MCP验证工具

一个全面的验证工具模型上下文协议（MCP）服务器，以确保协议合规性、安全性和正确实施。

目标

此工具通过以下方式验证MCP服务器：

协议遵从：测试完整的MCP初始化握手
标准一致性：验证JSON-RPC 2.0格式和必填字段
能力测试：验证宣传的功能（资源、工具、提示）
证券分析：与集成 mcp扫描用于漏洞检测
注册表验证：确保服务器与其注册表架构定义匹配
详细报告：导出带有验证清单的全面JSON报告
自动化测试：为CI/CD管道提供程序验证

特性

✅ 协议验证：完成MCP握手和能力测试
✅ 安全扫描：集成mcp扫描漏洞分析
✅ JSON报告：具有链接安全扫描的全面验证报告
✅ 逐步记录：实时验证进度和详细反馈
✅ 工具发现：列出所有可用的工具、提示和资源
✅ 环境变量：可配置的环境设置
✅ 超时处理：可配置的验证超时
✅ 退出代码：自动化的正确退出代码
✅ 详细模式：可选详细输出

安装

# Clone and install
git clone https://github.com/modelcontextprotocol/mcp-validation
cd mcp-validation
uv sync

或直接安装：

pip install mcp-validation

用法

基本验证

# Validate a Python MCP server
mcp-validate python server.py

# Validate a Node.js MCP server
mcp-validate node server.js

# Validate npx packages (use -- separator for flags)
mcp-validate -- npx -y kubernetes-mcp-server@latest

# Validate servers via container runtime (podman/docker)
mcp-validate -- podman run -i --rm hashicorp/terraform-mcp-server

使用环境变量

# IoTDB MCP server example
mcp-validate \
  --env IOTDB_HOST=127.0.0.1 \
  --env IOTDB_PORT=6667 \
  --env IOTDB_USER=root \
  --env IOTDB_PASSWORD=root \
  python src/iotdb_mcp_server/server.py

JSON报告生成

# Generate comprehensive JSON report
mcp-validate --json-report validation-report.json python server.py

# With security analysis and custom timeout
mcp-validate \
  --timeout 60 \
  --json-report full-report.json \
  --env API_KEY=secret \
  -- npx -y some-mcp-server@latest

安全分析选项

# Skip mcp-scan for faster validation
mcp-validate --skip-mcp-scan python server.py

# Full validation with security scan
mcp-validate --timeout 120 --json-report report.json python server.py

程序化使用

import asyncio
from mcp_validation import validate_mcp_server_command

async def test_server():
    result = await validate_mcp_server_command(
        command_args=["python", "server.py"],
        env_vars={"API_KEY": "secret"},
        timeout=30.0,
        use_mcp_scan=True
    )
    
    if result.is_valid:
        print(f"✓ Server is MCP compliant!")
        print(f"Tools: {result.tools}")
        print(f"Capabilities: {list(result.capabilities.keys())}")
        if result.mcp_scan_results:
            print(f"Security scan: {result.mcp_scan_file}")
    else:
        print("✗ Validation failed:")
        for error in result.errors:
            print(f"  - {error}")

asyncio.run(test_server())

CLI选项

选项	描述	示例
`command`	运行MCP服务器的命令和参数	`python server.py`
`--env KEY=VALUE`	设置环境变量（可重复）	`--env HOST=localhost`
`--timeout SECONDS`	验证超时（秒）（默认值：30）	`--timeout 60`
`--verbose`	显示包括警告在内的详细输出	`--verbose`
`--skip-mcp-scan`	跳过mcp扫描安全分析	`--skip-mcp-scan`
`--json-report FILE`	将详细的JSON报告导出到文件	`--json-report report.json`

验证过程

该工具执行以下验证步骤：

进程执行：使用提供的参数和环境启动服务器
初始化握手：发送MCP initialize 请求协议版本
协议遵从：验证JSON-RPC 2.0格式和所需的响应字段
能力发现：测试广告功能（资源、工具、提示）
证券分析：运行mcp扫描漏洞检测（可选）
报告生成：使用验证清单创建详细的JSON报告

输出格式

Testing MCP server: npx -y kubernetes-mcp-server@latest

🔄 Step 1: Sending initialize request...
✅ Initialize request successful
🔄 Step 2: Sending initialized notification...
✅ Initialized notification sent
🔄 Step 3: Testing capabilities...
  🔄 Testing tools...
    ✅ Found 18 tools
    📋 Names: configuration_view, events_list, helm_install, helm_list, helm_uninstall (and 13 more)
  🔄 Testing prompts...
    ✅ Found 0 prompts
  🔄 Testing resources...
    ✅ Found 0 resources
✅ Capability testing complete
🔄 Step 4: Running mcp-scan security analysis...
    🔍 Running: uvx mcp-scan@latest --json...
    📊 Scanned 18 tools
    ✅ No security issues detected
    💾 Scan results saved to: mcp-scan-results_20250730_120203.json
✅ mcp-scan analysis complete

✓ Valid: True
⏱ Execution time: 10.49s
🖥 Server: kubernetes-mcp-server vv0.0.46
🔧 Capabilities: logging, prompts, resources, tools
🔨 Tools (18): configuration_view, events_list, helm_install, helm_list, helm_uninstall, namespaces_list, pods_delete, pods_exec, pods_get, pods_list, pods_list_in_namespace, pods_log, pods_run, pods_top, resources_create_or_update, resources_delete, resources_get, resources_list
🔍 Security Scan: No issues found in 18 tools
📋 JSON report saved to: validation-report.json

JSON报告结构

这 --json-report 选项生成全面的验证报告：

{
  "report_metadata": {
    "generated_at": "2025-07-30T12:02:03.456789",
    "validator_version": "0.1.0",
    "command": "npx -y kubernetes-mcp-server@latest",
    "environment_variables": {}
  },
  "validation_summary": {
    "is_valid": true,
    "execution_time_seconds": 10.49,
    "total_errors": 0,
    "total_warnings": 0
  },
  "validation_checklist": {
    "protocol_validation": {
      "initialize_request": {"status": "passed", "details": "..."},
      "initialize_response": {"status": "passed", "details": "..."},
      "protocol_version": {"status": "passed", "details": "..."}
    },
    "capability_testing": {
      "tools_capability": {"status": "passed", "details": "..."},
      "resources_capability": {"status": "skipped", "details": "..."}
    },
    "security_analysis": {
      "mcp_scan_execution": {"status": "passed", "details": "..."}
    }
  },
  "server_information": {
    "server_info": {"name": "kubernetes-mcp-server", "version": "v0.0.46"},
    "capabilities": {"logging": {}, "tools": {"listChanged": true}},
    "discovered_items": {
      "tools": {"count": 18, "names": ["configuration_view", "..."]}
    }
  },
  "security_analysis": {
    "mcp_scan_executed": true,
    "mcp_scan_file": "mcp-scan-results_20250730_120203.json",
    "summary": {
      "tools_scanned": 18,
      "vulnerabilities_found": 0,
      "vulnerability_types": [],
      "risk_levels": []
    }
  },
  "issues": {
    "errors": [],
    "warnings": []
  }
}

退出代码

0：服务器符合MCP标准
1：验证失败或服务器不符合要求

MCP注册表验证

对于中列出的服务器 MCP注册表，此工具可以验证：

包装安装要求
环境变量规格
参数格式合规性
协议实现正确性

发展

先决条件

此项目使用紫外线用于依赖关系管理和开发工作流。

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/modelcontextprotocol/mcp-validation
cd mcp-validation

Makefile快速入门

为方便起见，此项目包括一个包含常见开发任务的Makefile：

# Setup development environment
make install

# Run the full pre-commit workflow (format, lint, test)
make pre-commit

# Run tests
make test

# Format code
make format

# See all available commands
make help

手动设置

# Install all dependencies including dev extras
uv sync --extra dev

# Alternatively, install the package in development mode
uv pip install -e ".[dev]"

可用的生成命令

命令	描述
`make help`	显示所有可用命令
`make install`	使用dev-extras安装依赖项
`make dev-setup`	完成开发环境设置
`make test`	运行所有测试（不包括合作伙伴仓库）
`make test-cov`	使用覆盖率报告运行测试
`make test-fast`	使用快速失败（-x标志）运行测试
`make debug-test`	使用调试输出和注册表日志记录运行测试
`make format`	用黑色格式化代码
`make check`	检查格式而不进行更改
`make lint`	使用Ruff检查代码（无修复）
`make lint-fix`	检查并修复Ruff的代码问题
`make pre-commit`	运行完整的预提交工作流（格式化、lint、测试）
`make ci`	运行类似CI的检查（无自动修复）
`make clean`	清理缓存和临时文件

手动测试命令

# Run all tests
make test
# OR manually:
uv run --extra dev pytest tests/ -v

# Run tests with coverage
make test-cov
# OR manually:
uv run --extra dev pytest tests/ --cov=mcp_validation --cov-report=term-missing

# Run specific test file
uv run --extra dev pytest tests/test_enhanced_registry.py -v

# Run tests and stop on first failure
make test-fast
# OR manually:
uv run --extra dev pytest tests/ -x

代码格式化和Linting

# Format code with Black
make format
# OR manually:
uv run --extra dev black mcp_validation/

# Check code formatting (without making changes)
make check
# OR manually:
uv run --extra dev black --check mcp_validation/

# Lint with Ruff (with fixes)
make lint-fix
# OR manually:
uv run --extra dev ruff check --fix mcp_validation/

# Lint with Ruff (check only)
make lint
# OR manually:
uv run --extra dev ruff check mcp_validation/

# Type checking with mypy
uv run --extra dev mypy mcp_validation/

工作流

# Pre-commit workflow (format, lint, test)
make pre-commit

# CI-style checks (no automatic fixes)
make ci

# Manual pre-commit workflow
uv run --extra dev black mcp_validation/ && \
uv run --extra dev ruff check --fix mcp_validation/ && \
uv run --extra dev pytest tests/ -v

开发指南

测试：所有新功能都必须包括测试
代码的风格：使用黑色进行格式化，使用Ruff进行换行
类型提示：为所有公共API添加类型提示
文档：更新README和docstring以获取新功能

测试配置

该项目在以下配置中使用pytest pyproject.toml:

测试发现：在中查找测试 tests/ 目录
异步支持：已配置用于异步/等待测试
除外条款：自动排除合作伙伴存储库和生成目录
标记：启用了严格的标记检查

调试测试

# Run tests with debug output and registry logging
make debug-test

# Run tests with verbose output and debug information
uv run --extra dev pytest -v -s

# Run specific test with debugging
uv run --extra dev pytest tests/test_enhanced_registry.py::test_enhanced_registry_validator -v -s

# Run registry tests with debug output
mcp-validate --debug -- npm test

调试MCP验证

该工具提供全面的调试输出，以跟踪服务器执行进度：

# Enable debug output for detailed execution tracking
mcp-validate --debug -- python server.py

调试输出包括：

执行上下文：工作目录、Python版本、平台、用户、shell
命令详细信息：完整命令、参数、可执行路径
环境变量：自定义变量（带敏感值掩码）
流程信息：PID，流程生命周期事件
验证器进度：具有时间和结果的单个验证器执行
验证摘要：总体统计和执行时间

调试输出示例：

[10:19:29.872] [EXEC-INFO] 🚀 Starting MCP Server Process
[10:19:29.872] [EXEC-INFO] 📁 Working Directory: /path/to/project
[10:19:29.872] [EXEC-INFO] 🐍 Python: /usr/bin/python3 (v3.11.0)
[10:19:29.872] [EXEC-INFO] 🔧 Command: npx @dynatrace-oss/dynatrace-mcp-server
[10:19:29.872] [EXEC-INFO] 🌍 Environment Variables:
[10:19:29.872] [EXEC-INFO]    API_KEY=ab*****ef
[10:19:29.877] [VALIDATOR-INFO] 🔍 [registry] STARTING: (1/6)
[10:19:30.727] [VALIDATOR-INFO] 🔍 [registry] PASSED: Time: 0.85s

例子

验证注册表服务器

# Apache IoTDB MCP Server from registry
mcp-validate \
  --env IOTDB_HOST=127.0.0.1 \
  --env IOTDB_PORT=6667 \
  --env IOTDB_USER=root \
  --env IOTDB_PASSWORD=root \
  --env IOTDB_DATABASE=test \
  --env IOTDB_SQL_DIALECT=table \
  python src/iotdb_mcp_server/server.py

CI/CD集成

# GitHub Actions example
- name: Validate MCP Server
  run: |
    mcp-validate --json-report validation-report.json python server.py
  env:
    DATABASE_URL: sqlite:///test.db

- name: Upload validation report
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: mcp-validation-report
    path: |
      validation-report.json
      mcp-scan-results_*.json

证券分析

该工具与 mcp扫描进行全面的安全分析：

自动检测：检查 uvx 或 mcp-scan 可用性
漏洞扫描：分析潜在安全问题的工具
单独报告：安全结果保存到带时间戳的JSON文件中
链接报告：主验证报告引用安全扫描文件
跳过选项：使用 --skip-mcp-scan 无需安全分析即可更快地进行验证

贡献

欢迎投稿！请查看我们的贡献指南了解详情。

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

MCP Validation

快速接入

详细介绍