docs: create README.md and AGENTS.md

Author: google-labs-jules[bot]

AGENTS.md

@@ -0,0 +1,76 @@
+# Agent Instructions for mcp-cli
+
+This document provides instructions for AI agents working on the `mcp-cli` codebase.
+
+## Project Overview
+
+`mcp-cli` is a command-line tool for testing Model Context Protocol (MCP) servers. It's written in Go and uses `cobra` for the command-line interface and `bubbletea` for the terminal user interface (TUI).
+
+The primary goal of this tool is to provide a user-friendly way to interact with MCP servers, select tools, provide arguments, and view results, all within the terminal.
+
+## Tech Stack
+
+-   **Go:** The programming language used for the project.
+-   **Cobra:** A library for creating powerful modern CLI applications in Go.
+-   **Bubble Tea:** A framework for building terminal user interfaces. It follows The Elm Architecture (Model-View-Update).
+-   **Lip Gloss:** A library for styling terminal output, used for the TUI layout.
+-   **Bubbles:** A library of ready-to-use components for Bubble Tea applications (e.g., `list`, `textinput`, `viewport`).
+
+## How to Build and Run
+
+-   **Build:** To build the executable, run:
+    ```sh
+    go build
+    ```
+    This will create an `mcp-cli` binary in the root directory.
+
+-   **Run:** The application has three main commands:
+    -   `mcp-cli stdio "<command>"`
+    -   `mcp-cli sse <url>`
+    -   `mcp-cli http <url>`
+
+-   **Debugging:** The `-v` or `--verbose` flag enables logging to a `debug.log` file. This is useful for debugging the TUI's behavior.
+
+## Code Structure
+
+All the application logic is contained in `main.go`.
+
+### Key Components
+
+-   **`AppModel`:** This is the main struct that holds the state of the application. It includes the current view, the list of tools, the input fields, the debug log, and the viewport for the debug panel.
+
+-   **`initialModel`:** This function initializes the `AppModel` when the application starts.
+
+-   **`Update` function:** This is the heart of the Bubble Tea application. It handles all incoming messages (key presses, window resize events, tool results) and updates the model accordingly. It follows a switch-case structure to handle different message types and application states.
+
+-   **`View` function:** This function is responsible for rendering the TUI based on the current state of the `AppModel`. It uses `lipgloss` to create a two-column layout, with the main content on the left and the debug panel on the right.
+
+-   **`logf` function:** A helper function on `AppModel` to append messages to the debug log and update the debug viewport. Use this function for all logging that should be visible in the debug panel.
+
+### TUI Views
+
+The application has three main views, represented by the `viewState` enum:
+
+1.  `toolSelectionView`: The initial view that shows a list of available tools.
+2.  `argumentInputView`: The view for entering arguments for a selected tool.
+3.  `resultView`: The view for displaying the result of a tool call.
+
+The debug panel is always visible on the right side of the screen.
+
+## Development Workflow
+
+1.  **Understand the Request:** Carefully read the user's request and identify the required changes.
+2.  **Explore the Code:** Use `read_file` to examine `main.go` and understand the current implementation.
+3.  **Formulate a Plan:** Create a clear, step-by-step plan to implement the changes.
+4.  **Implement Changes:** Use `replace_with_git_merge_diff` or other tools to modify the code.
+5.  **Test:** After making changes, run `go build` to ensure the code compiles.
+6.  **Review and Submit:** Use `request_code_review` to get feedback on your changes before submitting.
+
+## Important Considerations
+
+-   **State Management:** The `AppModel` is the single source of truth for the application's state. All changes to the UI should be a result of changes to the `AppModel`.
+-   **Pointer Receivers:** Methods on `AppModel` that modify its state (like `Update` and `logf`) must have a pointer receiver (`*AppModel`) to ensure the changes are applied to the original model.
+-   **Command Handling:** The `Update` function returns a `tea.Cmd`, which represents a command to be executed by the Bubble Tea runtime (e.g., waiting for a tool result). Be sure to handle and batch commands correctly.
+-   **Styling:** Use `lipgloss` for all TUI styling.
+-   **Dependencies:** Use `go mod tidy` to manage dependencies.
+-   **`.gitignore`:** The `mcp-cli` executable is ignored by `.gitignore`.

README.md

@@ -1 +1,101 @@
-# mcpc
+# MCP-CLI
+
+MCP-CLI is a command-line tool for interacting with and testing Model Context Protocol (MCP) servers. It provides a user-friendly terminal user interface (TUI) for selecting and executing tools offered by an MCP server.
+
+## Features
+
+- **Multiple Transports:** Connect to MCP servers using `stdio`, `sse` (Server-Sent Events), or `http` (streamable HTTP).
+- **Interactive TUI:** A terminal user interface built with `bubbletea` that allows you to:
+  - Select a tool from a list of available tools.
+  - Enter arguments for the selected tool in a form.
+  - View the results of the tool execution.
+- **Debug Panel:** A scrollable debug panel on the right side of the TUI that shows:
+  - Informational logs (key presses, state changes).
+  - The arguments sent to the tool in a pretty-printed JSON format.
+  - The results of tool calls.
+- **Verbose Logging:** Use the `-v` flag to enable verbose logging to a `debug.log` file for troubleshooting.
+
+## Installation
+
+You can install `mcp-cli` using `go install`:
+
+```sh
+go install mcp-cli
+```
+
+Alternatively, you can build it from source.
+
+## Building from Source
+
+1.  Clone the repository:
+    ```sh
+    git clone <repository-url>
+    cd mcp-cli
+    ```
+2.  Build the executable:
+    ```sh
+    go build
+    ```
+    This will create an `mcp-cli` executable in the current directory.
+
+## Usage
+
+The `mcp-cli` tool has three main commands, one for each transport protocol.
+
+### `stdio`
+
+Connect to an MCP server that communicates over standard input/output.
+
+```sh
+mcp-cli stdio "<command-to-start-server>"
+```
+
+**Example:**
+
+```sh
+mcp-cli stdio "python /path/to/mcp/server.py"
+```
+
+### `sse`
+
+Connect to an MCP server that uses Server-Sent Events (SSE).
+
+```sh
+mcp-cli sse <server-url>
+```
+
+**Example:**
+
+```sh
+mcp-cli sse http://localhost:8080/mcp
+```
+
+### `http`
+
+Connect to an MCP server that uses streamable HTTP.
+
+```sh
+mcp-cli http <server-url>
+```
+
+**Example:**
+
+```sh
+mcp-cli http http://localhost:8080/mcp
+```
+
+### Global Flags
+
+- `-v`, `--verbose`: Enable verbose logging to `debug.log`.
+
+## TUI Guide
+
+When you connect to an MCP server, you will be presented with a terminal user interface.
+
+-   **Tool Selection View:** A list of available tools. Use the arrow keys to navigate and press `Enter` to select a tool.
+-   **Argument Input View:** A form for entering the arguments for the selected tool. Use `Tab` to switch between fields and `Enter` to submit the tool call.
+-   **Result View:** Shows the result of the tool execution. Press `Enter` to return to the argument input view for the same tool, allowing you to easily call it again with different arguments.
+-   **Debug Panel:** The right-hand panel shows a scrollable log of events, tool calls, and results. Use the up and down arrow keys to scroll through the log.
+-   **Navigation:**
+    -   `Esc`: Return to the tool selection view.
+    -   `Ctrl+C`: Exit the application.