oh-my-opencode-slim 内置 MCP 服务器架构：context7 与 gh_grep 的配置、权限与禁用机制

人工智能AI AgentAgent 编排AI 技能【免费下载链接】oh-my-opencode-slimLean, fine tuned Opencode multi agent suite · Mix any models · Auto delegate tasks项目地址https://gitcode.com/gh_mirrors/oh/oh-my-opencode-slim点击查看免费下载本文围绕 oh-my-opencode-slim 插件中src/mcp/模块展开深入剖析其内置 Model Context ProtocolMCP服务器context7与gh_grep的配置结构、初始化流程、按 Agent 授权的权限机制以及全局禁用方案。读完本文你将掌握如何为 OpenCode 插件配置内置 MCP 端点、如何为不同 Agent 精确分配 MCP 访问权以及如何基于源码理解这套类型安全配置系统的底层原理。MCP 模块的职责与设计src/mcp/模块负责为 OpenCode 插件定义 MCP 服务器配置与集成通过 MCP 标准让 Agent 访问外部工具与资源。模块的职责定位集中在两点文档查询documentation lookup与代码搜索code search。从架构设计看该目录采用模块化 MCP 配置系统核心由三部分组成类型定义types.tsMCP 配置的核心类型系统包含RemoteMcpConfig、LocalMcpConfig与联合类型McpConfig内置 MCP 服务器预配置的远程 MCP 端点覆盖常见开发任务工厂模式index.ts集中创建与管理 MCP 配置并支持用户配置覆盖。两种 MCP 服务器类型类型用途典型使用场景RemoteMcpConfig通过 URL 连接托管的 MCP 服务器文档查询、代码搜索LocalMcpConfig以本地进程方式启动 MCP 服务器自定义工具集成以 types.ts 的源码实现来看RemoteMcpConfig结构为{ type: remote; url: string; headers?: Recordstring, string; oauth?: false }其中headers用于携带认证信息如 API Keyoauth字段被限定为false即内置远程服务器一律不使用 OAuth 流程。LocalMcpConfig结构为{ type: local; command: string[]; environment?: Recordstring, string }command是以数组形式给出的启动命令environment用于注入子进程环境变量——该类型为将来接入本地 MCP 工具进程预留了空间。内置 MCP 服务器详解模块预置了两个远程 MCP 服务器分别定义在 context7.ts 与 grep-app.ts 中。context7库的官方文档查询context7提供库的官方实时更新的文档查询能力其端点配置为https://mcp.context7.com/mcp。认证采用CONTEXT7_API_KEY环境变量// src/mcp/context7.ts节选 export const context7: RemoteMcpConfig { type: remote, url: https://mcp.context7.com/mcp, headers: process.env.CONTEXT7_API_KEY ? { CONTEXT7_API_KEY: process.env.CONTEXT7_API_KEY } : undefined, oauth: false, };实现细节值得注意headers字段是条件注入的——仅当CONTEXT7_API_KEY环境变量存在时才附加认证头否则为undefined。这意味着即使未配置 API Key服务器配置依然合法只是以匿名方式访问。gh_grepGitHub 代码搜索gh_grep提供跨 GitHub 仓库的超快代码搜索底层基于 grep.app端点配置为https://mcp.grep.app用于在公共仓库中查找代码示例与模式// src/mcp/grep-app.ts节选 export const gh_grep: RemoteMcpConfig { type: remote, url: https://mcp.grep.app, oauth: false, };与context7不同gh_grep不需要认证头因此配置最为简洁。两个服务器均将oauth显式设为false这是模块安全策略的一部分详见后文安全小节。初始化流程工厂模式与禁用过滤MCP 配置的创建统一由 index.ts 中的createBuiltinMcps()函数完成。其初始化流程如下Plugin loads → createBuiltinMcps() called with disabledMcps list ↓ Filters built-in MCP list to exclude disabled servers ↓ Creates RemoteMcpConfig instances for each enabled server ↓ Returns record of McpConfig objects to main plugin源码实现中allBuiltinMcps是一个以McpName为键、McpConfig为值的记录包含context7与gh_grep两个内置服务器。createBuiltinMcps()的完整逻辑为// src/mcp/index.ts export function createBuiltinMcps( disabledMcps: readonly string[] [], ): Recordstring, McpConfig { // 运行时绝不信任来自用户配置的声明类型 // 若非数组则回退为全部不禁用而不是抛错。 const safeDisabledMcps Array.isArray(disabledMcps) ? disabledMcps : []; return Object.fromEntries( Object.entries(allBuiltinMcps).filter( ([name]) !safeDisabledMcps.includes(name), ), ); }两个关键的工程决策体现在这里类型安全映射McpName类型定义在 config/schema.ts 中z.enum([context7, gh_grep])与src/config/共享避免重复定义src/mcp/通过import type { McpName } from ../config复用。防御式运行时校验safeDisabledMcps对用户配置派生的disabledMcps做Array.isArray检查若用户传入了非数组的畸形值如字符串会静默回退为全部不禁用避免插件初始化崩溃。这一行为在 index.test.ts 中有专门回归测试createBuiltinMcps( as any)必须返回全部 2 个 MCP。运行期流程注册与按 Agent 授权MCP 的生命周期分为两个阶段配置阶段插件初始化时createBuiltinMcps()在插件主入口 src/index.ts 被调用传入runtime.disabledMcps用户配置与默认值合并被禁用的 MCP 被过滤掉。集成阶段Agent 执行期间MCP 服务器注册到 MCP 运行时Agent 通过 MCP 协议发起工具调用请求MCP 服务器执行请求并把结果返回给 Agent。在配置阶段主入口还承担了将内置 MCP 合并进 OpenCode 配置并生成权限规则的职责src/index.ts若opencodeConfig.mcp不存在则整体写入{ ...mcps }若已存在则通过Object.assign(configMcp, mcps)合并内置服务器从而保留用户自定义的 MCP 服务器对每个配置了mcps数组的 Agent基于服务器名 _*的通配形式生成权限键MCP 工具实际命名为server_tool例如context7_*并根据允许列表决定allow/deny仅当用户未显式定义该权限键时才写入保证用户自定义权限优先。mcps列表的解析逻辑位于 config/agent-mcps.ts 的parseList()支持*通配展开全部可用 MCP、!item排除指定 MCP、!*否定全部冲突时如[a, !a]deny 优先。按 Agent 的默认 MCP 权限config/agent-mcps.ts 中定义了各内置 Agent 的默认 MCP 列表Agent默认 MCPorchestrator*、!context7全部 MCP 但排除 context7librariancontext7、gh_grepdesigner无oracle无explorer无fixer无observer/council/councillor无可见librarian图书管理员 Agent是唯一默认同时持有两个 MCP 的 Agent与其检索资料的职能定位一致而orchestrator虽可使用全部 MCP但被排除掉context7避免编排者在检索类工具上消耗过多上下文。用户配置禁用与授权覆盖全局禁用disabled_mcps若需对全部 Agent 禁用特定 MCP可在配置根节点声明disabled_mcps。对应 Schema 定义位于 config/schema.ts描述为MCP 服务器名完全禁用被禁用的服务器不会启动、Agent 无法使用。示例// 例如 ~/.config/opencode/oh-my-opencode-slim.json或 .jsonc { disabled_mcps: [gh_grep] }这一配置常用于完全切断外部网络调用的场景如离线隔离环境或成本控制。注意disabled_mcps是全局一刀切而下面的mcps是按 Agent 细粒度授权。按 Agent 授权preset 中的mcps数组在预设preset配置中可通过mcps数组为每个 Agent 指定可用的 MCP语法含义[*]全部 MCP[*, !context7]全部 MCP 但排除context7[context7, gh_grep]仅列出的 MCP[]不授予任何 MCP[!*]否定全部 MCP规则要点*展开为所有可用 MCP!item排除指定项冲突时 deny 优先例如[a, !a]最终拒绝a。完整示例{ presets: { my-preset: { orchestrator: { mcps: [*, !context7] }, librarian: { mcps: [context7, gh_grep] }, oracle: { mcps: [*, !gh_grep] }, fixer: { mcps: [] } } } }这套授权机制与默认权限、权限键注入共同构成默认值 用户覆盖的完整策略getAgentMcpList()config/agent-mcps.ts会优先读取配置中的mcps未配置时才回退到DEFAULT_AGENT_MCPS。错误处理与防御策略缺少 API Keycontext7的认证头按环境变量条件注入未设置时静默降级为匿名访问不会抛出异常非法配置TypeScript 类型系统在编译期阻止非法配置如oauth仅允许false畸形禁用列表createBuiltinMcps()对非数组输入回退为全部不禁用保证插件初始化不崩溃被禁用服务器从输出记录中被优雅过滤不产生错误权限冲突parseList()中 deny 优先于 allow。测试覆盖src/mcp/index.test.ts 围绕createBuiltinMcps()提供了完整单元测试无禁用列表 / 空禁用列表时返回全部 2 个 MCP禁用单个[gh_grep]或全部时正确过滤禁用列表含未知名称[unknown_mcp, nonexistent]时不影响有效 MCP每个 MCP 配置必须含url远程或command本地context7与gh_grep的结构校验非数组disabledMcps的回归测试不抛错。配置层另有 Schema 校验保证用户配置与期望类型一致如disabled_mcps为字符串数组。此外主入口 src/index.ts 的健康检查会统计实际启用的 MCP 数量mcpCount当存在禁用项时阈值降为 0否则要求不小于HEALTH_CHECK.minMcps确保 MCP 注册环节可观测。性能与安全考量性能方面惰性初始化MCP 配置在插件初始化时仅创建一次运行期零重复解析最小开销类型安全配置无运行时解析成本连接池远程 MCP 服务器自行管理连接插件无需关心连接生命周期。安全方面API Key 不硬编码始终从环境变量CONTEXT7_API_KEY读取关闭 OAuth所有内置 MCP 均显式oauth: false输入校验TypeScript 类型系统保证配置正确性运行时另有Array.isArray防御HTTPS所有远程端点https://mcp.context7.com/mcp、https://mcp.grep.app均使用 HTTPS 加密通信。消费者与扩展点src/mcp/的消费者关系清晰主消费者src/index.ts插件入口在初始化时调用createBuiltinMcps()接收McpConfig记录后注册进 OpenCode配置层src/config/ 提供McpName类型与 MCP 配置 Schemaschema.ts并负责校验用户配置API 面从types.ts导出RemoteMcpConfig、LocalMcpConfig、McpConfig类型从index.ts导出createBuiltinMcps()函数以及context7、gh_grep预配置常量src/index.ts 还对外重导出了RemoteMcpConfig。扩展方式如需新增内置 MCP 服务器只需在src/mcp/下新增一个遵循McpConfig类型的常量文件远程服务器给出url与可选headers并将其注册进 index.ts 的allBuiltinMcps记录同时把服务器名加入 config/schema.ts 的McpNameSchema枚举即可用户侧则可通过自定义 MCP 配置与 preset 中的mcps数组完成接入与授权。与 websearch 内置工具的分工需要说明的是oh-my-opencode-slim 自旧版本起已不再内置 websearch MCP 服务器OpenCode 自带的websearch工具Exa 后端可选 Parallel取代了它的位置无需 API Key 或额外 MCP 服务器。内置 MCPcontext7、gh_grep与 OpenCode 内置的websearch工具在能力上是互补的前者负责库文档查询与GitHub 代码搜索后者负责通用网络搜索。在配置 MCP 权限时两者相互独立permission规则可分别控制websearch工具与server_*形式的 MCP 工具。赞分享人工智能AI AgentAgent 编排AI 技能【免费下载链接】oh-my-opencode-slimLean, fine tuned Opencode multi agent suite · Mix any models · Auto delegate tasks项目地址https://gitcode.com/gh_mirrors/oh/oh-my-opencode-slim点击查看免费下载相关推荐oh-my-opencode-slim 内置 MCP 与 websearch 接入指南context7、gh_grep 的配置、权限与全局禁用oh my opencode slim 内置 MCP 与 websearch 接入指南context7、gh_grep 的配置、权限与全局禁用 导读 oh m人工智能AI AgentAgent 编排AI 技能oh-my-opencode-slim 项目级本地定制完全指南按仓库配置 Agent、Prompt、技能与 MCPoh my opencode slim 项目级本地定制完全指南按仓库配置 Agent、Prompt、技能与 MCP 导读 oh my opencode sli人工智能AI AgentAgent 编排AI 技能oh-my-opencode-slim 韩文版指南Opencode 多智能体编排插件的架构、安装与配置实战oh my opencode slim 韩文版指南Opencode 多智能体编排插件的架构、安装与配置实战 本文以 README.ko KR.md https人工智能AI AgentAgent 编排AI 技能上一篇Wand-Enhancer 使用指南免费为 Wand(WeMod) 客户端打补丁并解锁手机远程面板下一篇DeepLearning循环神经网络自然语言处理核心技术终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考