# 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`，无需显式提供即可安装：

```bash
node scripts/install.cjs
```

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

可选参数：

| 参数 | 说明 |
|---|---|
| `--api-url <URL>` | 覆盖默认搜索地址 `http://10.1.120.36:5010/search` |
| `--api-base <URL>` | 显式指定基础地址；默认从 `--api-url` 自动推导 |
| `--codex-mode direct` | 直接注册 Codex MCP，默认模式 |
| `--codex-mode plugin` | 通过本仓库 Marketplace 安装 Codex 插件 |
| `--codex-mode both` | 同时安装两种 Codex 接入方式 |
| `--no-codex` | 跳过 Codex |
| `--no-opencode` | 跳过 OpenCode |
| `--no-proxy <列表>` | 显式写入 MCP 的 `no_proxy` 环境变量 |

### Windows

```powershell
.\scripts\install.ps1
```

### Linux / macOS

```bash
./scripts/install.sh
```

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

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

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

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

**基础地址自动推导：**

- 当 URL 以 `/search/dify` 或 `/search` 结尾时，基础地址自动取去掉该后缀的部分。
  ```bash
  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
  ```
- 否则基础地址与搜索地址相同。
  ```bash
  node scripts/set-url.cjs http://10.1.120.36:5010/custom
  # searchApiUrl = apiServerBaseUrl = http://10.1.120.36:5010/custom
  ```

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

```bash
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`。

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

### 插件安装

仓库采用标准 Marketplace 布局：

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

安装命令：

```bash
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：

```bash
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 模式安装：

```bash
codex mcp remove xinyang-kb
```

然后删除 Skill：

```text
~/.codex/skills/xinyang-assistant/
```

如果使用 plugin 模式安装：

```bash
codex plugin remove xinyang-kb@xinyang-internal
```

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

```bash
codex plugin marketplace remove xinyang-internal
```

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

### OpenCode

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

然后删除 skill 目录：

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

### 共享运行配置

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

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

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

## 开发与验证

```bash
npm ci
npm run typecheck
npm run build
```

常用检查：

```bash
codex mcp list
codex plugin marketplace list
codex plugin list
opencode mcp list
```

## 工具

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

参数：

| 参数 | 说明 |
|---|---|
| `query` | 必填，知识库检索关键词 |
| `search_api_url` | 可选，覆盖本次调用的搜索 API 地址，默认 `http://10.1.120.36:5010/search` |