MCP Probe (Pivot LLM)

MCPProbe

此实用程序用于测试MCP（模型上下文协议）服务器。MCPProbe枚举服务器功能并提供完整的工具调用功能，允许您直接从命令行执行MCP工具并查看其响应。

特性

• 多种运输方式：支持HTTP、SSE（服务器发送事件）和stdio连接
• 初始化握手：执行正确的MCP协议初始化
• 能力发现：服务器功能报告（工具、资源、提示）
• 工具调用：使用参数直接从命令行执行MCP工具
• 交互模式：用于探索和测试的引导式工具调用界面
• 详细输出：提供有关连接和服务器响应的详细信息
• 自定义标头：支持用于身份验证或其他目的的自定义HTTP标头

安装

# Clone the repository
git clone https://github.com/PivotLLM/MCPProbe.git
cd MCPProbe

# Build the application
go build -o mcp-probe

快速开始

# 1. Test server connectivity and see all capabilities (SSE)
./mcp-probe -url http://localhost:8000/sse

# 2. Test a local MCP server via stdio
./mcp-probe -stdio ./my-mcp-server

# 3. List tool names only (minimal output)
./mcp-probe -url http://localhost:8000/sse -list

# 4. List available tools with details
./mcp-probe -url http://localhost:8000/sse -list-only

# 5. Call a specific tool
./mcp-probe -url http://localhost:8000/sse -call "echo" -params '{"message":"Hello MCP!"}'

# 6. Interactive exploration
./mcp-probe -url http://localhost:8000/sse -interactive

使用模式

MCPProbe在五种模式下运行：

1.发现模式（默认）

测试MCP服务器并报告所有功能（工具、资源、提示）。

./mcp-probe -url 

2.列表模式（最小）

仅列出输出最小的工具名称：

./mcp-probe -url  -list

3.仅列出模式（详细）

列出带有描述和模式的可用工具：

./mcp-probe -url  -list-only

4.直接工具调用模式

使用提供的参数执行特定工具。

./mcp-probe -url  -call  -params ''

5.交互模式

为探索和测试工具提供了一个有指导的界面。

./mcp-probe -url  -interactive

命令行选项

注： 要么 -url 或 -stdio 必须提供。这 -headers 和 -transport 选项仅适用于基于URL的连接（SSE/HTTP）。

详细示例

认证

MCPProbe通过以下方式支持各种身份验证方法 -headers 标志：

承载令牌身份验证

# Bearer token
./mcp-probe -url http://api.example.com/mcp \
  -headers "Authorization:Bearer YOUR_TOKEN_HERE"

API密钥验证

# Standard X-API-Key header
./mcp-probe -url http://api.example.com/mcp \
  -headers "X-API-Key:sk-1234567890abcdef"

# Custom API key header
./mcp-probe -url http://api.example.com/mcp \
  -headers "Api-Token:your-secret-key"

基本认证

# Basic auth (base64 encoded username:password)
./mcp-probe -url http://api.example.com/mcp \
  -headers "Authorization:Basic dXNlcm5hbWU6cGFzc3dvcmQ="

多个标题

# Combine authentication with other headers
./mcp-probe -url http://api.example.com/mcp \
  -headers "Authorization:Bearer token123,X-API-Key:backup-key,Content-Type:application/json"

# API key with additional headers
./mcp-probe -url http://api.example.com/mcp \
  -headers "X-API-Key:secret,X-Client-ID:myclient,Accept:application/json"

自定义身份验证标头

# Custom authentication scheme
./mcp-probe -url http://api.example.com/mcp \
  -headers "X-Custom-Auth:custom-token-format"

# Multiple authentication methods (if server supports fallback)
./mcp-probe -url http://api.example.com/mcp \
  -headers "Authorization:Bearer primary-token,X-API-Key:fallback-key"

基本服务器测试

# Test an SSE server (default transport)
./mcp-probe -url http://localhost:8000/sse

# Test an HTTP server
./mcp-probe -url http://localhost:8000/mcp -transport http

# Test with extended timeout for slow servers
./mcp-probe -url http://localhost:8000/sse -timeout 60s

标准传输（本地服务器）

stdio传输允许您通过将本地MCP服务器生成为子进程并通过stdin/stdout进行通信来测试它们。

# Test a local MCP server binary
./mcp-probe -stdio ./my-mcp-server

# Test with arguments (comma-separated)
./mcp-probe -stdio python -args "-m,my_mcp_module"

# Test with arguments and environment variables
./mcp-probe -stdio ./my-server -args "--port,8080,--debug" -env "LOG_LEVEL=debug,API_KEY=secret"

# Interactive mode with a local server
./mcp-probe -stdio ./my-server -interactive

# Call a specific tool on a local server
./mcp-probe -stdio ./my-server -call "get_data" -params '{"id": 1}'

# Complex example: local server with auth proxy arguments
./mcp-probe -stdio ./mcprelay -args "-url,http://127.0.0.1:8888/sse,-headers,{\"Authorization\":\"Bearer YOUR_TOKEN\"}" -verbose

Stdio特定选项：

• `-stdio

`：MCP服务器可执行文件的路径

• -args ：传递给服务器的逗号分隔参数
• -env ：KEY=VALUE格式的逗号分隔环境变量

工具发现

# List tool names only (minimal output)
./mcp-probe -url http://localhost:8000/sse -list

# List all available tools with descriptions
./mcp-probe -url http://localhost:8000/sse -list-only

# List tools with full schema information
./mcp-probe -url http://localhost:8000/sse -list-only -verbose

# List tools from authenticated server
./mcp-probe -url http://api.example.com/mcp -list-only \
  -headers "Authorization:Bearer YOUR_TOKEN"

直接工具调用

# Call a tool without parameters
./mcp-probe -url http://localhost:8000/sse -call "get_time"

# Call with simple parameters
./mcp-probe -url http://localhost:8000/sse \
  -call "echo" \
  -params '{"message":"Hello, MCP!"}'

# Call with authentication
./mcp-probe -url http://api.example.com/mcp \
  -headers "Authorization:Bearer YOUR_TOKEN" \
  -call "get_user_data" \
  -params '{"user_id":"12345"}'

# Call with API key authentication
./mcp-probe -url http://api.example.com/mcp \
  -headers "X-API-Key:your-api-key" \
  -call "fetch_records" \
  -params '{"limit":10}'

# Call with numeric parameters
./mcp-probe -url http://localhost:8000/sse \
  -call "calculate" \
  -params '{"operation":"multiply","x":7,"y":9}'

# Call with complex nested parameters
./mcp-probe -url http://localhost:8000/sse \
  -call "search_documents" \
  -params '{"query":"machine learning","filters":{"type":"pdf","date_range":{"start":"2024-01-01","end":"2024-12-31"},"max_results":10}}'

# Call with array parameters
./mcp-probe -url http://localhost:8000/sse \
  -call "process_batch" \
  -params '{"items":["item1","item2","item3"],"options":{"parallel":true}}'

# Call with extended timeout for long-running tools
./mcp-probe -url http://localhost:8000/sse \
  -call "analyze_large_dataset" \
  -params '{"dataset_id":"12345"}' \
  -call-timeout 10m

交互模式

# Start interactive mode
./mcp-probe -url http://localhost:8000/sse -interactive

# Interactive mode with authentication
./mcp-probe -url http://api.example.com/mcp -interactive \
  -headers "Authorization:Bearer YOUR_TOKEN"

# Interactive mode with extended tool timeout for long operations
./mcp-probe -url http://localhost:8000/sse -interactive -call-timeout 10m

交互模式命令：

• list 或 ls -显示所有可用工具
• call 或 c -启动引导式工具调用流程
• 1, 2, 3…-直接按号码呼叫工具
• help 或 h -显示可用命令
• exit 或 quit -退出交互模式

交互模式示例会话：

=== Interactive Tool Calling Mode ===
Type 'help' for commands, 'exit' to quit

> list

Available tools (3):
  1. echo - Returns the input message
  2. calculate - Performs arithmetic operations
  3. get_weather - Gets weather for a city

> 1

Calling tool: echo
Description: Returns the input message

Enter parameters (press Enter to skip optional parameters):
  message (The message to echo) [required]: Hello from interactive mode!

Calling tool 'echo'...

=== Tool Call Result ===
Tool call succeeded:

Hello from interactive mode!

> exit
Exiting interactive mode...

真实世界的例子

测试文件系统MCP服务器

# List files in a directory
./mcp-probe -url http://localhost:8000/sse \
  -call "list_directory" \
  -params '{"path":"/home/user/documents","recursive":false}'

# Read a file
./mcp-probe -url http://localhost:8000/sse \
  -call "read_file" \
  -params '{"path":"/home/user/documents/readme.txt"}'

测试数据库MCP服务器

# Execute a query
./mcp-probe -url http://localhost:8000/sse \
  -call "execute_query" \
  -params '{"query":"SELECT * FROM users WHERE active = true","limit":10}'

测试AI/LLM MCP服务器

# Generate text
./mcp-probe -url http://localhost:8000/sse \
  -call "generate_text" \
  -params '{"prompt":"Write a haiku about programming","max_tokens":50,"temperature":0.7}'

输出格式

MCPProbe为不同模式提供清晰、结构化的输出：

发现模式输出

=== MCP Server Test Tool ===
Server URL: http://localhost:8000/sse
Transport: sse
Timeout: 30s

Creating SSE client...
Starting client connection...
Client connection started successfully

Performing initialization handshake...
Server info: ExampleMCP v1.0.0
Protocol version: 2024-11-05

Server capabilities received:
  - Tools: supported (list_changed: true)
  - Resources: supported (subscribe: false, list_changed: true)

Initialization completed successfully

--- Tools Capability ---
Requesting list of available tools...
Found 2 tools:

  1. echo
     Description: Returns the input message
     Input Schema: {...}

  2. calculate
     Description: Performs basic arithmetic
     Input Schema: {...}

=== Finished ===

工具调用输出

=== Sending Tool Call ===
Tool: calculate
Parameters:
  operation: add (string)
  x: 5 (float64)
  y: 3 (float64)

Calling tool 'calculate'...

=== Tool Call Result ===
Tool call succeeded:

The result of 5 + 3 is 8

错误输出

Failed to call tool 'nonexistent':
   Tool 'nonexistent' not found. Use -list-only to see available tools.

故障排除

常见问题

连接被拒绝

# Error: dial tcp [::1]:8000: connect: connection refused
# Solution: Ensure the MCP server is running on the specified URL

工具名称无效

# Error: Tool 'badname' not found
# Solution: Use -list-only to see available tools
./mcp-probe -url http://localhost:8000/sse -list-only

JSON参数无效

# Error: failed to parse parameters JSON: invalid character
# Solution: Ensure JSON is properly quoted and formatted
./mcp-probe -url http://localhost:8000/sse -call "echo" -params '{"message":"test"}'

超时问题

# Error: context deadline exceeded during initialization/connection
# Solution: Increase connection timeout for slow servers
./mcp-probe -url http://localhost:8000/sse -timeout 60s

# Error: context deadline exceeded during tool call
# Solution: Increase tool call timeout for long-running tools
./mcp-probe -url http://localhost:8000/sse -call "long_task" -call-timeout 10m

# Both timeouts can be adjusted independently
./mcp-probe -url http://localhost:8000/sse -timeout 60s -call-timeout 15m -interactive

了解超时：

• -timeout （默认30秒）：控制连接、初始化和列表操作
• -call-timeout （默认300s/5m）：控制工具执行可以运行多长时间

调试提示

1. 使用详细模式 查看详细的请求/响应信息
2. 首先测试连接性 在调用工具之前使用发现模式
3. 验证JSON 使用JSON验证器的参数
4. 检查服务器日志 有关其他错误信息
5. 使用交互模式 安全地探索工具

JSON参数指南

MCPProbe接受JSON字符串形式的工具参数。以下是格式化指南：

基本类型

# String parameters
-params '{"name":"John Doe","city":"New York"}'

# Numeric parameters
-params '{"count":42,"price":19.99,"temperature":-5}'

# Boolean parameters
-params '{"enabled":true,"debug":false}'

# Null values
-params '{"optional_field":null}'

复杂结构

# Arrays
-params '{"tags":["urgent","important"],"scores":[85,92,78]}'

# Nested objects
-params '{"user":{"name":"Alice","age":30,"preferences":{"theme":"dark"}}}'

# Mixed complex structure
-params '{"query":"search term","filters":{"categories":["tech","science"],"date_range":{"start":"2024-01-01","end":"2024-12-31"}},"options":{"max_results":10,"sort_by":"relevance"}}'

壳牌逃逸

不同的shell处理引号的方式不同：

Bash/Zsh（Linux/macOS）

# Use single quotes to wrap the JSON
-params '{"message":"Hello World"}'

# Escape inner quotes if needed
-params '{"message":"Say \"Hello\""}'

Windows命令提示符

# Use double quotes and escape inner quotes
-params "{\"message\":\"Hello World\"}"

PowerShell

# Use single quotes or escape double quotes
-params '{"message":"Hello World"}'
# OR
-params "{`"message`":`"Hello World`"}"

依赖项

• -Go实现模型上下文协议

版权和许可

版权所有（c）2025-2026 Tenebris Technologies股份有限公司本软件获得麻省理工学院许可。请参阅许可证以了解详细信息。

无担保（零、无、无效、无、空、“”、｛｝、0x00、0b000000000、EOF）

本软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权保证。在任何情况下，版权持有人或贡献者均不对因使用本软件而以任何方式产生的任何直接、间接、附带、特殊、惩戒性或后果性损害（包括但不限于采购替代商品或服务；使用、数据或利润损失；或业务中断）承担责任，无论是基于何种责任理论，无论是合同、严格责任还是侵权（包括疏忽或其他），即使被告知此类损害的可能性。

加拿大制造