CodeWeave

CodeWeave 是一个本地优先的 MCP 服务器，为 AI 编码客户端提供精确的搜索、受保护的编辑、Git 操作、语义智能以及在一个仓库内受限的 Bash 执行。

它专为那些希望拥有强大编码工具，但又不想在仓库间静默切换、隐藏部分编辑或将整个机器发送到远程服务的开发者而设计。

快速开始

你需要 Rust、Git 和 Bash。Windows 用户可以使用 Git for Windows 附带的 Bash。

cargo install --git https://github.com/abhij1306/codeweave --locked
codeweave install

交互式安装程序会：

• 询问 CodeWeave 应服务于哪个仓库；

• 推荐本地 stdio 或配置回环 HTTP；

• 创建 config.json 和一个私有源令牌；

• 检查 Git、Bash、工作区、配置、令牌权限、端口以及热索引启动；

• 打印一个可直接粘贴的 MCP 客户端命令。

如需自动化，请跳过向导：

codeweave init --path /absolute/path/to/repository --config config.json
codeweave doctor --config config.json

Related MCP server: MatterAI MCP Server

连接客户端

本地客户端：stdio

Stdio 是最简单且最安全的传输方式。安装程序会打印如下代码块：

{
  "command": "/absolute/path/to/codeweave",
  "args": ["serve", "--transport", "stdio", "--config", "/absolute/path/to/config.json"]
}

将其粘贴到任何接受本地命令的 MCP 客户端中。

回环 HTTP

codeweave serve --transport http --config config.json

默认情况下，本地端点为 http://127.0.0.1:8813/mcp。HTTP 需要使用存储在 .mcp-token 中的 bearer 令牌；该令牌是一个私有源凭证，不是 LLM API 密钥，也不是外部用户认证。

远程客户端

切勿仅通过将回环源的 bearer 注入每个公共请求来发布该回环源。公共网关必须首先对每个外部调用者进行身份验证，然后添加私有源 bearer 以跳转到 CodeWeave。

附带的 PowerShell 辅助程序在 ngrok 处使用强制性的 HTTP Basic 身份验证，然后替换源 bearer：

.\start-ngrok.ps1 -Config .\config.json

PowerShell 会提示输入公共用户名和密码。仅将此辅助程序用于支持 Basic 凭据的客户端。仅支持 URL 的托管连接器需要支持 OAuth 的 MCP 网关。请参阅 ChatGPT 设置 和 Claude 设置。

CodeWeave 暴露的内容

CodeWeave 提供一个固定的 25 个工具的表面：

• 发现：workspace、code_retrieve、code_intelligence；

• 受保护的编辑：code_write、code_replace、code_replace_range、code_insert、code_delete、code_rename、code_preview、code_transaction；

• Git：git_status、git_diff、git_log、git_show、git_blame、git_preflight、git_stage、git_commit、git_restore、git_push；

• 命令：bash、bash_status、bash_output、bash_cancel。

仓库在进程生命周期内是固定的。所有连接的客户端共享相同的工作区变更、生成和 Bash 运行。

安全模型

CodeWeave 是特权开发者工具。经过身份验证的客户端可以以你的操作系统账户身份运行无沙箱的 Bash，因此只连接你信任的客户端和模型。

服务器仍然围绕该信任强制执行更窄的不变量：

• 文件读写被能力限制在配置的工作区内；

• 快照哈希、范围句柄和预期内容检查保护编辑；

• 多文件编辑会如实报告部分应用和恢复失败；

• Git 路径参数和破坏性操作使用验证和显式确认；

• HTTP 身份验证在读取受限的 4 MiB 请求体之前进行；

• 源仅接受 HTTP/1 并限制并发连接数；

• Bearer 文件在 Unix 上使用 0600 权限，在 Windows 上使用受保护的显式 DACL。

在将 HTTP 暴露到回环之外之前，请阅读 SECURITY.md。

配置

codeweave install 会创建一个严格的 configVersion: 2 配置。未知字段会被拒绝，包括未知的嵌套字段。请参阅 config.example.json 了解所有选项。

有用的命令：

codeweave doctor --config config.json
codeweave serve --transport stdio --config config.json
codeweave serve --transport http --config config.json

可选的语义后端包括 rust-analyzer、basedpyright-langserver 和 typescript-language-server。它们默认禁用，直到在生成的配置中启用。

不要提交 config.json、.mcp-token 或 .codeweave-cache/。

更新

从 GitHub 安装最新版本：

cargo install --git https://github.com/abhij1306/codeweave --locked --force
codeweave doctor --config /path/to/config.json

较旧的 Windows 版本创建的 bearer 文件具有继承的权限。如果 doctor 拒绝此类文件，请停止 CodeWeave，仅删除配置的令牌文件，然后重新启动，以便使用受保护的 DACL 轮换令牌。

开发

git clone https://github.com/abhij1306/codeweave.git
cd codeweave
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

架构和并发保证位于 docs/architecture.md 中。工具合约记录在 docs/tools.md 中，欢迎通过 CONTRIBUTING.md 贡献。