Preflight Tools

飞行前工具

自主系统协议的参考验证器：MCP、A2A、ACE、OCC/OCS/OCP

 

概述

Preflight Tools为跨自治代理生态系统的协议合规性验证提供了参考实现。这些验证器在部署之前捕获常见的集成问题，从而节省了数小时的调试时间。

支持的协议

• 主控程序 （模型上下文协议）-Anthropic的LLM工具集成协议
• A2A （代理到代理）-自治代理的对等通信协议
• 王牌 （自主合规生态系统）-平台编排标准
• OCC/OCS/OCP - *（即将推出）* 可观察性、合规性和策略协议

安装

# Via pip
pip install preflight-tools

# Via Poetry
poetry add preflight-tools

# From source
git clone https://github.com/syzygysys/preflight-tools.git
cd preflight-tools
poetry install

快速开始

MCP验证

根据规范验证您的MCP服务器实现：

# Validate a tools definition file
mcp-preflight-check validate path/to/tools.py

# Test a running server
mcp-preflight-check test http://localhost:8000

# Full report with verbose output
mcp-preflight-check validate --verbose path/to/tools.py

输出示例：

✅ Tool names: All valid [a-zA-Z0-9_-]
✅ Properties schemas: All using objects {}
✅ Content wrappers: All responses properly wrapped
✅ Notification handling: Correctly implemented
✅ JSON-RPC structure: All responses include required fields
❌ Stdout pollution: Found 3 print statements that will break stdio transport

Fix suggestions:
  Line 42: Remove print() statement
  Line 89: Use logging instead of print()
  Line 134: Redirect to stderr

A2A验证

*（即将推出）* 验证代理到代理协议实现：

a2a-preflight-check validate path/to/agent_config.yml

六个关键的MCP修复

该验证器是基于LAP:：CORE的MCP集成的实际调试而构建的。查看完整故事： 调试网桥

1.工具名称模式

问题： 带有圆点的工具名称未通过Zod验证\ 规则： 必须匹配 ^[a-zA-Z0-9_-]{1,64}$

# ❌ FAILS
{"name": "lap.health.ping"}

# ✅ PASSES
{"name": "lap_health_ping"}

2.属性架构类型

问题： 空属性为 [] 而不是 {}\ 规则： JSON模式要求属性为对象

# ❌ FAILS
{
    "inputSchema": {
        "type": "object",
        "properties": []  # Wrong type
    }
}

# ✅ PASSES
{
    "inputSchema": {
        "type": "object",
        "properties": {}  # Correct type
    }
}

3.内容包装结构

问题： 返回原始数据而不是MCP内容结构\ 规则： 所有回复都必须打包

# ❌ FAILS
return {"status": "ok", "value": 42}

# ✅ PASSES
return {
    "content": [{
        "type": "text",
        "text": json.dumps({"status": "ok", "value": 42})
    }]
}

4.通知处理

问题： 通知请求返回错误（否 id 现场）\ 规则： 通知不需要响应

# ❌ FAILS
async def dispatch(self, request: dict) -> str:
    method = request.get("method")
    if method not in self.handlers:
        return json.dumps({"error": "unknown method"})

# ✅ PASSES
async def dispatch(self, request: dict) -> str:
    # Check if this is a notification (no "id" field)
    if "id" not in request:
        return ""  # Silent success
    
    method = request.get("method")
    # ... handle request-response

5.标准污染

问题： 任何输出到stdout都会中断JSON-RPC stdio传输\ 规则： 尽早重定向stderr，永远不要使用print（）

# ❌ FAILS - stderr goes to stdout
poetry run mcp-server 2>> /tmp/debug.log

# ✅ PASSES - redirect before Python starts
exec 2>/tmp/debug.log; poetry run mcp-server

在代码中：

# ❌ NEVER
print("Debug message")

# ✅ ALWAYS
import logging
logging.error("Debug message")  # Goes to stderr

6.JSON-RPC响应结构

问题： 使用 exclude_none=True 删除必填字段 None\ 规则： JSON-RPC 2.0需要 id 和 jsonrpc 在每一个回应中

# ❌ FAILS - removes 'id' when it's None
class JsonRpcResponse(BaseModel):
    jsonrpc: str = "2.0"
    id: Optional[Any] = None
    result: Optional[Any] = None
    error: Optional[Dict[str, Any]] = None
    
    def json(self, **kwargs):
        return self.model_dump_json(exclude_none=True, **kwargs)

# ✅ PASSES - keeps required fields
class JsonRpcResponse(BaseModel):
    jsonrpc: str = "2.0"
    id: Optional[Any] = None
    result: Optional[Any] = None
    error: Optional[Dict[str, Any]] = None
    
    def json(self, **kwargs):
        data = self.model_dump()
        # Keep id and jsonrpc always, only exclude result/error conditionally
        if data.get('error') is not None:
            data.pop('result', None)
        elif data.get('result') is not None:
            data.pop('error', None)
        return json.dumps(data)

API使用

Python API

from preflight_tools.mcp import MCPValidator

validator = MCPValidator()

# Validate a tools file
results = validator.validate_file("path/to/tools.py")

for issue in results.issues:
    print(f"{issue.severity}: {issue.message}")
    print(f"  Fix: {issue.suggestion}")

# Test a running server
results = validator.test_server("http://localhost:8000")
print(f"Protocol version: {results.protocol_version}")
print(f"Tools found: {len(results.tools)}")

配置

创建一个 .preflight.toml 在项目根目录中：

[mcp]
strict = true  # Fail on warnings
ignore = ["stdout-pollution"]  # Skip specific checks

[a2a]
version = "0.1.0"
require_auth = true

发展

# Clone and setup
git clone https://github.com/syzygysys/preflight-tools.git
cd preflight-tools
poetry install

# Run tests
poetry run pytest

# Run validator on itself
poetry run mcp-preflight-check validate src/

# Format and lint
poetry run black src/ tests/
poetry run ruff check src/ tests/
poetry run mypy src/

建筑

preflight-tools/
├── src/preflight_tools/
│   ├── mcp/              # MCP validation
│   │   ├── validator.py  # Core validation logic
│   │   ├── checks.py     # Individual check implementations
│   │   └── cli.py        # Command-line interface
│   ├── a2a/              # A2A validation (coming soon)
│   └── common/           # Shared utilities
├── tests/
│   ├── test_mcp.py
│   └── fixtures/         # Test cases
└── docs/
    └── protocols/        # Protocol specs

贡献

我们欢迎捐款！这是社区的参考实现。

1. 分叉回购
2. 创建要素分支
3. 为新验证器添加测试
4. 提交一份描述清晰的PR

看 贡献.md 了解详情。

相关项目

• 圈数：：核心 -LAPI编排平台
• ACE框架 -自主合规生态系统
• MCP规范 -MCP官方文件

参考文献

• 日志14：调试网桥 -启发此工具的调试会话
• -在此处报告MCP错误
• SyzygySys架构笔记本 -更多技术深度潜水

许可证

Apache许可证2.0-请参阅 许可证 了解详情。

版权所有2025 SyzygySys

支持

• 问题：
• 讨论：
• 电子邮件：kevin@syzygysys.com

______________________________________________________________________

内置于❤️ 作为送给自治系统社区的礼物。