内容
# 自动文档 MCP 服务器
准备好生产的 TypeScript MCP 服务器，捕获开发信号并在 Notion 中持续构建用户/管理员文档。
本地桥使用 HTTP-SSE 传输：
- `GET /sse` 打开 MCP 会话流
- `POST /messages?sessionId=...` 发送该会话的 JSON-RPC 工具调用
- `GET /health`、`GET /info`、`GET /startup/preflight` 和 `GET /contracts/bifrost-discovery` 暴露运行时和合约检查
## 快速开始
要从克隆到首次生成的手动文档的完整冷启动路径，请使用 [QUICKSTART.md](QUICKSTART.md)。
1. 安装依赖：
```bash
npm ci
```
2. 运行检查：
```bash
npm run lint
npm run typecheck
npm test
npm run build
```
3. 在本地运行：
```bash
npm run dev
```
## 环境
- `NOTION_TOKEN` 用于 Notion API 访问
- `NOTION_PARENT_PAGE_ID` 用于实时集成测试
- `RUN_LIVE_NOTION_TESTS=true` 启用环境门控的实时测试
- `BIFROST_VIRTUAL_KEY` 用于提供者为 `bifrost` 时的 Bifrost 支持的 AI 调用
- `AUTO_DOC_BRIDGE_API_KEY` 用于 HTTP-SSE 桥访问；需要打开 `/sse`、`/runner/status` 和 `/runner/trigger`
- `AUTO_DOC_RUNNER_PROJECT_ID` 和 `AUTO_DOC_RUNNER_REPO_PATH` 启用连续运行器
- `AUTO_DOC_RUNNER_TARGETS` 在一个 JSON 有效负载中配置多个运行器目标
- `SELF_DOC_PROJECT_ID` 和 `SELF_DOC_REPO_PATH` 是单独的运行时配置值；它们不是运行器的源
- `STATE_ENCRYPTION_KEY` 必须是在生产环境、桥模式和运行器模式下唯一的、高熵值
- 项目状态默认为 `~/.auto-doc-mcp/state.json`，因此运行器重启在当前工作目录之外恢复相同的项目
- `AUTO_DOC_STATE_FILE` 是可选的，仅应在隔离的测试/预发布环境中设置；显式覆盖不会自动迁移旧状态
- `discover_project_from_notion` 可以在验证所有五个数据库和关系后，从现有的 Auto-Doc Notion 项目页面重建本地项目绑定
- `AUTO_DOC_DISCOVERY_RECOVERY_ENABLED=true` 加上 `AUTO_DOC_DISCOVERY_PROJECT_PAGE_ID` 或 `AUTO_DOC_DISCOVERY_PROJECT_HINTS` 启用在 `project_missing_from_state` 后的受保护运行器恢复；默认情况下禁用
- `AUTO_DOC_ARTIFACT_ROOT` 约束生成的 PDF、本地文档、帮助中心导出和截图
生成生产状态密钥：
```bash
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
```
## 运行时模式
容器默认：HTTP 桥模式。Docker 镜像启动 `node build/src/cli/index.js bridge`，公开 `/health`，并适用于网络、Bifrost 和隧道部署。在打开 MCP 或运行器会话之前，请设置 `AUTO_DOC_BRIDGE_API_KEY`；非环回绑定在没有配置的非占位符密钥的情况下关闭。
在本地使用 `npm run dev` 或 `node build/src/index.js` 使用 stdio MCP。在配置运行器目标后，使用 `AUTO_DOC_RUNTIME_MODE=runner node build/src/index.js` 或 `node build/src/cli/index.js runner` 使用连续模式。
## VS Code MCP 开发集成
此存储库在以下位置包含本地 MCP 工作区配置：
- `.mcp.json`
- `.vscode/mcp.json`
默认连接直接通过 stdio 运行此服务器：
```json
{
"command": "node",
"args": ["build/src/index.js"]
}
```
在开发运行 MCP 客户端之前：
1. 运行 `npm ci`。
2. 运行 `npm run build`。
3. 确保您的 `.env` 包含 `NOTION_TOKEN`、`NOTION_PARENT_PAGE_ID` 和 `STATE_ENCRYPTION_KEY`。
4. 重新启动 MCP 客户端/IDE 以重新加载服务器条目。
HTTP-SSE 桥模式仍然可用于网络或远程客户端。有关桥设置、Notion 设置、提供者配置和首次工具调用，请参阅 [QUICKSTART.md](QUICKSTART.md)。
## CI
GitHub Actions 在推送和拉取请求到 `main` 时运行类型检查、lint、测试、构建和 Docker 桥烟雾测试。
## 分支保护
在 `main` 上强制实施合并保护，以便在合并之前 CI 必须通过：
- 必需状态检查：`test-build`
- 合并前要求分支保持最新
- 要求至少有一个批准的拉取请求审查
使用包含的脚本应用这些设置：
1. 设置 GitHub 管理员令牌：
```bash
export GITHUB_ADMIN_TOKEN=<your-admin-token>
```
2. 运行：
```bash
./scripts/apply-branch-protection.ps1 -Owner bido75 -Repo Auto-Documentation-MCP-Server
```
3. 只读验证：
```bash
./scripts/apply-branch-protection.ps1 -Owner bido75 -Repo Auto-Documentation-MCP-Server -VerifyOnly
```
在 `docs/branch-protection.md` 中查看完整的策略详细信息。
## CD 版本
GitHub Actions 在您推送语义版本标签（`v*.*.*`）时发布版本。
发布工作流程：
- 运行 `typecheck`、`test` 和 `build`
- 验证标签提交位于 `main` 上
- 验证所需的 CI 检查 `test-build` 已经通过
- 从 `build/` 和运行时元数据文件打包发布工件
- 发布具有自动生成的说明的 GitHub 版本
创建并推送发布标签：
```bash
git tag v1.0.0
git push origin v1.0.0
```
您也可以使用标签输入手动从 GitHub Actions 运行发布工作流程。
## GitHub 推送设置（需要一次）
此存储库配置为通过 SSH 推送。
1. 确认远程 URL：
```bash
git remote -v
```
您应该看到 `git@github.com:bido75/Auto-Documentation-MCP-Server.git`。
2. 生成 SSH 密钥（如果需要）：
```bash
ssh-keygen -t ed25519 -C "bido75@users.noreply.github.com"
```
3. 复制您的公钥：
```bash
cat ~/.ssh/id_ed25519.pub
```
4. 在 GitHub 上添加密钥：
- GitHub 设置 -> SSH 和 GPG 密钥 -> 新的 SSH 密钥
5. 验证身份：
```bash
ssh -T git@github.com
```
6. 推送：
```bash
git push -u origin main
```
## 可选自动推送
此存储库在 `.githooks/post-commit` 中包含一个 `post-commit` git 钩子，该钩子尝试在 `main` 上提交后推送。
在本地启用它：
```bash
git config core.hooksPath .githooks
```
如果推送身份验证尚未配置，钩子将打印错误并重试一次。
