MCP Probe

MCP探头

全面的验证和测试框架 模型上下文协议 （MCP）服务器。

MCP Probe连接到您的MCP服务器，发现其工具/资源/提示，并运行一系列测试，涵盖协议一致性、模式验证、执行正确性、错误处理、边缘情况和可选的人工智能语义评估。结果以字母等级（a-F）报告，并附有详细的每次测试明细。

演示

观看完整的演示视频

  MCP Probe v0.1.0

  Servers: 1
  Suites:  protocol, schema, execution, error-handling, edge-cases

  my-server: B (86%) — 63/73 passed

  Summary
  Duration: 19057ms
  63 passed, 10 failed, 0 skipped

______________________________________________________________________

目录

• 特性
• 项目结构
• 快速开始
• CLI使用情况
• 仪表盘
• 配置
• 测试套件
• AI评估套件
• 程序化API
• 插件系统
• 报告架构
• 建筑

______________________________________________________________________

特性

• 8个内置测试套件 涵盖协议、模式、执行、错误处理、边缘情况、安全性、性能和人工智能评估
• 多个传输 --stdio、HTTP和SSE
• 认证 -承载令牌、API密钥和带PKCE自动解密的OAuth 2.0
• CLI+仪表板 --从终端或通过交互式web UI运行测试
• 基于人工智能的评估 （可选）--使用Claude或OpenAI生成真实的参数，检测隐藏的故障，评估描述质量，并分析工具的可发现性
• 分级记分卡 --A/B/C/D/F等级，每台服务器的百分比分数
• 实时进度 --仪表板中基于SSE的实时流媒体
• 可扩展 --用于自定义断言、报告器和副作用跟踪的插件系统
• 安全扫描 --快速注入、凭证暴露、SSRF、路径遍历、工具中毒检测
• 性能基准测试 （可选）——P50/P95/P99延迟、吞吐量（RPS）、黄金信号饱和测试
• CI友好 --JSON/HTML/JUnit报告， --fail-under 分级门控， compare 回归检测，故障时的非零退出码

______________________________________________________________________

项目结构

MCP-Integ/
├── mcp-probe/                    # Core testing library (TypeScript, ES modules)
│   ├── src/
│   │   ├── cli/                  # CLI entry point (test, inspect, validate-config)
│   │   ├── config/               # Zod-based configuration schema and loader
│   │   ├── client/               # MCP client (high-level, raw, task-based)
│   │   ├── transport/            # Stdio, HTTP, SSE transports
│   │   ├── llm/                  # LLM client (Anthropic + OpenAI), prompts
│   │   ├── suite/                # Test suites
│   │   │   ├── protocol/         #   Protocol conformance
│   │   │   ├── schema/           #   Schema validation and fuzzing
│   │   │   ├── execution/        #   Tool/resource/prompt execution
│   │   │   ├── error-handling/   #   Error code and invalid request handling
│   │   │   ├── edge-cases/       #   Boundary values and concurrency
│   │   │   └── ai-evaluation/    #   LLM-powered semantic evaluation
│   │   ├── runner/               # Test orchestrator with concurrency control
│   │   ├── reporter/             # JSON and HTML report generators
│   │   ├── plugin/               # Plugin interface and types
│   │   └── index.ts              # Public API exports
│   ├── dist/                     # Compiled JavaScript output
│   └── package.json
│
├── mcp-probe-dashboard/          # Next.js web dashboard
│   ├── src/
│   │   ├── app/                  # Pages and API routes
│   │   │   ├── api/
│   │   │   │   ├── servers/      #   Server CRUD
│   │   │   │   ├── runs/         #   Test run management + SSE streaming
│   │   │   │   ├── llm-config/   #   LLM judge settings + connection test
│   │   │   │   ├── oauth/        #   OAuth 2.0 flow (discover, start, callback)
│   │   │   │   ├── inspect/      #   Server capability inspection
│   │   │   │   └── validate/     #   Config validation
│   │   │   ├── servers/          #   Server management page
│   │   │   └── runs/             #   Run history and detail pages
│   │   ├── components/           # UI components
│   │   │   ├── ServerForm.tsx    #   Server configuration form
│   │   │   ├── LLMSettings.tsx   #   AI evaluation settings panel
│   │   │   ├── LiveProgress.tsx  #   Real-time test progress
│   │   │   ├── TestResultTree.tsx#   Expandable test result tree
│   │   │   ├── RunSummary.tsx    #   Run overview with grade chart
│   │   │   └── ScoreCard.tsx     #   Letter grade display
│   │   └── lib/                  # Backend utilities
│   │       ├── probe-client.ts   #   Bridges dashboard to mcp-probe core
│   │       ├── run-store.ts      #   Run state persistence
│   │       ├── server-store.ts   #   Server config persistence
│   │       ├── llm-store.ts      #   LLM config persistence
│   │       └── event-emitter.ts  #   SSE event bus
│   └── package.json
│
└── .env                          # Environment variables (API keys)

______________________________________________________________________

快速开始

先决条件

• Node.js >= 20.0.0
• 要测试的MCP服务器（基于stdio或基于HTTP）

安装和构建

# Clone the repository
git clone  && cd MCP-Integ

# Install core library
cd mcp-probe
npm install
npm run build

# Install dashboard
cd ../mcp-probe-dashboard
npm install

通过CLI运行

# Create a config file
cp mcp-probe/mcp-probe.example.yaml mcp-probe.yaml
# Edit mcp-probe.yaml with your server details

# Run tests
cd mcp-probe
npx mcp-probe test ../mcp-probe.yaml

# Inspect server capabilities
npx mcp-probe inspect ../mcp-probe.yaml

通过仪表板运行

cd mcp-probe-dashboard
npm run dev
# Open http://localhost:3000

1. 首选 服务器 并添加您的MCP服务器（stdio或HTTP端点）
2. 返回到 仪表盘 然后单击 测试所有服务器
3. 实时观看结果流
4. 点击任何运行，通过输入/预期/实际选项卡查看详细的测试结果

______________________________________________________________________

CLI使用情况

mcp-probe  [options]

Commands:
  test               Run validation tests against MCP servers
  inspect            Discover and display server capabilities
  validate-config      Validate a config file without running tests

Options (test):
  --verbose                  Show detailed JSON-RPC traces
  --filter 
         Run only tests matching this pattern
  --format           Output format: json, html, both (default: json)
  --output-dir          Output directory for reports
  --max-concurrent        Max parallel servers

示例：

# Run all suites against all servers
npx mcp-probe test config.yaml

# Run only protocol and schema suites
npx mcp-probe test config.yaml --filter protocol

# Generate HTML report
npx mcp-probe test config.yaml --format html

# Inspect a specific tool
npx mcp-probe inspect config.yaml --tool my_tool_name

# Validate config without running
npx mcp-probe validate-config config.yaml

退出代码：

• 0 --所有服务器均已通过
• 1 --一个或多个服务器发生故障（F级）或连接错误
• 2 --配置错误

______________________________________________________________________

仪表盘

仪表板是一个Next.js应用程序，它为管理服务器、运行测试和探索结果提供了一个可视化界面。

页面

主要特点

• 服务器管理 -使用可选身份验证（Bearer、API密钥、OAuth）配置stdio、HTTP或SSE服务器
• OAuth自动发现 --从MCP服务器元数据中自动发现OAuth端点
• 实时进度 --SSE提供通过/失败计数器的实时测试进度
• 测试结果树 --可扩展的树视图，显示每个具有颜色编码严重性的断言
• 元数据选项卡 --每个测试的输入、预期、实际和LLM选项卡显示了完整的JSON-RPC请求/响应
• 分数等级 --视觉等级（A-F），每台服务器的百分比

API路线

______________________________________________________________________

配置

配置是YAML或JSON。以下是一个完整的示例：

version: "1"

servers:
  # Stdio server (spawns a process)
  - name: my-filesystem-server
    transport:
      type: stdio
      command: mcp-server-filesystem
      args: ["/tmp/test"]
      cwd: /home/user
      env:
        DEBUG: "true"

  # HTTP server with bearer auth
  - name: my-api-server
    transport:
      type: http
      url: https://example.com/mcp/message
      headers:
        X-Custom: value
    auth:
      type: bearer
      token: { env: "MCP_AUTH_TOKEN" }    # reads from environment variable
    timeout:
      request: 10000     # per-request timeout (ms)
      test: 60000        # per-test timeout (ms)

  # HTTP server with API key auth
  - name: my-keyed-server
    transport:
      type: http
      url: https://api.example.com/mcp
    auth:
      type: apikey
      header: X-API-Key
      key: my-secret-key

  # Tool safety overrides
  - name: my-db-server
    transport:
      type: stdio
      command: node
      args: ["./db-server.js"]
    toolSafety:
      readOnly: ["query", "list_tables"]
      write: ["execute_sql", "drop_table"]

# Which test suites to run
suites:
  include:
    - protocol
    - schema
    - execution
    - error-handling
    - edge-cases
    # - ai-evaluation      # uncomment when LLM judge is configured
  exclude: []

# Global defaults
defaults:
  timeout:
    request: 30000
    test: 300000
  maxConcurrent: 5
  maxOutputBytes: 1048576
  allowWriteFuzzing: false

# Report output
output:
  format: json            # json | html | junit
  dir: ./mcp-probe-results

# Optional: LLM-powered evaluation
llmJudge:
  enabled: false
  baseUrl: https://api.anthropic.com
  apiKey: { env: "ANTHROPIC_API_KEY" }
  model: claude-sonnet-4-20250514
  maxTokens: 1024

身份验证类型

所有机密字段都支持环境变量引用： { env: "MY_SECRET" }.

______________________________________________________________________

测试套件

1.议定书(protocol)

测试MCP协议一致性和生命周期管理。

2.模式(schema)

验证工具输入模式和文档质量。

3.执行(execution)

调用工具，读取资源，并使用有效参数呈现提示。

4.错误处理(error-handling)

发送无效请求以验证正确的错误响应。

5.边缘案例(edge-cases)

测试边界条件和并发访问。

6.人工智能评估(ai-evaluation)

LLM支持语义评估。 可选的 -需要Anthropic或OpenAI的API密钥。看 AI评估套件 在......下面

______________________________________________________________________

AI评估套件

AI评估套件使用LLM（Claude或任何与OpenAI兼容的模型）来执行超越结构测试的语义分析。它完全是可选的，不会影响其他五间套房。

为什么？

标准协议测试只能检查结构。返回的工具 isError: false 带有正文 "Mandatory path variable bill_id is not present" 通过 结构测试，但有 实际上失败了人工智能评估套件捕捉到了这些隐藏的故障。

四种测试类别

智能参数生成

LLM读取每个工具的模式和描述，生成逼真的参数（看起来真实的ID、合理的地址、有意义的文本），调用工具，然后从语义上评估响应。

  PASS: Generated args with reasoning: Created a realistic bill comment
        scenario about an urgent invoice follow-up
  PASS: Tool responded in 979ms
  FAIL: Response contains error message despite isError=false

响应验证（隐藏故障检测）

使用标准伪参数调用每个工具，并将响应发送到LLM。LLM检测以下情况 isError: false 但响应文本描述了实际错误。

  FAIL: Hidden failure detected — Response states 'Mandatory path variable
        bill_id is not present' despite isError being false
  LLM verdict: failure (confidence: 10/10)

描述质量评分

LLM以1-10的评分标准对每个工具的描述质量进行评分，确定具体问题，并提出改进建议。

  Score 6/10 (needs improvement)
  Issues:
    - 'description' parameter talks about 'line item' details, confusing for a comment function
    - No examples provided for any parameters
    - Missing information about authentication or permissions
  Suggestions:
    - Clarify that 'description' is the comment text, not line item details
    - Add examples: 'description': 'Approved by finance team on 2024-01-15'

工具集可发现性

分析整个工具集的命名一致性、混淆的配对和组织问题。

  Score 7/10 — tools are well-organized
  WARNING: Both add_bill_attachment and add_journal_attachment add attachments
           but to different document types — an AI might struggle to distinguish

设置

通过仪表板：

1. 打开仪表板并展开 人工智能评估（法学硕士评委） 部分
2. 启用切换
3. 选择您的提供商（Anthropic或OpenAI）
4. 输入您的API密钥
5. 点击 测试连接 验证
6. 运行测试——ai评估套件将自动出现

通过配置文件：

llmJudge:
  enabled: true
  baseUrl: https://api.anthropic.com     # or https://api.openai.com/v1
  apiKey: { env: "ANTHROPIC_API_KEY" }
  model: claude-sonnet-4-20250514            # or gpt-4o-mini
  maxTokens: 1024

suites:
  include:
    - protocol
    - schema
    - execution
    - error-handling
    - edge-cases
    - ai-evaluation

成本

每个工具的成本约为 3个LLM电话 （arg生成+响应验证+描述质量）+ 1个电话 用于跨工具集的可发现性分析。总计： 3N+1次通话 N工具。

提供商自动检测

LLM客户端自动检测来自的提供程序 baseUrl:

• 包含 anthropic.com --本机使用Anthropic SDK(@anthropic-ai/sdk)
• 其他任何东西——使用与OpenAI兼容的 chat/completions 端点通过 fetch

这支持Anthropic、OpenAI、Azure OpenAI、Ollama和任何其他兼容OpenAI的提供商。

______________________________________________________________________

程序化API

使用 mcp-probe 作为你自己的Node.js代码中的库：

import { run, loadConfig } from 'mcp-probe';

const config = loadConfig('./mcp-probe.yaml');

const report = await run({
  config,
  onServerStart(name) {
    console.log(`Testing ${name}...`);
  },
  onServerEnd(name, serverReport) {
    console.log(`${name}: ${serverReport.score?.grade} (${serverReport.score?.percentage}%)`);
  },
  onTestEnd(result) {
    console.log(`  ${result.status}: ${result.testName}`);
  },
});

// report.servers[0].score => { grade: 'B', percentage: 86, passed: 63, total: 73 }

自定义注册表

仅注册您需要的套房：

import { run, TestSuiteRegistry, ProtocolSuite, SchemaSuite, AIEvaluationSuite } from 'mcp-probe';

const registry = new TestSuiteRegistry();
registry.register(new ProtocolSuite());
registry.register(new SchemaSuite());
registry.register(new AIEvaluationSuite({ enabled: true, baseUrl: '...', apiKey: '...', model: '...', maxTokens: 1024 }));

const report = await run({ config, registry });

直接客户端使用

连接到MCP服务器并直接交互：

import { MCPProbeClient, HttpTransport } from 'mcp-probe';

const transport = new HttpTransport({ url: 'https://example.com/mcp/message' });
const client = new MCPProbeClient(transport, { name: 'test', transport: { type: 'http', url: '...' } });

const discovered = await client.connect();
console.log(`Tools: ${discovered.tools.length}`);
console.log(`Resources: ${discovered.resources.length}`);

// Call a tool
const result = await client.callTool('my_tool', { arg1: 'value' });
console.log(result);

await client.disconnect();

导出类型

// Configuration
import type { MCPProbeConfig, ServerConfig, LLMJudgeConfig } from 'mcp-probe';

// Test framework
import type { TestSuite, TestCase, TestRunContext } from 'mcp-probe/suite';

// Plugin system
import type { MCPProbePlugin, CustomAssertion, TestResult, SuiteResult } from 'mcp-probe/plugin';

// Reports
import type { MCPProbeReport, ServerReport, ScoreCard } from 'mcp-probe/reporter';

______________________________________________________________________

插件系统

使用自定义断言、副作用跟踪和报告器扩展mcp探测：

import type { MCPProbePlugin } from 'mcp-probe/plugin';

const myPlugin: MCPProbePlugin = {
  name: 'my-db-checker',
  version: '1.0.0',
  description: 'Verifies database state after tool calls',

  async onBeforeToolCall(context) {
    // Capture baseline state
    return { pluginName: this.name, data: await getRowCount(), capturedAt: Date.now() };
  },

  async onAfterToolCall(context, baseline, trace) {
    // Check for side effects
    const newCount = await getRowCount();
    return {
      pluginName: this.name,
      changed: newCount !== baseline.data,
      description: `Row count: ${baseline.data} -> ${newCount}`,
    };
  },

  customAssertions: [{
    name: 'response-time',
    description: 'Tool responds within 5 seconds',
    appliesTo: (tool) => true,
    assert: (trace) => ({
      passed: trace.durationMs │  for each server:                    │  │
│  └─────────┘    │    connect -> discover -> run suites  │  │
│                 └───────────────┬────────────────────┘  │
│                                 │                        │
│  ┌──────────────────────────────┴──────────────────────┐ │
│  │              Test Suite Registry                     │ │
│  │  ┌──────────┐ ┌────────┐ ┌───────────┐ ┌─────────┐ │ │
│  │  │ Protocol │ │ Schema │ │ Execution │ │  Error  │ │ │
│  │  └──────────┘ └────────┘ └───────────┘ │Handling │ │ │
│  │  ┌──────────┐ ┌───────────────────────┐└─────────┘ │ │
│  │  │  Edge    │ │   AI Evaluation       │            │ │
│  │  │  Cases   │ │ (optional, LLM-based) │            │ │
│  │  └──────────┘ └───────────┬───────────┘            │ │
│  └───────────────────────────┼────────────────────────┘ │
│                              │                           │
│  ┌───────────────────────────┴────────────────────────┐  │
│  │              LLM Client                             │  │
│  │  Anthropic (native SDK) / OpenAI-compatible (fetch) │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │           Transport Layer                            │  │
│  │  ┌───────┐  ┌──────┐  ┌─────┐                      │  │
│  │  │ Stdio │  │ HTTP │  │ SSE │                       │  │
│  │  └───────┘  └──────┘  └─────┘                       │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

关键设计决策

• 套件注册表模式 --测试套件会动态注册，因此可以在不修改框架的情况下添加自定义套件
• LLM配置的构造注入 — AIEvaluationSuite 接收 LLMJudgeConfig 在其构造函数中，保持 TestRunContext 界面不变
• 双LLM提供者 --自动检测Anthropic与OpenAI baseUrl，使用Claude和generic的原生Anthropic SDK fetch 对于其他一切
• 断言助手 -流畅断言API(ok, equal, deepEqual, typeOf, throws, warn, info)在所有套房中一致使用
• 元数据系统 --每个测试都可以附加结构化 metadata （输入、预期、实际、llm）在仪表板中呈现为选项卡

______________________________________________________________________

技术栈

______________________________________________________________________

许可证

麻省理工学院