内容
# onboard-mcp
**您的开发环境，由 AI 助手修复。**
MCP（模型上下文协议）服务器，检查本地开发中静默中断的问题：错误的 Node 版本、Docker 未运行、缺少 git 配置、缺少 .env 密钥、端口占用。向 AI 助手询问“我的环境准备好了吗？”，并获得一份带有确切修复方法的通过/失败报告。
[](https://github.com/developerpankajdixit/onboard-mcp/actions/workflows/ci.yml)
[](LICENSE)
## 为什么
每个开发人员都因“在我的机器上运行正常”而损失了一个下午：应用程序因 Node 版本相差一个主版本而失败，或者端口被僵尸进程占用，或者 `.env.local` 缺少上一个冲刺中添加的密钥。在我的团队中，环境设置问题使每个新开发人员花费数天。
该服务器将调试转换为在 AI 聊天中提出的一个问题：
> **您：** 在我的项目上运行医生，它需要端口 3000 和 5432
>
> **助手：**
> ```
> [PASS] node-version: Node v20.11.0 满足项目要求（20）。
> [FAIL] docker: Docker 已安装但守护进程未运行。
> 修复方法：启动 Docker Desktop，或在 Linux 上运行“sudo systemctl start docker”。
> [PASS] git-config: Git 已安装，user.name / user.email 已配置。
> [FAIL] env-files: .env.local 缺少 1 个密钥，来自 .env.example：REDIS_URL。
> 修复方法：将缺少的密钥添加到 .env.local。向队友或您的机密管理器询问值。
> [PASS] ports: 所有必需的端口都是空闲的：3000，5432。
>
> 2 个失败，0 个警告。上述列出了修复方法。
> ```
## 工具
| 工具 | 检查内容 |
|------|----------------|
| `doctor` | 运行以下所有检查并返回一份报告 |
| `check_node_version` | 当前 Node 版本与 `.nvmrc` 或 `package.json` engines |
| `check_docker` | Docker CLI 已安装，守护进程正在运行 |
| `check_git_config` | git 已安装，`user.name` / `user.email` 已设置 |
| `check_env_files` | `.env` / `.env.local` 与 `.env.example` （仅比较密钥，绝不读取您的值到响应中） |
| `check_ports` | 项目所需的 TCP 端口是否空闲 |
## 要求
- **Node.js 18 或更新版本** — 每个客户端都需要，因为服务器通过 `npx onboard-mcp` 运行。 使用 `node --version` 检查；如果需要，请从 [nodejs.org](https://nodejs.org) 安装。
这是唯一的通用依赖项。`npx` 自动获取已发布的包 — 无需克隆或构建。 **Claude Code** 步骤下面还需要 `claude` CLI（`npm install -g @anthropic-ai/claude-code`）；其他客户端不需要。
## 快速开始
### Claude Code
需要 [Claude Code CLI](https://code.claude.com/docs)。如果您还没有安装，请先安装：
```bash
npm install -g @anthropic-ai/claude-code
```
然后注册服务器：
```bash
claude mcp add --scope user onboard -- npx -y onboard-mcp
```
（`--scope user` 使其在每个项目中都可用；省略它仅为当前项目注册。）使用 `claude mcp get onboard` 验证。
或者克隆并在本地构建：
```bash
git clone https://github.com/developerpankajdixit/onboard-mcp.git
cd onboard-mcp && npm install && npm run build
claude mcp add onboard -- node /absolute/path/to/onboard-mcp/dist/index.js
```
### VS Code（GitHub Copilot 代理模式）
在您的项目中将以下内容添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"onboard": {
"command": "npx",
"args": ["-y", "onboard-mcp"]
}
}
}
```
### Cursor
设置 → MCP → 添加新的全局 MCP 服务器，或添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"onboard": {
"command": "npx",
"args": ["-y", "onboard-mcp"]
}
}
}
```
### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"onboard": {
"command": "npx",
"args": ["-y", "onboard-mcp"]
}
}
}
```
然后询问： *"在 /path/to/my/project 上运行医生，它需要端口 3000 和 5432。"*
任何其他 MCP 兼容的客户端都以相同的方式工作：通过 stdio 指向 `npx -y onboard-mcp`。
## 设计笔记
- **修复，而不是仅仅失败。** 每个失败的检查都返回确切的修复命令，以便助手可以提供运行它。
- **机密永远不会离开您的机器。** 环境检查仅比较密钥名称。值永远不会包含在任何工具响应中。
- **纯检查函数。** 每个检查都是一个普通的异步函数，具有可注入的依赖项，无需模拟 MCP 层（23 个单元测试，Node 18/20/22 跨 Linux 和 macOS 的 CI）。
## 开发
```bash
npm install
npm test # vitest
npm run build # tsc
npm run dev # 从源代码运行服务器
```
## 路线图
- `fix_*` 对应工具，在确认后应用建议的修复
- 通过 `onboard.config.json` 在项目根目录中配置检查列表
- 数据库连接检查（Postgres，Redis）后面有一个标志
## 许可证
MIT。 由 [Pankaj Dixit](https://pankajdixit.com) 构建，基于一个内部 MCP 入职工具，该工具将新开发人员的设置时间从 2 周缩短到 30 分钟以下。
