Xinyang KB MCP

芯阳内部知识库 MCP 服务，同时支持 Codex 和 OpenCode。

环境要求

• Node.js 18+

• Codex CLI 和/或 OpenCode

• 可访问芯阳内部搜索 API

仓库已提交独立运行产物 plugins/xinyang-kb/dist/index.js。使用者安装时不需要执行 npm install。

一键安装

搜索 API 地址默认为 http://10.1.120.36:5010/search，无需显式提供即可安装：

node scripts/install.cjs

安装器会自动检测 Codex 和 OpenCode，并保留未涉及的现有配置。修改已有 JSON 配置前会生成带时间戳的备份。

可选参数：

Windows

.\scripts\install.ps1

Linux / macOS

./scripts/install.sh

更换搜索地址（无需重装）

安装完成后，如需切换到其他知识库地址，运行一行命令即可，无需重新执行安装流程：

node scripts/set-url.cjs http://10.1.120.36:5010/search

脚本会直接更新运行时配置 ~/.config/xinyang-kb/config.json，并自动备份原文件。

基础地址自动推导：

• 当 URL 以 /search/dify 或 /search 结尾时，基础地址自动取去掉该后缀的部分。

  node scripts/set-url.cjs http://10.1.120.36:5010/search
  # searchApiUrl     = http://10.1.120.36:5010/search
  # apiServerBaseUrl = http://10.1.120.36:5010

• 否则基础地址与搜索地址相同。

  node scripts/set-url.cjs http://10.1.120.36:5010/custom
  # searchApiUrl = apiServerBaseUrl = http://10.1.120.36:5010/custom

如需显式指定基础地址，追加 --api-base：

node scripts/set-url.cjs http://10.1.120.36:5010/custom/search --api-base http://10.1.120.36:5010

更新完成后重启 Codex/OpenCode 并新建会话即可生效。

Codex

直接注册

默认安装方式。安装器执行 codex mcp add，并将 Skill 安装到 ~/.codex/skills/xinyang-assistant。

node scripts/install.cjs --codex-mode direct --no-opencode

插件安装

仓库采用标准 Marketplace 布局：

.agents/plugins/marketplace.json
plugins/xinyang-kb/

安装命令：

node scripts/install.cjs --codex-mode plugin --no-opencode

插件同时携带 MCP 和 xinyang-assistant Skill。安装完成后请重启 Codex 并新建会话。

OpenCode

OpenCode 继续使用已验证的配置格式：

• 配置文件：~/.config/opencode/opencode.json

• MCP 类型：local

• 环境字段：environment

• Skill：~/.config/opencode/skills/xinyang-assistant/SKILL.md（由 OpenCode 的 skill 工具自动发现，无需在 instructions 中引用）

仅安装 OpenCode：

node scripts/install.cjs --no-codex

安装器会合并已有 JSON，不覆盖其他 MCP 或用户设置。升级时还会自动清理旧版的单文件 skill 及其 instructions 引用。若原配置不是有效 JSON，安装会停止且不会覆盖文件。

配置

搜索 API 默认地址为 http://10.1.120.36:5010/search。运行时可通过以下方式自定义（优先级从高到低）：

1. 工具调用参数 search_api_url（单次调用覆盖）

2. SEARCH_API_URL、API_SERVER_BASE_URL 环境变量

3. ~/.config/xinyang-kb/config.json

4. 内置默认值 http://10.1.120.36:5010/search

当只提供 SEARCH_API_URL 时，API_SERVER_BASE_URL 会自动从其中推导（若以 /search/dify 或 /search 结尾则截取基础地址，否则与搜索地址相同）。

插件模式使用用户配置文件；直接注册模式同时注入环境变量。

卸载

Codex

如果使用 direct 模式安装：

codex mcp remove xinyang-kb

然后删除 Skill：

~/.codex/skills/xinyang-assistant/

如果使用 plugin 模式安装：

codex plugin remove xinyang-kb@xinyang-internal

如不再使用本仓库 Marketplace，可继续执行：

codex plugin marketplace remove xinyang-internal

both 模式需要同时执行 direct 和 plugin 两组卸载操作。

OpenCode

编辑 ~/.config/opencode/opencode.json，删除 mcp 中的 xinyang-kb。

然后删除 skill 目录：

~/.config/opencode/skills/xinyang-assistant/

共享运行配置

确认 Codex 和 OpenCode 都不再使用本 MCP 后，可删除：

~/.config/xinyang-kb/config.json

卸载后重启 Codex 或 OpenCode，并新建会话。

开发与验证

npm ci
npm run typecheck
npm run build

常用检查：

codex mcp list
codex plugin marketplace list
codex plugin list
opencode mcp list

工具

knowledge_base_search 用于搜索芯阳内部产品参数、技术方案、制度、流程、项目和内部文档。返回结果中的内部文档路径会转换为可引用 URL。

参数：