STARWARCLOUD STARWAR.AI
返回市场
MCP测试MCP

MCP测试MCP

作者：rdwj2 星标更新：2025-10-29
安装使用来源：spider==github.com

项目介绍

mcp-test-mcp

Python 版本 许可证: MIT

概述

mcp-test-mcp 是一个专门的 MCP（模型上下文协议）服务器，帮助 AI 助手测试其他 MCP 服务器。它解决了“循环中断”问题，即 AI 助手在测试自身 MCP 能力时遇到困难，因为它们无法看到自己的工具模式或执行结果。

可以将其视为一个测试框架，通过提供 AI 助手所需的可见性和控制能力，使 MCP 服务器的开发和调试变得容易得多。

架构：双服务器/客户端设计

mcp-test-mcp 具有独特的双重角色架构，专为测试而设计：

双重性质

┌─────────────────────────────────────────────────────────────────────┐
│                        测试流程                                      │
└─────────────────────────────────────────────────────────────────────┘

用户/开发者
    │
    ├─► Claude Desktop/Code (MCP 客户端)
            │
            ├─► mcp-test-mcp (MCP 服务器角色)
            │   └─ 通过 MCP 协议暴露测试工具
            │      • connect_to_server
            │      • list_tools, call_tool
            │      • list_resources, read_resource
            │      • list_prompts, get_prompt
            │      • execute_prompt_with_llm
            │
            ├─► mcp-test-mcp (MCP 客户端角色)
                    │
                    └─► 目标 MCP 服务器 (被测试的服务器)
                        └─ 正在开发/调试的服务器

为什么这种设计？

服务器和客户端功能之间的耦合是有意为之且经过设计的：

  1. 服务器角色：作为 MCP 工具暴露测试能力，Claude 可以调用这些工具。
  2. 客户端角色：连接到目标 MCP 服务器以测试其功能。
  3. 统一目的：这些工具需要客户端功能才能工作——它们测试其他 MCP 服务器。

这不是两个独立的关注点偶然合并的结果，而是一个测试框架，其中服务器角色将客户端能力作为可测试工具暴露出来。

代码组织

代码库反映了这种双重角色：

  • src/mcp_test_mcp/server.py：FastMCP 服务器实例（向 Claude 暴露工具）
  • src/mcp_test_mcp/connection.py：ConnectionManager（目标服务器的 MCP 客户端）
  • src/mcp_test_mcp/tools/：桥接服务器和客户端角色的工具实现
    • connection.py：连接管理工具（使用 ConnectionManager）
    • tools.py：工具测试工具（调用目标服务器的工具）
    • resources.py：资源测试工具（读取目标服务器的资源）
    • prompts.py：提示测试工具（获取目标服务器的提示）
    • llm.py：LLM 集成（使用实际 LLM 执行提示）

关键见解

当你在 Claude 中调用 connect_to_server 工具时，实际上是：

  1. 调用 mcp-test-mcp 的 MCP 工具（服务器角色）
  2. 内部使用 ConnectionManager 作为客户端连接
  3. 到你想要测试的 目标 MCP 服务器

这使得测试 MCP 服务器变得自然：Claude 调用工具，这些工具测试其他服务器。

问题：循环中断

在开发 MCP 服务器时，测试可能会令人沮丧。AI 助手不能与未配置的 MCP 服务器交互进行测试，有时会导致它们错误地认为工作的 MCP 代码是故障的，并通过转换为 REST/WebSocket 模式来“修复”它。

通过提供 AI 助手可以调用的原生 MCP 测试能力，mcp-test-mcp 防止了破坏性的“循环中断”，其中 AI 尝试 curl 命令失败后重写正常工作的代码。相反，AI 可以连接到用户正在开发的 MCP 服务器，列出其工具/资源/提示及其完整的模式，并执行测试调用——所有这些都是通过适当的 MCP 协议通信完成的。这使得快速验证部署的 MCP 服务器成为可能，并支持构建自信地消费 MCP 服务的代理。

MVP 专注于测试部署的 MCP 服务器（流式传输-http 运输），具有详细的可验证响应，防止 AI 幻想并允许人类验证结果的真实性。

mcp-test-mcp 解决了这个问题，通过为 AI 助手提供专用工具来：

  • 连接到目标 MCP 服务器
  • 发现所有可用的工具、资源和提示及其完整模式
  • 执行工具并查看详细的、详尽的结果
  • 跟踪统计信息和连接状态
  • 排查连接和执行问题

这创建了一个测试工作流程，AI 助手可以有效地测试 MCP 服务器，清晰地报告问题，并全面验证功能。

主要特性

连接管理

  • 连接到任何 MCP 服务器（STDIO 或 HTTP/流式传输-http 运输）
  • 自动检测传输协议
  • 跟踪连接状态和统计信息
  • 清洁断开连接和重新连接

工具测试

  • 列出所有工具及其完整的输入模式
  • 使用任意参数调用工具
  • 获取详细的执行结果及其时间
  • 查看结构化的错误消息

资源测试

  • 列出所有可用资源及其元数据
  • 读取资源内容（文本和二进制）
  • 跟踪 MIME 类型和内容大小

提示测试

  • 列出所有提示及其参数模式
  • 获取带有自定义参数的渲染提示
  • 查看完整的消息结构

🎯 LLM 集成 (新！)

  • 完整的端到端提示测试，使用实际 LLM 执行
  • 双模式支持：
    • 标准 MCP 提示（服务器端参数替换）
    • 模板变量填充（客户端 {占位符} 替换）
  • 自动 JSON 提取从 Markdown 代码块
  • 全面指标：令牌使用量、时间和性能数据
  • 灵活的 LLM 配置：支持任何兼容 OpenAI 的 API

综合错误处理

  • 详细的错误类型（未连接、工具未找到等）
  • 上下文错误消息
  • 可操作的解决建议
  • 用于调试的完整错误元数据

详细输出

  • 连接统计信息（调用的工具、访问的资源等）
  • 请求计时信息
  • 服务器功能和元数据
  • 执行持续时间跟踪

要求

  • Python 3.11 或更高版本
  • FastMCP v2.12.4+
  • Pydantic v2.12.0+
  • python-dotenv v1.0.0+（用于 .env 文件支持）
  • httpx v0.27.0+（用于 LLM API 调用）

安装

与 Claude Desktop / Claude Code 一起使用（推荐）

最简单的方法是使用 Claude Desktop 或 Claude Code。只需将其添加到您的 MCP 配置文件中：

配置文件位置：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%/Claude/claude_desktop_config.json

使用 npx（推荐 - 不需要安装）：

基本配置（大多数用户）：

{
  "mcpServers": {
    "mcp-test-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-test-mcp"]
    }
  }
}

带 LLM 集成（可选）：

{
  "mcpServers": {
    "mcp-test-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-test-mcp"],
      "env": {
        "LLM_URL": "https://your-llm-endpoint.com/v1",
        "LLM_MODEL_NAME": "your-model-name",
        "LLM_API_KEY": "your-api-key"
      }
    }
  }
}

使用 Claude Code CLI：

claude mcp add mcp-test-mcp -- npx -y mcp-test-mcp

前提条件：

  • Node.js 16+（用于 npx）
  • Python 3.11+（安装期间自动检测）

npm 包会自动：

  1. 检测系统上的 Python 3.11+
  2. 创建虚拟环境
  3. 安装所有 Python 依赖项

关于 LLM 配置的注意事项： env 部分是完全可选的。服务器和所有测试工具无需它也能运行。只有当您希望使用 execute_prompt_with_llm 工具进行端到端提示测试时才需要 LLM 配置。所有其他工具（连接、list_tools、call_tool、list_resources、list_prompts 等）无需任何 LLM 配置即可运行。

添加此配置后，请重启 Claude Code/Desktop 以使更改生效。

本地开发 / 独立使用

如果您希望直接开发或运行 mcp-test-mcp（不在 Claude 中）：

使用 pip：

# 首先创建虚拟环境（必需）
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安装包
pip install mcp-test-mcp

从源码：

# 克隆仓库
git clone https://github.com/example/mcp-test-mcp
cd mcp-test-mcp

# 创建并激活虚拟环境（必需）
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 使用开发依赖项安装
pip install -e ".[dev]"

使用标准 Python 与 Claude（替代方案）：

如果您更喜欢使用 pip 安装的 Python 而不是 npx：

基本配置：

{
  "mcpServers": {
    "mcp-test-mcp": {
      "command": "python",
      "args": ["-m", "mcp_test_mcp"]
    }
  }
}

带 LLM 集成（可选）：

{
  服务器": {
    "mcp-test-mcp": {
      "command": "python",
      "args": ["-m", "mcp_test_mcp"],
      "env": {
        "LLM_URL": "https://your-llm-endpoint.com/v1",
        "LLM_MODEL_NAME": "your-model-name",
        "LLM_API_KEY": "your-api-key"
      }
    }
  }
}

配置

配置说明已移至上面的 安装 部分。选择最适合您需求的安装方法：

LLM 集成配置（可选）

execute_prompt_with_llm 工具需要 LLM 配置才能工作。所有其他工具无需任何 LLM 设置即可运行。

对于 Claude Desktop/Code 用户：

在您的 MCP 配置中添加 env 部分（参见上面安装部分中的示例）：

"env": {
  "LLM_URL": "https://your-llm-endpoint.com/v1",
  "LLM_MODEL_NAME": "your-model-name",
  "LLM_API_KEY": "your-api-key"
}

对于独立/本地开发：

在项目根目录创建一个 .env 文件：

# .env 文件
LLM_URL=https://your-llm-endpoint.com/v1
LLM_MODEL_NAME=your-model-name
LLM_API_KEY=your-api-key

该工具支持任何兼容 OpenAI 的 API 端点（包括 OpenAI、Azure OpenAI、通过 vLLM/Ollama 的本地模型以及企业端点）。

快速入门

配置完成后，您可以立即开始通过与 Claude 的自然对话测试 MCP 服务器：

1. 连接到服务器

用户："连接到我的本地 MCP 服务器 /path/to/server"

Claude 将：使用 connect_to_server 工具并显示：

  • 连接成功/失败
  • 传输类型（stdio 或流式传输-http）
  • 服务器信息（名称、版本、功能）
  • 连接计时

2. 发现工具

用户："它有哪些工具？"

Claude 将：使用 list_tools 工具并显示：

  • 所有可用工具的名称
  • 完整描述
  • 每个工具的完整输入模式

3. 测试工具

用户："测试带有消息 'Hello MCP' 的 echo 工具"

Claude 将：使用 call_tool 工具并显示：

  • 工具执行结果
  • 执行时间
  • 成功/失败状态
  • 更新的统计信息

4. 检查状态

用户："连接状态如何？"

Claude 将：使用 get_connection_status 工具并显示：

  • 当前服务器 URL
  • 连接持续时间
  • 统计信息（调用的工具、访问的资源、错误）

5. 使用 LLM 测试 (新！)

用户："使用 LLM 执行带有该数据的 weather_report 提示"

Claude 将：使用 execute_prompt_with_llm 工具并显示：

  • 提示检索和变量替换
  • LLM 请求和响应
  • 自动解析的 JSON（如果适用）
  • 令牌使用量和计时指标

6. 断开连接

用户："从服务器断开连接"

Claude 将：使用 disconnect 工具并确认断开连接，同时显示最终统计信息。

可用工具

mcp-test-mcp 提供14 个工具，按功能类别组织：

连接管理（3 个工具）

  • connect_to_server：建立到目标 MCP 服务器的连接
    • 支持 stdio（文件路径）和流式传输-http（URL）
    • 返回连接状态和服务器功能
  • disconnect：干净地关闭活动连接
    • 返回最终统计信息
  • get_connection_status：检查当前连接状态
    • 显示连接持续时间和使用统计信息

工具测试（2 个工具）

  • list_tools：发现所有工具及其完整模式
    • 返回工具名称、描述和输入模式
  • call_tool：使用指定参数执行工具
    • 返回执行结果和时间
    • 跟踪工具使用统计信息

资源测试（2 个工具）

  • list_resources：发现所有资源及其元数据
    • 返回 URI、名称、描述和 MIME 类型
  • read_resource：通过 URI 读取资源内容
    • 支持文本和二进制内容
    • 返回内容及其大小和时间

提示测试（2 个工具）

  • list_prompts：发现所有提示及其参数模式
    • 返回提示名称、描述和所需参数
  • get_prompt：获取带有参数的渲染提示
    • 返回完整的消息结构
    • 跟踪提示使用统计信息

LLM 集成（1 个工具） (新！)

  • execute_prompt_with_llm：使用 LLM 进行完整的端到端提示测试
    • 从连接的 MCP 服务器检索提示
    • 支持标准 MCP 提示和模板变量填充
    • 使用实际 LLM 推理执行提示
    • 返回结构化响应及其时间和令牌使用量
    • 自动从 Markdown 代码块提取 JSON
    • 详见 TESTING_GUIDE.md 中的详细示例

实用工具（4 个工具）

  • health_check：验证服务器是否运行
  • ping：测试基本连通性（返回 "pong"）
  • echo：回显一条消息
  • add：加两个数（用于测试基本工具调用）

常见工作流程

测试新的 MCP 服务器

1. 连接 → 检查连接状态
2. 列出工具 → 了解可用功能
3. 调用每个工具 → 验证行为
4. 列出资源 → 检查资源功能
5. 读取资源 → 验证内容
6. 列出提示 → 检查提示模板
7. 获取提示 → 验证渲染
8. 使用 LLM 执行提示 → 测试端到端（新！）
9. 断开连接 → 清洁关闭

端到端 LLM 测试 (新！)

1. 连接到 MCP 服务器
2. 调用工具获取数据（例如，get_weather）
3. 使用 execute_prompt_with_llm 和数据执行提示
4. 验证 LLM 生成预期输出格式
5. 检查令牌使用量和性能指标

排查连接问题

1. 尝试使用详细输出连接
2. 检查特定问题的错误消息
3. 验证传输类型（stdio 对比 HTTP）
4. 检查服务器日志以获取更多上下文
5. 使用 health_check 和 ping 测试基本连通性

验证工具模式

1. 连接到服务器
2. 列出工具以获取完整模式
3. 与预期模式进行比较
4. 使用各种参数测试边缘情况
5. 验证无效输入的错误处理