MCP & API Interoperability

连接层：MCP 协议、多端接入与 API 互操作规范

深度透视 acp_adapter/ 协议桥接、LSP/JSON-RPC 指令流转与 tools/registry.py 动态注入

📊 图 10-1：Host 编辑器客户端、ACP 桥接器与执行沙箱对接系统图

🔌 1. Model Context Protocol (MCP) 与 Narrow Waist

Model Context Protocol (MCP) 是 AI 智能体与外部工具、上下文解耦的行业标准协议。在 Hermes 架构中，MCP 起到了至关重要的隔离作用：

协议隔离：核心大模型不直接知晓底层环境的 API，而是通过 MCP 客户端，以标准 JSON-RPC 方式进行协商与发现。
按需呈现 (Service-Gated Tools)：工具不需要永久堆积在 LLM 的 System Prompt 里，而是根据当前配置（例如 Home Assistant token 存在时）动态注册，节省大量 Caching 费用。

📊 图 10-2：UML 序列图：基于 JSON-RPC 的工具发现、动态 Schema 校验与动态注入流

⚙️ 2. acp_adapter/ 的宿主 IDE (VSCode/Zed) 桥接内幕

在项目 acp_adapter/ 目录中，系统扮演着 LSP (Language Server Protocol) 与 TCP/Unix Sockets 桥接器的角色，使得 VSCode、Zed、JetBrains 等编辑器可以直接挂载 Hermes 作为后台执行插件：

JSON-RPC 监听：服务拉起一个长连接 Server，宿主编辑器作为 Client，将“执行命令”、“获取文件上下文”、“自动重构”等请求编码为标准的 JSON-RPC 2.0 数据包发送过来。
工作空间挂载 (Workspace Mount)：适配器基于 FUSE 或 OverlayFS 动态把宿主编辑器的本地目录映射为智能体内的 Workspace。
状态同步返回：适配器将智能体的中间思考过程和工具结果回传，宿主端直接呈现在侧边栏或输出终端中。

🛠️ 3. tools/registry.py 的工具发现与自动反射

所有的工具在其 Python 源文件中仅需通过装饰器 @register 注册。这套机制是由 tools/registry.py 控制的。在运行时，系统利用 Python 内省功能反射生成 LLM 格式的工具定义：

# tools/registry.py 自动生成 JSON Schema 的核心逻辑
import inspect
from typing import get_type_hints

def register_tool(name: str):
    def decorator(func):
        # 利用 inspect 模块反射提取函数签名与 Docstring
        sig = inspect.signature(func)
        doc = inspect.getdoc(func) or ""
        type_hints = get_type_hints(func)
        
        # 组装 LLM 标准的 Tool Schema
        schema = {
            "type": "function",
            "function": {
                "name": name,
                "description": doc.split("\n")[0],
                "parameters": {
                    "type": "OBJECT",
                    "properties": {}
                }
            }
        }
        # 自动提取参数类型和必需标志
        # ...
        func.schema = schema
        return func
    return decorator

💡 初学者提醒

每次新建工具，只需直接在函数上打上 @register 标签，系统会在 model_tools.py 触发 discover_builtin_tools() 时自动将其内省翻译为 LLM Schema，无须手写繁琐的 JSON。

🔗 本章子任务深入剖析专栏

为深度掌握 MCP 协议集成，推荐阅读以下子技术专题：