MCP 服务器集成与自定义工具注册

学习目标

• 理解 OMC 自托管 MCP Server 的架构
• 掌握 Notepad、Project Memory、State 工具通过 MCP 暴露的模式
• 设计自己的 MCP 工具注册
• 识别 MCP Server 启动失败和版本不兼容的陷阱

前置知识

MCP 协议的传输层与客户端/服务器架构已在通用知识中介绍：

• MCP 协议与生态集成

下文假设你已理解 MCP 的基础概念（传输层、客户端/服务器、工具调用协议），直接聚焦 OMC 的 自托管 MCP 工具服务器。

项目实践

OMC 的 MCP 架构

OMC 自托管了一个 MCP Server（bridge/mcp-server.cjs），用于向 Agent 暴露自定义工具：

工具分类

OMC 通过 MCP 暴露的工具按功能分组：

工具组	工具	用途
Notepad	notepad_read, notepad_write_priority, notepad_write_working, notepad_write_manual, notepad_prune, notepad_stats	抗压缩备忘录管理
Project Memory	project_memory_read, project_memory_write, project_memory_add_note, project_memory_add_directive	项目知识持久化
State	state_read, state_write, state_clear, state_list_active, state_get_status	编排状态查询
Team	TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskGet, TaskUpdate	Team 编队运行时
Session History	会话历史搜索工具	跨会话知识检索
Skills	技能管理工具	技能的创建、查询、删除
Trace	追踪工具	因果追踪与证据捕获
Wiki	知识库工具	项目知识库的读写

MCP Server 实现模式

OMC 的 MCP Server 使用 @modelcontextprotocol/sdk 构建：

bridge/mcp-server.cjs (983KB bundle)
├── Tool Registry（工具注册）
├── Transport Layer（传输层 - stdio）
├── Tool Handlers（工具处理器 - 文件系统操作）
└── Prompt Injection（提示词注入 - 工具描述）

工具处理器模式： 每个工具处理器是一个 async 函数，接收参数、操作文件系统、返回结构化结果：

notepad_read() → readFileSync('.omc/notepad.md')
notepad_write_priority({content}) → appendFileSync('.omc/notepad.md', content)

MCP 配置

OMC 通过 .mcp.json 文件配置 MCP 服务器：

{
  "mcpServers": {
    "omc-tools": {
      "command": "node",
      "args": ["bridge/mcp-server.cjs"]
    }
  }
}

Claude Code 通过 stdio 传输与 MCP Server 通信，无需网络配置。

与 Claude Code 原生工具的协作

OMC MCP 工具与 Claude Code 原生工具（Read、Write、Bash 等）协同工作：

• 原生工具：通用文件操作、命令执行
• OMC 工具：特定于 OMC 状态结构的封装操作

这种分层确保 Agent 可以使用原生工具进行一般操作，同时通过 OMC 工具访问 OMC 特有的功能。

问题与规避

问题 1：MCP Server 启动失败

MCP Server 是 bundle 产物，如果构建不完整，启动时可能报模块缺失错误。

规避策略：npm run build 确保所有 bundle 产物生成。/omc-doctor 命令检测 MCP Server 是否可用。

问题 2：工具注册冲突

OMC 工具名与 Claude Code 原生工具名冲突时，行为不可预测。

规避策略：OMC 使用独特的前缀命名（如 notepad_、project_memory_、state_），避免与原生工具名冲突。

问题 3：版本不兼容

OMC MCP Server 使用的 @modelcontextprotocol/sdk 版本与 Claude Code 不兼容时，工具调用失败。

规避策略：OMC 使用 @modelcontextprotocol/sdk 的稳定版本（^1.26.0），与 Claude Code 的 MCP 实现兼容。

设计取舍

为什么自托管 MCP 而非使用外部 MCP Server？

维度	自托管	外部 MCP Server
可用性	高——与 OMC 一起启动	中——依赖外部服务可用性
延迟	低——本地 stdio 传输	高——网络传输
定制性	高——完全控制工具实现	低——受限于外部服务器的 API
可移植性	低——绑定到 OMC	高——任何 MCP 客户端可用

OMC 的选择：自托管 MCP——确保工具的可用性和低延迟，代价是绑定到 OMC 生态。对于 Agent 编排场景，工具的可靠性比可移植性更重要。

参考来源

• MCP 官方文档 — Model Context Protocol 规范
• OMC Architecture - MCP — OMC 的 MCP 实现
• @modelcontextprotocol/sdk — MCP SDK