codebase-memory-mcp 去依赖 SOP

目标

在需要使用 codebase-memory-mcp 时，尽量绕过 npm / PyPI / go install 这些包装层，直接接入仓库 release 的真实二进制。

已验证结论

1. README.md 明确写了该项目是 single static binary, zero infrastructure；默认持久化目录为 ~/.cache/codebase-memory-mcp/。
2. README.md 的 Installation 章节给出了 macOS / Linux / Windows 的预编译包，并明确说明：All binaries are statically linked — no shared library dependencies。
3. README.md 给出了手动 MCP 配置，command 直接指向 /path/to/codebase-memory-mcp，args 为空数组。
4. README.md 的 Build from Source 写明源码构建前置仅有：C compiler、C++ compiler、zlib、Git；构建命令是 scripts/build.sh，产物在 build/c/codebase-memory-mcp。
5. Python 包装层 pkg/pypi/src/codebase_memory_mcp/_cli.py 文件头直接说明：首次运行下载 binary，然后 exec。
6. Go 包装层 pkg/go/cmd/codebase-memory-mcp/main.go 会在缓存里找真实 binary；若不存在，就从 GitHub Releases 下载对应平台压缩包，（如能取到）校验 checksums.txt，解压后再 exec 真正 binary。
7. npm 包装层由 pkg/npm/install.js + pkg/npm/bin.js 组成：postinstall 下载 GitHub Releases 二进制并尝试校验 checksum；运行时 bin.js 只是寻找本地 binary，缺失则再触发一次下载，然后 spawnSync 真正 binary。

结论翻译成操作策略

优先级 1：直接使用 release 二进制

适用：大多数本机 / CI / MCP 客户端集成场景。

做法：

1. 按系统架构从 releases 下载对应压缩包。
2. 用 release 自带的 checksums.txt 校验 SHA-256。
3. 解压出 codebase-memory-mcp（Windows 为 .exe）到稳定路径。
4. 在 MCP 配置里直接把 command 指向这个二进制。

README 中的手动配置模板：

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

这样做的直接收益：

• 少一层 npm/pip/go 包管理器行为；
• 安装路径更可控；
• 排障时面对的就是实际运行的可执行文件。

优先级 2：被迫走 pip / npm / go install 时的认知

已读文件里，这三个入口都表现为“薄包装层”：

• Python：下载后二进制 exec
• Go：下载、校验、缓存后二进制 exec
• npm：postinstall 下载；启动时 spawnSync 二进制

因此排障时要先分层：

1. 是包装层的 下载 / 校验 / 解压 / 缓存 出问题；
2. 还是真实 codebase-memory-mcp 二进制本身运行有问题。

如果目标是“去依赖”，通常不要卡在修包装层，直接切回 release 二进制更省事。

优先级 3：只有 release 不适用时再源码构建

仅在这些情况下退回源码构建：

• 目标平台没有现成 release；
• 需要修改源码；
• 需要调试底层实现。

最小前置：

• C compiler
• C++ compiler
• zlib
• Git

构建方式：

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh
# binary at build/c/codebase-memory-mcp

排障顺序

1. 先确认你到底在运行谁
   • 直接 release 二进制？
   • pip / npm / go 的包装层？
2. 若是包装层，先查下载、校验、解压、缓存路径
3. 若目的是降复杂度，直接换成 release 二进制 + 手动 MCP 配置
4. 只有 release 方案不适用时才退回源码构建

一句话记忆

codebase-memory-mcp 的核心是 release 静态单二进制；pip/npm/go 入口主要负责下载并转交给这个二进制，去依赖时优先直连 release binary。

本 SOP 的证据文件

• README.md
• pkg/pypi/src/codebase_memory_mcp/_cli.py
• pkg/go/cmd/codebase-memory-mcp/main.go
• pkg/npm/bin.js
• pkg/npm/install.js