内容
# CodeWeave MCP
CodeWeave 是一个项目范围的模型上下文协议（MCP）服务器，允许 AI 编码客户端检查、编辑和验证一个配置的 Git 仓库。它设计用于本地 Windows 开发，并可通过安全隧道或临时 HTTPS 开发隧道从 ChatGPT 进行远程使用。
CodeWeave 提供了六种专注的工具：
| 工具 | 目的 |
| --- | --- |
| `code_context` | 查找任务上下文、定义、引用、精确文本、更改、仓库映射和文件大纲。 |
| `code_fetch` | 读取精确的行范围、完整文件、继续处理句柄和任务日志。 |
| `prepare_patch` | 验证和预览广泛或多文件的更改，而不修改仓库。 |
| `apply_prepared_patch` | 原子地应用先前准备的补丁计划。 |
| `apply_patch` | 应用聚焦的精确编辑、统一的差异或完整的文件操作。 |
| `run_task` | 运行在 `config.toml` 中明确允许列出的测试、检查工具、格式化工具、类型检查或构建。 |
## 安全模型
CodeWeave 绑定到一个项目根目录。文件访问在该根目录下解析，符号链接逃逸被拒绝，补丁写入由 Git 快照和可选的 SHA-256 检查保护，任务执行被限制为配置的参数数组，而不是任意的 shell 命令。
默认配置使用本地持有者令牌。机密和机器特定的文件被排除在 Git 之外：
- `.mcp-token`
- `config.toml`
- `.venv/`
- SQLite 索引和日志
- 生成的隧道策略文件
公共 `/health` 响应故意省略了本地文件系统路径。
## 要求
- Windows 10 或更新版本，附带 PowerShell
- Python 3.11、3.12 或 3.13
- Git
- 一个 Git 仓库，供 CodeWeave 操作
- 可选：OpenAI 安全 MCP 隧道、ngrok 或另一个 HTTPS 部署路径
## 安装
```powershell
git clone <仓库网址>
Set-Location codeweave
.\scripts\install.ps1
```
安装程序创建 `.venv`，以可编辑模式安装包，复制 `config.example.toml` 到 `config.toml`，并生成一个私有的 `.mcp-token`。
编辑 `config.toml` 并设置仓库根目录：
```toml
[project]
root = 'C:\path\to\your\project'
```
然后验证和索引仓库：
```powershell
.\scripts\doctor.ps1
.\scripts\index.ps1
```
## 在本地运行
在一个 PowerShell 窗口中启动服务器：
```powershell
.\scripts\start-server.ps1
```
在另一个窗口中验证 MCP 握手：
```powershell
.\scripts\test-local.ps1
```
本地端点是：
- MCP：`http://127.0.0.1:8812/mcp`
- 健康检查：`http://127.0.0.1:8812/health`
## 连接到 ChatGPT
ChatGPT 需要一个 HTTPS 可访问的远程 MCP 端点；它不会直接连接到 localhost URL。首选的私有网络选项是 OpenAI 安全 MCP 隧道。对于短期开发，包含的 ngrok 脚本创建一个临时的公共端点，并将本地持有者令牌注入上游。
参见 [docs/chatgpt-setup.md](docs/chatgpt-setup.md) 以获取完整的端到端设置，包括：
- OpenAI 安全 MCP 隧道
- ngrok 开发设置
- Cloudflare 隧道和托管部署注意事项
- ChatGPT 开发者模式配置
- 验证提示和故障排除
自定义 MCP 应用、开发者模式和写入操作的有效性取决于当前的 ChatGPT 计划和工作区策略。请使用设置指南中链接的当前 OpenAI 文档作为真实来源。
## 连接到其他 AI 客户端（Claude，Perplexity）
CodeWeave 还可以连接到其他模型上下文协议（MCP）客户端，例如 Claude Desktop 和 Perplexity。
参见 [docs/claude-perplexity-setup.md](docs/claude-perplexity-setup.md) 以获取详细的设置说明，包括：
- 使用 `mcp-remote` 的 Claude Desktop stdio-to-SSE 桥接设置
- Perplexity macOS/web 自定义连接器配置
## 配置
从 [`config.example.toml`](config.example.toml) 开始。
### 身份验证模式
```toml
[server]
host = "127.0.0.1"
port = 8812
auth_mode = "bearer" # bearer | none
token_env = "CODEWEAVE_MCP_TOKEN"
```
- `bearer` 是默认的，并且是包含的 ngrok 工作流程所必需的。
- `none` 仅在服务器绑定到环回主机时被接受。它适用于私有传输，例如 OpenAI 安全 MCP 隧道，其中 MCP 监听器仍然无法从网络访问。
### 允许列出的任务
`run_task` 只能执行配置的任务。命令是数组，并且永远不会通过 shell 传递。
```toml
[tasks.pytest]
command = [
"C:/path/to/your/project/.venv/Scripts/python.exe",
"-m",
"pytest",
"-q",
"{target}"
]
cwd = "."
timeout_seconds = 900
```
可选的 `{target}` 占位符被替换为有效的项目相对路径。绝对路径、父目录遍历、缺失目标、类似选项的目标和符号链接逃逸都被拒绝。
## 典型工具工作流程
用于调查和聚焦编辑：
1. 使用编码任务调用 `code_context`。
2. 使用 `code_fetch` 和返回的项目相对路径，当需要精确内容时。
3. 使用 `apply_patch` 和精确替换和 `code_fetch` 返回的文件哈希。
4. 使用 `run_task` 运行允许列出的验证任务。
对于广泛的更改，请使用 `prepare_patch`，查看其预览，然后使用返回的计划 ID 调用 `apply_prepared_patch`。
## 开发
```powershell
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
```
持续集成工作流程在支持的 Python 版本上运行测试和 Ruff。
## 文档
- [ChatGPT 连接指南](docs/chatgpt-setup.md)
- [Claude 和 Perplexity 连接指南](docs/claude-perplexity-setup.md)
- [架构](docs/architecture.md)
- [安全策略](SECURITY.md)
- [贡献](CONTRIBUTING.md)
- [变更日志](CHANGELOG.md)
## 项目状态
CodeWeave 是一个独立的开源项目，而不是 OpenAI 产品。在将其连接到 AI 客户端之前，请查看服务器、其配置的项目根目录和每个启用的写入/任务功能。
MCP 市场