| philip.zeyliger | cebb03c | 2025-06-27 13:24:38 -0700 | [diff] [blame] | 1 | # mcp-tool |
| 2 | |
| 3 | A command-line tool for testing MCP (Model Context Protocol) servers. Uses the |
| 4 | same `mcp-go` library as Sketch to provide manual testing capabilities for MCP |
| 5 | server implementations. |
| 6 | |
| 7 | ## Usage |
| 8 | |
| 9 | ### Discover Tools |
| 10 | |
| 11 | List all tools available from an MCP server: |
| 12 | |
| 13 | ```bash |
| 14 | mcp-tool discover -mcp '{"name": "server-name", "type": "stdio", "command": "./server"}' |
| 15 | ``` |
| 16 | |
| 17 | ### Call Tools |
| 18 | |
| 19 | Invoke a specific tool on an MCP server: |
| 20 | |
| 21 | ```bash |
| 22 | mcp-tool call -mcp '{"name": "server-name", "type": "stdio", "command": "./server"}' tool_name '{"arg1": "value1"}' |
| 23 | ``` |
| 24 | |
| 25 | ## MCP Server Configuration |
| 26 | |
| 27 | The `-mcp` flag accepts a JSON configuration with the following fields: |
| 28 | |
| 29 | - `name` (required): Server name for identification |
| 30 | - `type`: Transport type - "stdio" (default), "http", or "sse" |
| 31 | - `command`: Command to run (for stdio transport) |
| 32 | - `args`: Array of command arguments (for stdio transport) |
| 33 | - `url`: Server URL (for http/sse transport) |
| 34 | - `env`: Environment variables as key-value pairs (for stdio transport) |
| 35 | - `headers`: HTTP headers as key-value pairs (for http/sse transport) |
| 36 | |
| 37 | ## Examples |
| 38 | |
| 39 | ### Stdio Transport |
| 40 | |
| 41 | ```bash |
| 42 | # Test a Python MCP server |
| 43 | mcp-tool discover -mcp '{"name": "python-server", "type": "stdio", "command": "python3", "args": ["server.py"]}' |
| 44 | |
| 45 | # Call a tool with arguments |
| 46 | mcp-tool call -mcp '{"name": "python-server", "type": "stdio", "command": "python3", "args": ["server.py"]}' list_files '{"path": "/tmp"}' |
| 47 | ``` |
| 48 | |
| 49 | ### HTTP Transport |
| 50 | |
| 51 | ```bash |
| 52 | # Discover tools from HTTP MCP server |
| 53 | mcp-tool discover -mcp '{"name": "http-server", "type": "http", "url": "http://localhost:8080/mcp"}' |
| 54 | |
| 55 | # Call with custom headers |
| 56 | mcp-tool call -mcp '{"name": "http-server", "type": "http", "url": "http://localhost:8080/mcp", "headers": {"Authorization": "Bearer token"}}' get_data '{}' |
| 57 | ``` |
| 58 | |
| 59 | ### SSE Transport |
| 60 | |
| 61 | ```bash |
| 62 | # Use Server-Sent Events transport |
| 63 | mcp-tool discover -mcp '{"name": "sse-server", "type": "sse", "url": "http://localhost:8080/mcp/sse"}' |
| 64 | ``` |
| 65 | |
| 66 | ## Options |
| 67 | |
| 68 | - `-v`: Verbose output for debugging |
| 69 | - `-timeout duration`: Connection timeout (default: 30s) |
| 70 | |
| 71 | ## Testing |
| 72 | |
| 73 | A test MCP server (`test-mcp-server.py`) is provided in the repository root for testing purposes. It implements basic tools like `echo`, `list_files`, and `get_env`: |
| 74 | |
| 75 | ```bash |
| 76 | # Start the test server and test it |
| 77 | mcp-tool discover -mcp '{"name": "test", "type": "stdio", "command": "python3", "args": ["test-mcp-server.py"]}' |
| 78 | mcp-tool call -mcp '{"name": "test", "type": "stdio", "command": "python3", "args": ["test-mcp-server.py"]}' echo '{"message": "Hello MCP!"}' |
| 79 | ``` |