Atrawog MCP

MCP HTTP验证器

基于HTTP的验证器，用于具有OAuth 2.0授权测试的模型上下文协议（MCP）服务器。

快速示例

# Install
pip install mcp-http-validator

# Run full validation suite (handles OAuth automatically)
mcp-validate full https://mcp.example.com

# Or validate with existing token
mcp-validate validate https://mcp.example.com --token $ACCESS_TOKEN

概述

MCP HTTP验证器是一个全面的测试工具，用于验证MCP服务器实现是否符合 MCP规范它侧重于：

• OAuth 2.0授权合规性（RFC 6749、RFC 8707、RFC 9728）
• MCP特定终点验证
• 令牌受众验证
• 服务器发送事件（SSE）支持
• 受保护的资源元数据合规性

特性

核心功能

• 自动OAuth发现：从MCP元数据中发现OAuth服务器
• 零配置：自动注册和保存OAuth客户端
• 完整的MCP合规性测试：根据MCP 2025-06-18规范验证服务器
• OAuth流测试：完成OAuth 2.0授权流验证
• 动态客户端注册：支持RFC 7591用于自动客户端设置
• 客户管理：RFC 7592支持更新/删除客户端
• 资源指标：验证RFC 8707资源受限令牌
• 多种输出格式：终端、JSON和Markdown报告
• 凭据管理：OAuth凭据的安全.env文件存储
• 无stdio依赖关系：纯基于HTTP的测试

高级功能

• 智能令牌管理：在OAuth流之前自动检查令牌有效性
• 令牌刷新：在启动新身份验证之前尝试刷新令牌流
• SSE支持：MCP SSE传输的完整服务器发送事件测试
• 工具发现：MCP服务器工具的自动发现和测试
• 运输检测：自动检测SSE与HTTP传输
• 批量测试: full 命令自动运行完整的测试套件
• 进度报告：长时间运行期间的实时进度更新
• 重定向策略：支持公共IP和带外OAuth流
• JWT验证：解码和验证JWT令牌的到期时间和受众
• 每台服务器隔离：每个MCP服务器都有自己的凭据命名空间

安装

pip install mcp-http-validator

或者从源代码安装：

git clone https://github.com/example/mcp-http-validator
cd mcp-http-validator
pip install -e .

快速开始

命令行用法

1.基本验证

# Validate an MCP server (automatic OAuth discovery and setup)
mcp-validate validate https://mcp.example.com

# Use existing access token
mcp-validate validate https://mcp.example.com --token $ACCESS_TOKEN

# With additional options
mcp-validate validate https://mcp.example.com \
  --output json \
  --output-file report.json \
  --verbose \
  --timeout 60

选项：

• --token, -t：用于身份验证测试的OAuth访问令牌
• --output, -o：输出格式（终端/json/makdown）
• --output-file, -f：将输出保存到文件
• --no-ssl-verify：禁用SSL证书验证
• --timeout：请求超时（秒）（默认值：30）
• --verbose, -v：显示详细的测试信息

2.完整的测试套件

# Run ALL validation tests in the correct order
mcp-validate full https://mcp.example.com

# Include destructive tool tests (use with caution!)
mcp-validate full https://mcp.example.com --test-destructive --verbose

此命令自动执行：

1. 从MCP元数据中发现OAuth服务器
2. 如果需要，注册OAuth客户端
3. 完成访问令牌的OAuth流
4. 运行主MCP验证
5. 测试所有MCP工具

3.OAuth身份验证流程

# Complete OAuth flow (checks for existing valid token first)
mcp-validate flow https://mcp.example.com

# Force new flow even if valid token exists
mcp-validate flow https://mcp.example.com --force

# Request specific scopes
mcp-validate flow https://mcp.example.com --scope "mcp:read"

流命令自动执行：

• 检查现有的有效访问令牌
• 如果已过期，尝试刷新令牌
• 仅在必要时启动新的OAuth流
• 支持公共IP和带外重定向策略

4.OAuth客户端管理（RFC 7591/7592）

# Register a new OAuth client
mcp-validate client register https://mcp.example.com

# Force new registration (replaces existing)
mcp-validate client register https://mcp.example.com --force

# Also validate RFC 7592 support
mcp-validate client register https://mcp.example.com --validate-rfc7592

# List all saved OAuth clients
mcp-validate client list

# Update client configuration (RFC 7592)
mcp-validate client update https://mcp.example.com \
  --client-name "My MCP Client" \
  --redirect-uri "http://localhost:8080/callback" \
  --scope "mcp:read mcp:write"

# Delete client registration
mcp-validate client delete https://mcp.example.com

5.代币管理

# List all stored tokens and their status
mcp-validate tokens list

# Show detailed token status for a specific server
mcp-validate tokens show https://mcp.example.com

# Refresh access token using refresh token
mcp-validate tokens refresh https://mcp.example.com

# Clear tokens for a server (keeps client credentials)
mcp-validate tokens clear https://mcp.example.com

6.MCP工具测试

# Discover and test all tools
mcp-validate tools https://mcp.example.com

# List tools without testing
mcp-validate tools https://mcp.example.com --list-only

# Test specific tool
mcp-validate tools https://mcp.example.com --tool-name "search"

# Include destructive tool tests
mcp-validate tools https://mcp.example.com --test-destructive

7.直接OAuth服务器测试

# Test an OAuth authorization server directly
mcp-validate oauth https://auth.example.com

# Register new client with OAuth server
mcp-validate oauth https://auth.example.com --register

程序化使用

import asyncio
from mcp_http_validator import MCPValidator, ComplianceChecker

async def validate_server():
    async with MCPValidator(
        server_url="https://mcp.example.com",
        auto_register=True  # Automatically discover OAuth and register client
    ) as validator:
        # OAuth client is automatically set up if needed
        await validator.setup_oauth_client()
        
        result = await validator.validate()
        
    checker = ComplianceChecker(result, validator.server_info)
    report = checker.check_compliance()
    
    print(f"Compliance Level: {report.compliance_level}")
    print(f"Success Rate: {result.success_rate:.1f}%")

asyncio.run(validate_server())

配置

验证器自动管理OAuth凭据和令牌 .env 文件：

手动配置

# Manual access token for pre-authenticated testing
MCP_ACCESS_TOKEN=your-access-token

# Default OAuth credentials (fallback if server-specific not found)
OAUTH_CLIENT_ID=default-client-id
OAUTH_CLIENT_SECRET=default-client-secret

每台服务器自动存储

验证器会自动保存带有服务器特定密钥的凭据：

# OAuth client credentials (RFC 7591)
OAUTH_CLIENT_ID_MCP_EXAMPLE_COM=mcp_client_123456
OAUTH_CLIENT_SECRET_MCP_EXAMPLE_COM=secret_abcdef...
OAUTH_REGISTRATION_TOKEN_MCP_EXAMPLE_COM=reg_token_xyz...
OAUTH_REDIRECT_URI_MCP_EXAMPLE_COM=http://localhost:61234/callback

# OAuth tokens
OAUTH_ACCESS_TOKEN_MCP_EXAMPLE_COM=eyJhbGc...
OAUTH_TOKEN_EXPIRES_AT_MCP_EXAMPLE_COM=1234567890
OAUTH_REFRESH_TOKEN_MCP_EXAMPLE_COM=refresh_token_abc...

服务器URL通过以下方式转换为环境变量键：

1. 删除协议(https://)
2. 用下划线替换圆点和特殊字符
3. 转换为大写

例子： https://mcp.example.com → MCP_EXAMPLE_COM

自动功能

验证器提供智能凭证管理：

1. 自动发现：从MCP元数据中发现OAuth服务器
2. 自动注册：需要时通过RFC 7591注册的客户端
3. 许可证管理：自动令牌验证和刷新
4. 安全存储：所有凭据保存到 .env 文件
5. 服务器隔离：每个服务器都有自己的凭据

验证测试

验证器执行以下测试：

关键测试（必需）

• 受保护资源元数据: /.well-known/oauth-protected-resource 端点
• 身份验证质询：带有WWW-Authenticate标头的正确401响应
• 认证访问：有效的持票人令牌接受

重要测试

• 令牌受众验证：验证令牌 aud 声明包含服务器URL
• 资源令牌一致性：验证受保护的资源元数据是否与令牌受众匹配
• SSE支持：MCP协议的服务器发送事件

OAuth服务器测试

• 授权服务器元数据发现
• 资源指示器支持（RFC 8707）
• 所需端点可用性
• MCP范围支持(mcp:read, mcp:write)

输出格式

终端输出

丰富的彩色输出，带有表格和进度指示器：

┌─────────────────────────────────────┐
│ MCP Compliance Report               │
│ Server: https://mcp.example.com     │
│ Compliance Level: FULLY_COMPLIANT   │
└─────────────────────────────────────┘

JSON输出

用于程序化处理的完整结构化数据：

mcp-validate validate https://mcp.example.com -o json -f report.json

Markdown输出

人类可读的文档报告：

mcp-validate validate https://mcp.example.com -o markdown -f report.md

完整测试套件输出

这 full 命令提供全面的结果：

mcp-validate full https://mcp.example.com --verbose

显示每个阶段的进度：

• OAuth服务器发现和验证
• 客户注册状态
• 代币获取进度
• MCP验证结果
• 工具发现和测试

合规级别

• 完全合规：所有测试均通过（100%）
• 最符合要求：90%以上的测试通过
• 部分合规：70%以上的测试通过或关键测试失败
• 最小兼容性：一些测试通过，但存在重大问题
• 不合规：关键要求的测试失败

高级用法

自定义验证测试

from mcp_http_validator import MCPValidator, TestCase, TestSeverity

class CustomValidator(MCPValidator):
    async def test_custom_endpoint(self):
        """Test a custom MCP endpoint."""
        response = await self.client.get(
            f"{self.server_url}/custom",
            headers=self._get_headers()
        )
        
        passed = response.status_code == 200
        error = None if passed else f"Got {response.status_code}"
        
        return passed, error, {"status": response.status_code}
    
    async def validate(self):
        # Add custom test
        custom_test = TestCase(
            id="custom-endpoint",
            name="Custom Endpoint Test",
            description="Validates custom MCP endpoint",
            severity=TestSeverity.MEDIUM,
            category="custom"
        )
        
        result = await self._execute_test(
            custom_test,
            self.test_custom_endpoint
        )
        self.test_results.append(result)
        
        # Run standard tests
        return await super().validate()

OAuth流自动化

from mcp_http_validator import MCPValidator, EnvManager

async def automated_oauth_test(mcp_server: str):
    # Automatic OAuth discovery and registration
    async with MCPValidator(mcp_server) as validator:
        # Discovers OAuth server and registers client automatically
        oauth_client = await validator.setup_oauth_client()
        
        if oauth_client:
            # Generate auth URL with discovered OAuth server
            auth_url, state, verifier = oauth_client.generate_authorization_url(
                resources=[mcp_server]
            )
            
            print(f"Visit: {auth_url}")
            code = input("Enter code: ")
            
            # Exchange for token
            token = await oauth_client.exchange_code_for_token(
                code, verifier, [mcp_server]
            )
            
            # Test access
            success, error, _ = await oauth_client.test_mcp_server_with_token(
                mcp_server, token.access_token
            )
            print(f"Access: {'✓' if success else '✗'} {error or 'OK'}")

# RFC 7592 Client Management
async def manage_oauth_client(mcp_server: str):
    env_manager = EnvManager()
    credentials = env_manager.get_oauth_credentials(mcp_server)
    
    async with MCPValidator(mcp_server) as validator:
        auth_server = await validator.discover_oauth_server()
        
        async with OAuthTestClient(
            auth_server,
            registration_access_token=credentials["registration_token"]
        ) as client:
            # Get current config
            config = await client.get_client_configuration()
            
            # Update client
            await client.update_client_configuration({
                "client_name": "Updated Name"
            })
            
            # Or delete client
            # await client.delete_client_registration()

故障排除

常见问题

1. “未发现OAuth服务器”

- 确保MCP服务器实现 /.well-known/oauth-protected-resource - 检查元数据是否包括 authorization_servers 数组 - 使用 --no-ssl-verify 用于具有自签名证书的开发服务器

1. 验证期间“令牌已过期”

- 跑 mcp-validate tokens refresh https://mcp.example.com 刷新 - 或使用 mcp-validate flow https://mcp.example.com 对于新令牌

1. “客户端注册失败”

- 检查OAuth服务器是否支持RFC 7591动态注册 - 尝试在OAuth服务器的web界面上手动注册 - 将环境变量用于手动客户端凭据

1. “SSL验证失败”

- 开发：使用 --no-ssl-verify 旗帜 - 对于生产：确保有效的SSL证书

1. “.env上的权限被拒绝”

- 检查文件权限： chmod 600 .env - 确保目录可写

调试模式

有关详细的调试信息：

# Verbose output for any command
mcp-validate validate https://mcp.example.com --verbose

# Check stored credentials
mcp-validate client list
mcp-validate tokens list

# Test OAuth server directly
mcp-validate oauth https://auth.example.com

贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

另见

• MCP规范
• OAuth 2.0 RFC 6749
• 动态客户端注册RFC 7591
• 动态客户端注册管理RFC 7592
• 资源指示器RFC 8707
• 受保护资源元数据RFC 9728