内容
开发 MCP 系统
本地开发 AI 代理的系统。它提供 MCP 工具，用于仓库上下文、知识库和技能、启动质量门和可验证的任务执行。服务器通过 `stdio` 工作，不打开网络端口，不需要远程 MCP 服务器。
需要连接的是 MCP 兼容的客户端，而不是直接连接模型，客户端可以选择 Codex、Cursor、Claude Desktop 或 Claude Code、VS Code with MCP、Gemini CLI/Code Assist 等。同一本地配置可这些客户端使用。
## 包含内容
- 基于 Node.js 的本地 MCP 服务器；
- 知识库、项目上下文和可库；
- 混合搜索：SQLite FTS、稀和可选的本地 B3；
- 任务`begin_task`、``、`verify_task`_task`；
- 、安全检查和前端质量 Playwright/Chromium；
- 适用于团队的 Docker 镜像：无需个人 Vault、密码、令牌、项目和任务## 要求
对于 Docker
- Docker Desktop（Windows）或带有 Compose v2 的 Docker Engine（Linux- Docker 必须有权选的项目文件夹。
从源码运行还需要 Node.js 24 和 npm。在 Windows 上，可以使用 [服务器 README](ai-dev-mcp-server/README.md) 中描述的捆绑运行时 Codex。
## Windows 上的一键启动
克隆后，在克隆根目录打开 PowerShell 并执行：
```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps```
脚本将创建一个隔离的文件夹 `AI-Dev-Projects` 在用户主目录中，安装 Docker Desktop 和 Node.js 24 LTS（如果），准备并检查 Docker 镜像，然后将本地 MCP 服务器 `ai-dev` 添加到 Codex、Cursor、Gemini、VS Code 和 Claude Windows，它还在 `C:\ProgramData\AI-\run-mcp.ps1` 中安装了一个启动，以避免当克隆西里尔字母时的编码问题。项目、Vault、令牌或密码不会复制到此文件夹中。对于 Claude Desktop，还会在同一文件夹中凑的 `ClaudeMcpProxy.exe`。 Docker 启动前响应 MCP 初始化，因此 Claude 的启动超时短；然后所有交换都透明地传递到本地 Docker 容器中。第一次启动 **需要管理员权限**，前提是 Docker Desktop 或 Node尚未安装：`wing 和 Docker 可能需要权限提升。如果 Docker Desktop 已经安装，则普通的 PowerShell 就足够了。
对于其他仓库文件夹选择：
```powershell
powershell.exe -NoProfilePolicy Bypass -File .\bootstrap.ps1 `
- "D:\Projects" `
-Clients "codex,cursor,vscode路径仅存储在所选客户端的本地设置中。令牌、密码、该文件夹的内容或您的个人资料不会写入 Git。执行后所需的 AI 客户端。
## macOS 和 Linux 上的一键启动
克隆后，在仓库根目录执行：
```bash
sh ./bootstrap.sh
```
脚本不需要主机上的 Node.js：它使用临时的 `node:24` 容器来准备 Docker 上下文和 MCP 设置。默认创建为 `~/AI-Dev-Projects`。它作为 `/workspace` 挂载到 MCP 容器中。
为了防止 Claude Desktop 和其他客户端在 Docker 冷启动时超时，bootstrap 创建了一个服务容器 `ai-dev-system-runtime-$(id -u)`。它在没有网络、只读文件系统、无 Linux 功能和 `no-new-privileges` 的情况下运行；它只访问命名卷和选定的项目文件夹。MCP 进程本身通过快速的 `docker exec` 启动，而启动器立即完成协议初始化。容器在 Docker 重启后自动启动，感谢 `restart=unless-stopped`。
在 macOS 上，请先安装并启动 Docker Desktop。在 Linux 上，如果没有 Docker，可以执行 `sh ./bootstrap.sh --install-prerequisites`：脚本使用 `sudo` 并支持 `apt`、` 和 `pacman`。将用户添加到 `docker` 组后，需要退出并，然后重复命令。这是的唯一必要情况。
对于文件夹和部分客户端：
```bash
sh ./bootstrap.sh --project-path "$HOME/Dev" --clients ",cursor,vs```
重复运行相同的命令地更新可管理的运行时容器。命名卷、索引、和项目文件不会被删除。您可以使用以下命令检查运行时：
```bash
docker ps --filter "label=ai-dev.system.runtime=true"
```
## 快速开始：Docker 1. 获取镜像
在团队发布后，将/REPOSITORY`为 GitHub 所有名称：
```powershell pull ghcr.io/OWNER/REPOSITORY:latest
```
或者从仓库克隆中构建镜像：
```powershell
cd ai-dev-mcp-server
npm ci --ignore-scripts --no-audit --no-fnpm run docker:prepare
npm run docker:audit
docker:build
npm run docker:smoke -- --image ai-dev-system:local
```
### 2. 选择工作文件夹
创建一个或文件夹，其中只包含允许代理。例如，Windows 上的 `C:\\Dev`OS/Linux 上的 `$HOME/Dev`。此作为 `/workspace` 挂载到容器中。
不要指定个人 Vault、整个主目录、包含机密或备份的文件### 3本地启动
Windows```powershell
$env_DEV_IMAGE = "ai-dev-system:local"
$env:AI_DEV_PROJECT_PATH = "C:\\Dev"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\\docker\\run-mcp.ps1
```
macOS/Linux:
```bash
export AI_DEV_IMAGE="ai-dev-system:local"
export AI_PATH="$HOME/Dev"
sh ./docker/run-mcp.sh
```
进程将等待标准输入中的 MCP 消息。这是预期行为：使用 `Ctrl+C` 终止检查，然后将启动器连接到 MCP 客户端。
## 连接到 AI 代理
在所有情况下，请将 `C:\\ABSOLUTE\\PATH` 替换为此仓库克隆的绝对路径，并将 `C:\\Dev` 替换为您允许的项目文件夹。不要将这些值添加到 Git 中。
### Codex
在用户 `config.toml` 中添加：
```toml
[mcp_servers.ai-dev]
command = "powershell.exe"
args = ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\ABSOLUTE\\PATH\\docker\\run-mcp.ps1"]
env = { AI_DEV_IMAGE = "ai-dev-system:local", AI_DEV_PROJECT_PATH = "C:\\Dev" }
startup_timeout_sec = 120
tool_timeout_sec = 3600
```
在 macOS/Linux 上，使用 `command = "/bin/sh"`，并在 `args` 中传递到 `docker/run-mcp.sh` 的绝对路径。在 `env` 中，还要指定 bootstrap 创建的名称：`AI_DEV_RUNTIME_CONTAINER = "ai-dev-system-runtime-UID"`，其中 `UID` 由 `id -u` 返回。自动安装程序会自行执行此操作。重启 Codex 并检查 MCP 工具列表中是否已出现 `ai-dev` 服务器。
### Cursor、Claude Desktop、Claude Code 和 Gemini
这些客户端使用带有 `mcpServers` 属性的 JSON。将以下块添加到或合并到它们现有的配置中：
启动 `bootstrap.ps1 -Clients claude` 时，安装程序会更新 Claude 的两个本地文件：Claude Code 的 `%USERPROFILE%\\.claude.json` 和 Claude Desktop 的 `%APPDATA%\\Claude\\claude_desktop_config.json`。现有的服务器会被保留，修改后的文件会备份。对于 Microsoft Store 版本的 Claude，安装程序还会更新APPDATA%\\Packages\\Claude_*隔离应用配置文件。在 Windows 上，请勿用以下示例安装的 Claude 配置：它使用 `C:\ProgramAI-Dev-System\ClaudeMcpProxy.exe Docker-MCP 启动。在 macOS/Linux 上，bootstrap 类似地保存 `AI_DEV_RUNTIME_CONTAINER` 并连接快速启动器；无需 后手动编辑 Claude```json
{
"mcpServers": {
ai-dev": {
command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"C:\\ABSOLUTE\\PATH\\docker\\run.ps1"
],
"env": {
"_IMAGE": "ai-dev-system:local",
_DEV_PROJECT_PATH": "C:\\Dev"
}
}
}
}
```
[docker/mcp-config.example.json](docker/mcp-config) 中提供了无需访问项目的最小化模板。更改配置后，请完全重启客户端。在 和 Gemini CLI 中，可以通过它们自己的 MCP 管理命令，但命令和环境变量保持不变。
### VS Code
在特定仓库中创建 `.vscode/mcp.json`，或将相同的服务器添加到 VS Code 的用户 MCP 设置中：
```json
{
"servers": {
"ai-dev": {
"type": "stdio",
"command": "powershell.exe",
"args": [
"-",
"-",
"Bypass",
"-File",
"C:\\ABSOLUTE\\PATH\\docker\\run-mcp.ps1"
"env": {
"AI_DEV_IMAGE": "-system:local",
"AI_DEV_PROJECT_PATH": "C:\\Dev"
}
}
}
}
```
重新加载 VS Code 窗口。在容器挂载仓库的路径以 `/workspace` 开头；例如，对于 `begin_task`，使用 `/workspace/my-project`。
## 如何与代理一起工作
1. 在 MCP 客户端中打开所需仓库。
2. 为代理提供具体任务和 `/workspace` 内的路径。
3. 对于有意义的工作，代理启动 `begin_task研究形成的上下文，并使用不超过三个选定的技能。
4. 在更改代码后，代理通过 `checkpoint_task进度，运行 `verify_task`，并仅在证据时通过 `complete_task` 完成工作请求示例：
```text
使用 MCP 服务器 ai-dev。为 /workspace/my-project 启动任务：
添加 CSV ，使用测试覆盖更改并运行 verify_task。
```
## 本地数据和安全性
镜像仅包含已验证的公共种子：规则、提示、质量门、允许和运行时。不包括：
- 密码、令牌、`.env`、密钥和用户- 个人 Obsidian Vault、 `.codex`、`.ai-dev`、Git 历史记录和本地缓存；
- `02-knowledge/Projects`、`02-knowledge/Task Runs`、索引、日志、备份存档；
- 您的项目源码和上下文；
- BGE-M3 权重。
容器创建的数据存储在本地 Docker 卷 `ai-dev-system-data` 中。镜像更新不会覆盖此卷。默认情况下，容器在没有网络、非 root 用户、只读根文件系统、无 Linux 功能和 `no-new-privileges` 的情况下启动。
如果项目在验证期间确实需要互联网，请有意识地仅为此启动设置 `AI_DEV_DOCKER_NETWORK=bridge`。
## Docker Compose 和 BGE-M3
对于 Compose，请复制/compose.local.example.yaml` 到 `docker.local.yaml`，指定本地 `AI_PATH` 并启动```bash
docker compose -f docker/compose.yaml -f docker/compose.local.yaml run -T ai-dev-mcp
```
`compose.local.yaml` 和 `docker/.env` 被 Git 忽略，因为它们可能包含本地路径。
可以使用 BGE 构建变体以实现更精确的语义搜索：
docker build -- INSTALL_BGE_M3=1 ---system-context
```
不嵌入镜像中。通过 `AI_DEV_MODEL_PATH` 挂载您自己的本地启动器将只读方式连接它作为 `/models/bge-m3`。
## 团队发布
[docker-publish.ymlgithub/workflows/docker-publish.yml)检查隐私政策，重新构建 allowlist 上下文，运行 MCP 烟雾测试，并使用 SBOM 和 provenance 将 `linux/amd64` 和 `linux/arm64` 镜像发布Hub 容器注册首次推送后1. 打开 GitHub 上的软件包并为团队或公开选择 `private/internal` 可见性。
2. 确保同事有权读取 GitHub Packages。
3. 将 `ghcr.io/REPOSITORY:latest` 和此 README给同事。
每个同事通过_DEV_PROJECT_PATH他们自己的本地；镜像和不包含其他人的文件。
## 验证和诊断
在从 `-mcp-server` 发布之前执行：
```powershell
npm run check
npm run docker:prepare
npm run docker:audit
npm run docker:smoke -- --image ai-dev-system:local
```
对于整个集合的完整检查：
```powershell
..\\scripts\\run-acceptance.ps1
```
如果 Docker Desktop 在活动 VPN 或 下无法下载基本镜像，请在 Docker Desktop 中配置代理/DNS。不要在 Dockerfile、Git、或项目文件中传递代理密码。已经构建的本地镜像在没有互联网访问的情况下启动。
有关 ComposeOS/Linux、B3 和 GHCR[docker/READMEdocker/README.md和完整工具列表：[ai-dev-mcp-server/README.md](ai-dev-mcp-server/README.md)。
## 许可证
请参阅 [LICENSE]( 和 [THIRD_NOTICES.md](THIRD_PARTY_NOTICES.md)。
