oh-my-openagent 内置 MCP 扩展实战以 arXiv 论文搜索 MCP 为例的源码级实施指南【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文围绕 oh-my-openagent 开源仓库中一份真实落地的执行计划对应 Issue #100 Built-in arXiv MCP完整讲解如何为项目新增一个内置 MCPModel Context Protocol模块从 git 工作区准备、源码实现、测试与文档更新到 PR 创建、三重验证门禁与最终合并的全流程。读完本文你将掌握 oh-my-openagent 内置 MCP 的注册机制、静态导出配置模式、测试约定与 CI/审查工作流并能在本仓库中独立复现同样的扩展路径。背景oh-my-openagent 的内置 MCP 架构在 oh-my-openagent 中MCP 体系分为三层见 packages/omo-opencode/src/mcp/AGENTS.mdTier来源机制1. Built-inpackages/omo-opencode/src/mcp/远程 HTTP MCP 本地 stdio MCP经createBuiltinMcps()统一注册2. Claude Code.mcp.json${VAR}展开由claude-code-mcp-loader加载3. Skill-embeddedSKILL.md YAML由SkillMcpManager管理stdio HTTP本文讨论的 arXiv MCP 属于第一层Tier 1内置 MCP。内置 MCP 由 createBuiltinMcps 函数 统一创建其入参包括disabledMcps: string[]需要禁用的内置 MCP 名称列表命中者不会注册config?: BuiltinMcpSourceConfig可选的来源配置例如websearch的提供商参数options?: BuiltinMcpOptions运行时选项cwd、resolveExecutable等主要服务于本地 stdio 的lspMCP。目前内置 MCP 名称由McpNameSchema固定约束websearch | context7 | grep_app | lsp见 types.ts全部禁用测试用例中对应的枚举即来自此 Schema。要新增 arXiv MCP正是要在这一 Schema 中加入arxiv并在注册函数中加入条件分支。Phase 0工作区准备执行计划的第一步是建立独立的工作区与特性分支避免污染主开发线git fetch origin dev git worktree add ../omo-wt/feat/arxiv-mcp origin/dev cd ../omo-wt/feat/arxiv-mcp git checkout -b feat/arxiv-mcp要点说明使用git worktree在仓库外另建工作树可同时持有多个分支而不互相干扰适合与主仓库并行迭代从dev分支拉出特性分支feat/arxiv-mcp保证后续 PR 的基线干净。Phase 1实现内置 arXiv MCPStep 1创建src/mcp/arxiv.ts新 MCP 需遵循既有内置模块的静态导出模式static export pattern可参照context7.ts与grep-app.ts两个先例grep-app.ts 是最简形态——直接导出一个纯静态配置对象export const grep_app { type: remote as const, url: https://mcp.grep.app, enabled: true, oauth: false as const, }context7.ts 则在静态对象基础上支持可选环境变量鉴权导出的是RemoteMcpConfigexport function createContext7Config(env: Recordstring, string | undefined process.env): RemoteMcpConfig { const context7ApiKey normalizeContext7ApiKey(env.CONTEXT7_API_KEY) return { type: remote as const, url: https://mcp.context7.com/mcp, enabled: true, ...(context7ApiKey ? { headers: { Authorization: Bearer ${context7ApiKey} } } : {}), oauth: false as const, } }RemoteMcpConfig的类型定义见 index.ts要求type: remote、url、enabled字段可选headers与oauth: false。对于 arXiv其 API 是公开的无需鉴权。执行计划中假设的远程端点为https://mcp.arxiv.org——注意这是计划中标注的假设性端点hypothetical remote MCP endpoint仓库中目前并不存在该服务。原计划明确指出若不存在现成的远程 arXiv MCP则需要改为 stdio MCP 或自建 HTTP 包装层本计划按与既有内置项一致的远程 MCP 端点模式继续推进。落地时若端点不可用应回归到本地 stdio 方案即参照 lsp.ts 的LocalMcpConfig形态本地命令行 resolveExecutable解析器。Step 2更新src/mcp/types.ts在McpNameSchema枚举中追加arxivexport const McpNameSchema z.enum([websearch, context7, grep_app, arxiv])对应到仓库中的实际文件为 packages/omo-opencode/src/mcp/types.ts同时需注意McpName类型z.infer会自动随之扩展。此外配置侧 Schema 位于 packages/omo-opencode/src/config/schema/oh-my-opencode-config.ts若用户配置文件需要显式禁用该 MCP还需同步配置 Schema 的联合类型。Step 3更新src/mcp/index.ts在createBuiltinMcps()中引入并注册 arXiv 模块对应仓库文件 packages/omo-opencode/src/mcp/index.tsimport { arxiv } from ./arxiv // ... if (!disabledMcps.includes(arxiv)) { mcps.arxiv arxiv }该条件分支与既有context7、grep_app的注册模式完全一致——凡是出现在disabledMcps数组中的名称都不会被注入到返回的mcps记录中。Step 4创建src/mcp/arxiv.test.ts测试应覆盖 arXiv 配置的形状shapetype必须为remoteurl必须为期望的 arXiv 端点enabled必须为trueoauth必须为false。测试写法遵循仓库现有的 given/when/then 结构可参考 context7.test.ts 与 websearch.test.ts。例如// given: arXiv 配置被创建 // when: 读取 arxiv 配置对象 // then: 其 url / enabled / oauth 字段符合预期Step 5更新src/mcp/index.test.ts注册函数测试需要同步三处仓库中对应 zauc-mocks-mcp-index/index.test.ts该测试通过 mock 模块逐项断言result.websearch、result.grep_app等属性是否toBeDefined()将默认返回的内置 MCP 数量从 3 更新为 4在toHaveProperty断言中追加arxiv在 all disabled 用例的disabledMcps数组中追加arxiv并断言剩余名称中不再包含它。Step 6更新src/mcp/AGENTS.md将 arxiv 行追加到内置 MCP 表格仓库中对应 packages/omo-opencode/src/mcp/AGENTS.md表格字段包括Name、Type、Endpoint / Command、Env Vars、Tools。按当前文档体例arxiv 一行大致应为NameTypeEndpoint / CommandEnv VarsToolsarxivremotemcp.arxiv.org假设端点NonearXiv 论文检索同时需更新文首的内置 MCP 数量当前标题为 4 Built-in MCPs与McpNameSchema枚举描述、三层次表格中的 3 remote HTTP MCPs 1 local stdio MCP 统计使其与实际注册数一致。Step 7本地验证bun run typecheck bun test src/mcp/ bun run buildtypecheck确认McpNameSchema扩展后类型推断正确单测跑通src/mcp/下全部测试含新增arxiv.test.ts与更新后的注册函数测试build确认打包产物正常生成。原子提交Atomic Commits按职责拆分为三个互相独立、可回滚的提交feat(mcp): add arxiv paper search built-in MCP——arxiv.tstypes.ts更新test(mcp): add arxiv MCP tests——arxiv.test.tsindex.test.ts更新docs(mcp): update AGENTS.md with arxiv MCP——AGENTS.md更新。Phase 2PR 创建git push -u origin feat/arxiv-mcp gh pr create --base dev --title feat(mcp): add built-in arXiv paper search MCP --body-file /tmp/pull-request-arxiv-mcp-*.md要点--base dev与 Phase 0 的工作树基线一致PR 正文从预生成的模板文件读取便于在本地先撰写、再提交。Phase 3验证循环Verify Loop合并前需要依次通过三道门禁任一门禁失败则修复后重新进入循环Gate ACI等待ci.yml工作流tests、typecheck、build通过使用gh run watch或轮询gh pr checks观察状态。Gate Breview-work 技能审查运行/review-work技能触发 5 个 Agent 并行审查五个审查角色必须全部通过Oracle目标一致性、Oracle代码质量、Oracle安全、QA 执行、上下文挖掘context mining。Gate CCubic 自动化审查等待cubic-dev-ai[bot]的自动化审查结果必须显示 No issues found若发现问题修复并重新推送。失败处理策略失败门禁处理方式Gate A 失败本地修复amend 或新增提交重新推送Gate B 失败处理 review-work 发现项新增提交Gate C 失败处理 Cubic 发现项新增提交修复后从 Gate A 重新进入验证循环直到三道门禁全部通过。Phase 4合并gh pr merge --squash --delete-branch git worktree remove ../omo-wt/feat/arxiv-mcp git branch -D feat/arxiv-mcp # 若未随 PR 自动删除采用 squash 合并将特性分支的多个原子提交折叠为单一提交进入dev随后清理工作树与本地分支保持环境整洁。总结把执行计划映射到本仓库的真实代码本执行计划中的src/mcp/路径在仓库中对应 packages/omo-opencode/src/mcp/ 目录其既有文件与计划步骤的对应关系如下计划中的文件仓库实际文件在计划中的角色src/mcp/arxiv.ts待新建参照 context7.ts、grep-app.ts静态导出 arXiv 远程 MCP 配置src/mcp/types.tstypes.ts扩展McpNameSchema枚举src/mcp/index.tsindex.ts在createBuiltinMcps()中注册arxivsrc/mcp/index.test.tszauc-mocks-mcp-index/index.test.ts更新计数、属性断言与 all-disabled 用例src/mcp/AGENTS.mdAGENTS.md维护内置 MCP 清单文档从源码结构看oh-my-openagent 的内置 MCP 扩展已经形成了一套高度模式化的流程静态导出配置对象 → 扩展 Schema 枚举 → 注册函数加条件分支 → 补测试与文档 → 本地验证 → PR 与三重门禁。为项目新增任何新的远程 MCP不止 arXiv都可以直接套用这套模板这也是该执行计划最值得复用的工程价值所在。落地时唯一需要重点确认的是目标 MCP 服务端点的真实可用性——远程端点、stdio 包装或自建 HTTP 网关三者应依据实际服务形态选择其一再按本流程推进。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
oh-my-openagent 内置 MCP 扩展实战：以 arXiv 论文搜索 MCP 为例的源码级实施指南
oh-my-openagent 内置 MCP 扩展实战以 arXiv 论文搜索 MCP 为例的源码级实施指南【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本文围绕 oh-my-openagent 开源仓库中一份真实落地的执行计划对应 Issue #100 Built-in arXiv MCP完整讲解如何为项目新增一个内置 MCPModel Context Protocol模块从 git 工作区准备、源码实现、测试与文档更新到 PR 创建、三重验证门禁与最终合并的全流程。读完本文你将掌握 oh-my-openagent 内置 MCP 的注册机制、静态导出配置模式、测试约定与 CI/审查工作流并能在本仓库中独立复现同样的扩展路径。背景oh-my-openagent 的内置 MCP 架构在 oh-my-openagent 中MCP 体系分为三层见 packages/omo-opencode/src/mcp/AGENTS.mdTier来源机制1. Built-inpackages/omo-opencode/src/mcp/远程 HTTP MCP 本地 stdio MCP经createBuiltinMcps()统一注册2. Claude Code.mcp.json${VAR}展开由claude-code-mcp-loader加载3. Skill-embeddedSKILL.md YAML由SkillMcpManager管理stdio HTTP本文讨论的 arXiv MCP 属于第一层Tier 1内置 MCP。内置 MCP 由 createBuiltinMcps 函数 统一创建其入参包括disabledMcps: string[]需要禁用的内置 MCP 名称列表命中者不会注册config?: BuiltinMcpSourceConfig可选的来源配置例如websearch的提供商参数options?: BuiltinMcpOptions运行时选项cwd、resolveExecutable等主要服务于本地 stdio 的lspMCP。目前内置 MCP 名称由McpNameSchema固定约束websearch | context7 | grep_app | lsp见 types.ts全部禁用测试用例中对应的枚举即来自此 Schema。要新增 arXiv MCP正是要在这一 Schema 中加入arxiv并在注册函数中加入条件分支。Phase 0工作区准备执行计划的第一步是建立独立的工作区与特性分支避免污染主开发线git fetch origin dev git worktree add ../omo-wt/feat/arxiv-mcp origin/dev cd ../omo-wt/feat/arxiv-mcp git checkout -b feat/arxiv-mcp要点说明使用git worktree在仓库外另建工作树可同时持有多个分支而不互相干扰适合与主仓库并行迭代从dev分支拉出特性分支feat/arxiv-mcp保证后续 PR 的基线干净。Phase 1实现内置 arXiv MCPStep 1创建src/mcp/arxiv.ts新 MCP 需遵循既有内置模块的静态导出模式static export pattern可参照context7.ts与grep-app.ts两个先例grep-app.ts 是最简形态——直接导出一个纯静态配置对象export const grep_app { type: remote as const, url: https://mcp.grep.app, enabled: true, oauth: false as const, }context7.ts 则在静态对象基础上支持可选环境变量鉴权导出的是RemoteMcpConfigexport function createContext7Config(env: Recordstring, string | undefined process.env): RemoteMcpConfig { const context7ApiKey normalizeContext7ApiKey(env.CONTEXT7_API_KEY) return { type: remote as const, url: https://mcp.context7.com/mcp, enabled: true, ...(context7ApiKey ? { headers: { Authorization: Bearer ${context7ApiKey} } } : {}), oauth: false as const, } }RemoteMcpConfig的类型定义见 index.ts要求type: remote、url、enabled字段可选headers与oauth: false。对于 arXiv其 API 是公开的无需鉴权。执行计划中假设的远程端点为https://mcp.arxiv.org——注意这是计划中标注的假设性端点hypothetical remote MCP endpoint仓库中目前并不存在该服务。原计划明确指出若不存在现成的远程 arXiv MCP则需要改为 stdio MCP 或自建 HTTP 包装层本计划按与既有内置项一致的远程 MCP 端点模式继续推进。落地时若端点不可用应回归到本地 stdio 方案即参照 lsp.ts 的LocalMcpConfig形态本地命令行 resolveExecutable解析器。Step 2更新src/mcp/types.ts在McpNameSchema枚举中追加arxivexport const McpNameSchema z.enum([websearch, context7, grep_app, arxiv])对应到仓库中的实际文件为 packages/omo-opencode/src/mcp/types.ts同时需注意McpName类型z.infer会自动随之扩展。此外配置侧 Schema 位于 packages/omo-opencode/src/config/schema/oh-my-opencode-config.ts若用户配置文件需要显式禁用该 MCP还需同步配置 Schema 的联合类型。Step 3更新src/mcp/index.ts在createBuiltinMcps()中引入并注册 arXiv 模块对应仓库文件 packages/omo-opencode/src/mcp/index.tsimport { arxiv } from ./arxiv // ... if (!disabledMcps.includes(arxiv)) { mcps.arxiv arxiv }该条件分支与既有context7、grep_app的注册模式完全一致——凡是出现在disabledMcps数组中的名称都不会被注入到返回的mcps记录中。Step 4创建src/mcp/arxiv.test.ts测试应覆盖 arXiv 配置的形状shapetype必须为remoteurl必须为期望的 arXiv 端点enabled必须为trueoauth必须为false。测试写法遵循仓库现有的 given/when/then 结构可参考 context7.test.ts 与 websearch.test.ts。例如// given: arXiv 配置被创建 // when: 读取 arxiv 配置对象 // then: 其 url / enabled / oauth 字段符合预期Step 5更新src/mcp/index.test.ts注册函数测试需要同步三处仓库中对应 zauc-mocks-mcp-index/index.test.ts该测试通过 mock 模块逐项断言result.websearch、result.grep_app等属性是否toBeDefined()将默认返回的内置 MCP 数量从 3 更新为 4在toHaveProperty断言中追加arxiv在 all disabled 用例的disabledMcps数组中追加arxiv并断言剩余名称中不再包含它。Step 6更新src/mcp/AGENTS.md将 arxiv 行追加到内置 MCP 表格仓库中对应 packages/omo-opencode/src/mcp/AGENTS.md表格字段包括Name、Type、Endpoint / Command、Env Vars、Tools。按当前文档体例arxiv 一行大致应为NameTypeEndpoint / CommandEnv VarsToolsarxivremotemcp.arxiv.org假设端点NonearXiv 论文检索同时需更新文首的内置 MCP 数量当前标题为 4 Built-in MCPs与McpNameSchema枚举描述、三层次表格中的 3 remote HTTP MCPs 1 local stdio MCP 统计使其与实际注册数一致。Step 7本地验证bun run typecheck bun test src/mcp/ bun run buildtypecheck确认McpNameSchema扩展后类型推断正确单测跑通src/mcp/下全部测试含新增arxiv.test.ts与更新后的注册函数测试build确认打包产物正常生成。原子提交Atomic Commits按职责拆分为三个互相独立、可回滚的提交feat(mcp): add arxiv paper search built-in MCP——arxiv.tstypes.ts更新test(mcp): add arxiv MCP tests——arxiv.test.tsindex.test.ts更新docs(mcp): update AGENTS.md with arxiv MCP——AGENTS.md更新。Phase 2PR 创建git push -u origin feat/arxiv-mcp gh pr create --base dev --title feat(mcp): add built-in arXiv paper search MCP --body-file /tmp/pull-request-arxiv-mcp-*.md要点--base dev与 Phase 0 的工作树基线一致PR 正文从预生成的模板文件读取便于在本地先撰写、再提交。Phase 3验证循环Verify Loop合并前需要依次通过三道门禁任一门禁失败则修复后重新进入循环Gate ACI等待ci.yml工作流tests、typecheck、build通过使用gh run watch或轮询gh pr checks观察状态。Gate Breview-work 技能审查运行/review-work技能触发 5 个 Agent 并行审查五个审查角色必须全部通过Oracle目标一致性、Oracle代码质量、Oracle安全、QA 执行、上下文挖掘context mining。Gate CCubic 自动化审查等待cubic-dev-ai[bot]的自动化审查结果必须显示 No issues found若发现问题修复并重新推送。失败处理策略失败门禁处理方式Gate A 失败本地修复amend 或新增提交重新推送Gate B 失败处理 review-work 发现项新增提交Gate C 失败处理 Cubic 发现项新增提交修复后从 Gate A 重新进入验证循环直到三道门禁全部通过。Phase 4合并gh pr merge --squash --delete-branch git worktree remove ../omo-wt/feat/arxiv-mcp git branch -D feat/arxiv-mcp # 若未随 PR 自动删除采用 squash 合并将特性分支的多个原子提交折叠为单一提交进入dev随后清理工作树与本地分支保持环境整洁。总结把执行计划映射到本仓库的真实代码本执行计划中的src/mcp/路径在仓库中对应 packages/omo-opencode/src/mcp/ 目录其既有文件与计划步骤的对应关系如下计划中的文件仓库实际文件在计划中的角色src/mcp/arxiv.ts待新建参照 context7.ts、grep-app.ts静态导出 arXiv 远程 MCP 配置src/mcp/types.tstypes.ts扩展McpNameSchema枚举src/mcp/index.tsindex.ts在createBuiltinMcps()中注册arxivsrc/mcp/index.test.tszauc-mocks-mcp-index/index.test.ts更新计数、属性断言与 all-disabled 用例src/mcp/AGENTS.mdAGENTS.md维护内置 MCP 清单文档从源码结构看oh-my-openagent 的内置 MCP 扩展已经形成了一套高度模式化的流程静态导出配置对象 → 扩展 Schema 枚举 → 注册函数加条件分支 → 补测试与文档 → 本地验证 → PR 与三重门禁。为项目新增任何新的远程 MCP不止 arXiv都可以直接套用这套模板这也是该执行计划最值得复用的工程价值所在。落地时唯一需要重点确认的是目标 MCP 服务端点的真实可用性——远程端点、stdio 包装或自建 HTTP 网关三者应依据实际服务形态选择其一再按本流程推进。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
