内容
# 开源代码库内存MCP
[](https://opencode.ai/docs/mcp-servers/)
[](https://github.com/DeusData/codebase-memory-mcp)
[](LICENSE)
**OpenCode 安装程序和修复程序**，适用于 [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) — 本地代码知识图 MCP（14种工具）。
上游提供其自己的二进制MCP服务器。该项目使其能够被 **OpenCode可靠地发现**，并具有正确的全局路径和配置格式。
仓库：https://github.com/stevenke1981/opencode-codebase-memory-mcp
---
## 为什么OpenCode无法找到它
| 问题 | 发生了什么 |
|---------|---------------|
| **错误的二进制路径** | `opencode.jsonc` 指向 `C:\Users\eda\.local\bin\...` — 另一台用户的机器 |
| **旧版MCP格式** | 旧的 `{ "command": "...", "args": [] }` 而不是 OpenCode 的 `{ "type": "local", "command": ["..."] }` |
| **配置合并冲突** | `opencode.json` 和 `opencode.jsonc` 同时存在；`.jsonc` 中的损坏条目覆盖了好的条目 |
| **超时时间短** | 默认 5 秒 MCP 超时时间；codebase-memory-mcp 在首次连接时需要更多时间 |
| **便携式路径** | Windows: `pwsh` + `$env:USERPROFILE`; Linux/macOS: `sh` + `$HOME`（安装时自动检测） |
此安装程序修复了上述所有问题。
---
## 适用于人类的快速入门
### 安装（全局，`~/.config`）
```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```
或者，如果您已经拥有上游二进制文件：
```powershell
powershell -ExecutionPolicy Bypass -File install.ps1 -UseExisting
```
**macOS / Linux：**
```bash
bash install.sh
# 或：bash install.sh --use-existing
```
### 安装内容
| 路径 | 用途 |
|------|---------|
| `~/.config/opencode-codebase-memory-mcp/bin/` | `codebase-memory-mcp` 二进制文件 |
| `~/.config/opencode/codebase-memory-mcp.json` | 本地设置（超时时间，路径） |
| `~/.config/opencode/opencode.json(c)` | OpenCode 的 MCP 注册 |
### OpenCode 加载说明
这是一个 **MCP 服务器**，而不是 OpenCode 插件。它应该在 `opencode.json(c)` 的 `mcp` 部分下注册，并具有：
- `"type": "local"`
- `"command": ["pwsh", "-NoProfile", "-Command", "..."]` 在 Windows 上
- 宽容的超时时间（默认为 `60000` 毫秒）
不要将 `mcps/codebase-memory-mcp/tools/*.json` 文件复制到 `~/.config/opencode/plugins/`。它们是 IDE/运行环境发现的工具模式，不是插件入口。
### 验证
```bash
node scripts/doctor.mjs
```
重启 OpenCode，然后：
```bash
opencode mcp list
opencode run "call list_projects from codebase-memory-mcp"
```
### 首次在仓库中使用
告诉 OpenCode：**"索引此项目"** — 或代理调用 `index_repository`。
### 故障排除
| 症状 | 修复方法 |
|---------|-----|
| OpenCode 中缺少 MCP | `node scripts/install-global.mjs` 然后重启 |
| 路径包含 `Users\eda` | 重新运行安装程序（过时的配置） |
| 首次连接超时 | 增加 `codebase-memory-mcp.json` 中的 `timeout`（默认为 60000） |
| 二进制文件丢失 | 在不使用 `--skip-download` 的情况下运行安装程序 |
| 需要 Windows 上的 `grep`/`find`/bash 脚本 | 与 [git-bash-opencode-plugin](https://github.com/stevenke1981/git-bash-opencode-plugin) 配对使用 Unix shell 工具（`npm`/`node` 在 PowerShell 中工作正常） |
### 许可证
MIT（安装程序）。上游 [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) 是 MIT。
---
## 适用于 AI 代理的操作说明
<!-- AGENT_README: opencode-codebase-memory-mcp v1.0 -->
您拥有用于 **结构化代码智能** 的 `codebase-memory-mcp` 工具。在查找定义、调用路径、架构或关系时，优先使用它们而不是 grep/glob。
### 何时使用 codebase-memory-mcp
| 任务 | 工具 |
|------|------|
| 首次进入仓库 / 大幅度更改后 | `index_repository` |
| 查找函数、类、路由 | `search_graph` |
| 谁调用 X / X 调用什么 | `trace_path` |
| 按限定名称读取实现 | `get_code_snippet` |
| 架构概览 | `get_architecture` |
| 图模式 / 计数 | `get_graph_schema` |
| 类似 Cypher 的查询 | `query_graph` |
| Git 差异影响 | `detect_changes` |
| 索引文件中文本搜索 | `search_code` |
| 列出索引仓库 | `list_projects` |
**在不熟悉的代码库中启动会话：** `list_projects` → `index_repository`（如果需要）→ `search_graph` / `get_architecture`。
### 何时不使用
| 情况 | 改用 |
|-----------|-------------|
| 仓库未索引 | 先使用 `index_repository` |
| 简单的字符串文字搜索 | `Grep` 适用于文字 |
| 非代码文件 / 图中未配置的文件 | `Read` / `Grep` |
| 用户要求跳过索引 | 除非需要结构化探索，否则尊重 |
### 安装（代理）
单条命令 — 不要先用 `ls` 探测。
**Windows（PowerShell 或 bash 均适用于 node）：**
```powershell
node $env:USERPROFILE\.config\opencode-codebase-memory-mcp\scripts\install-global.mjs --use-existing
node $env:USERPROFILE\.config\opencode-codebase-memory-mcp\scripts\doctor.mjs
```
对于 `bash install.sh` 或 Unix `grep`/`find`，请使用 [git-bash-opencode-plugin](https://github.com/stevenke1981/git-bash-opencode-plugin) 中的 `bashExec`。
**macOS / Linux：**
```bash
node ~/.config/opencode-codebase-memory-mcp/scripts/install-global.mjs --use-existing
```
如果 MCP 工具不可用，请运行 doctor 并告诉用户重启 OpenCode。
### 规则
1. 优先使用 `search_graph` 而不是盲 grep 进行 **定义** 和 **关系** 查找
2. 在编辑广泛调用的函数之前使用 `trace_path`
3. 当 `list_projects` 显示仓库丢失或过时时，调用 `index_repository`
4. 不要假设 MCP 已配置 — 先检查工具可用性
5. 与 [opencode-git-tools](https://github.com/stevenke1981/git-opencode-plugin) 配对使用 git 工作流程
6. 在 Windows 上，与 [git-bash-opencode-plugin](https://github.com/stevenke1981/git-bash-opencode-plugin) 配对使用 Unix shell 工具（`grep`、`find`、`bash` 脚本）— `npm`/`node` 在 PowerShell 中工作正常
7. 永远不要将 MCP 模式 JSON 文件注册为 OpenCode 插件；只有 MCP 服务器属于 `mcp`
### 上游工具（14）
`index_repository`, `list_projects`, `delete_project`, `index_status`, `search_graph`, `trace_path`, `detect_changes`, `query_graph`, `get_graph_schema`, `get_code_snippet`, `get_architecture`, `search_code`, `manage_adr`, `ingest_traces`
<!-- END_AGENT_README -->
---
## 项目布局
```
opencode-codebase-memory-mcp/
├── scripts/
│ ├── install-global.mjs # 下载/复制二进制文件 + 注册 OpenCode MCP
│ └── doctor.mjs # 诊断路径/配置/MCP 初始化
├── mcps/codebase-memory-mcp/tools/ # IDE 运行环境发现的工具模式
├── install.ps1 / install.sh
└── config.example.json
```
