AI Project Hub MCP

项目上下文MCP服务器

一个本地HTTP服务器，提供MCP风格的工具来管理AI项目上下文。该服务器充当您的AI工作室的“操作系统”，允许LLM客户端从中心读取和写入项目上下文 ai-projects 存储库。

概述

该服务器公开了一个简单的HTTP JSON API，LLM客户端（如Codex、通过MCP连接器的ChatGPT Business等）可以使用该API：

• 发现项目 -列出所有可用项目
• 阅读上下文 -访问清单、项目文档、决策和代码仓库
• 撰写更新 -附加日志、决策和更新文件段

所有写入操作的作用域都是 ai-projects 仅存储库-代码存储库是只读的。

快速开始

先决条件

• Node.js 20+
• npm或pnpm

安装

npm install

配置

服务器需要一个同级目录 ../ai-projects （相对于此仓库）包含您的项目上下文。要覆盖，请执行以下操作：

export AI_PROJECTS_ROOT=/path/to/ai-projects
export PORT=4000  # optional, defaults to 4000
export HOST=127.0.0.1  # optional, defaults to 127.0.0.1

环境变量

服务器从以下位置加载环境变量 ../.env （父母 ai_access 目录）。这包括：

• MCP_WRITE_TOKEN -写操作需要（请参阅下面的安全）
• AI_PROJECTS_ROOT -覆盖默认项目目录
• PORT -服务器端口（默认值：4000）
• HOST -服务器主机（默认值：127.0.0.1）

跑步

开发模式 （自动重新加载）：

npm run dev

生产模式:

npm run build
npm start

服务器将于启动 http://127.0.0.1:4000

测试

运行所有测试：

npm test

在监视模式下运行测试：

npm run test:watch

跑步覆盖：

npm run test:coverage

运行E2E测试：

npm run test:e2e

API

端点： POST /tools

所有工具都通过一个接受JSON请求的端点访问：

{
  "tool": "tool_name",
  "params": { ... }
}

成功响应：

{
  "ok": true,
  "tool": "tool_name",
  "result": { ... }
}

错误响应：

{
  "ok": false,
  "tool": "tool_name",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

可用工具

只读工具

list_projects

列出所有可用项目。

请求：

{
  "tool": "list_projects",
  "params": {}
}

答复：

{
  "ok": true,
  "tool": "list_projects",
  "result": [
    {
      "id": "clubhub",
      "name": "ClubHub",
      "path": "/absolute/path/to/ai-projects/projects/clubhub"
    }
  ]
}

get_manifest

检索项目的manifest.yaml。

请求：

{
  "tool": "get_manifest",
  "params": {
    "project_id": "clubhub"
  }
}

答复：

{
  "ok": true,
  "tool": "get_manifest",
  "result": {
    "project": {
      "id": "clubhub",
      "name": "ClubHub",
      "status": "active"
    },
    "repository": {
      "path": "../clubhub/"
    },
    ...
  }
}

get_file

从项目目录中读取文件。

请求：

{
  "tool": "get_file",
  "params": {
    "project_id": "clubhub",
    "rel_path": "project.md"
  }
}

答复：

{
  "ok": true,
  "tool": "get_file",
  "result": {
    "path": "/absolute/path/to/file",
    "content": "File contents..."
  }
}

search_repo

在代码存储库中搜索查询字符串。

请求：

{
  "tool": "search_repo",
  "params": {
    "project_id": "clubhub",
    "query": "authentication",
    "max_results": 20
  }
}

答复：

{
  "ok": true,
  "tool": "search_repo",
  "result": [
    {
      "path": "/absolute/path/to/file.go",
      "relativePath": "internal/http/auth.go",
      "snippet": "func authenticate(...)",
      "score": 1
    }
  ]
}

写入工具

⚠️ 安全说明： 所有写入工具都需要通过身份验证 X-Api-Key 头球看 安全 下面的部分。

append_log

将带时间戳的日志条目附加到项目的log.md文件中。

请求：

{
  "tool": "append_log",
  "params": {
    "project_id": "clubhub",
    "role": "developer",
    "text": "Completed authentication implementation"
  }
}

所需标题：

X-Api-Key: 

append_decision

将ADR样式的决策附加到项目的decisions.md文件中。

请求：

{
  "tool": "append_decision",
  "params": {
    "project_id": "clubhub",
    "id": "DEC-2025-001",
    "title": "Use JWT for authentication",
    "context": "We need to secure API endpoints...",
    "decision": "We will use JWT tokens...",
    "consequences": "Simpler implementation, but requires token refresh logic..."
  }
}

update_file_segment

更新文件中的标记段。文件必须包含HTML样式的注释标记：

Old content here

请求：

{
  "tool": "update_file_segment",
  "params": {
    "project_id": "clubhub",
    "path": "project.md",
    "marker": "ARCH_SUMMARY",
    "new_text": "New content here"
  }
}

例子

使用curl

# List projects
curl -X POST http://127.0.0.1:4000/tools \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_projects", "params": {}}'

# Get manifest
curl -X POST http://127.0.0.1:4000/tools \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_manifest", "params": {"project_id": "clubhub"}}'

# Append log (requires X-Api-Key header)
curl -X POST http://127.0.0.1:4000/tools \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token-here" \
  -d '{
    "tool": "append_log",
    "params": {
      "project_id": "clubhub",
      "role": "developer",
      "text": "Fixed bug in payment processing"
    }
  }'

与ChatGPT业务MCP连接器集成

此服务器可以通过MCP连接器与ChatGPT Business集成。连接器将MCP协议消息转换为HTTP POST请求 /tools.

安全与安保

路径验证

• 所有文件路径都经过验证，以防止目录遍历攻击
• 写入操作仅限于 ai-projects 仅限目录
• 代码存储库是只读的（不写入 ../clubhub等等）
• 项目ID和路径在使用前会进行清理

写入身份验证

编写工具(append_log, append_decision, update_file_segment)受API密钥保护：

1. 集 MCP_WRITE_TOKEN 在 ../.env （父母 ai_access 目录）：

   MCP_WRITE_TOKEN=your-secret-token-here

1. 包含 X-Api-Key 头球 在所有写入请求中：

   curl -X POST http://127.0.0.1:4000/tools \
     -H "Content-Type: application/json" \
     -H "X-Api-Key: your-secret-token-here" \
     -d '{"tool": "append_log", "params": {...}}'

1. 如果 MCP_WRITE_TOKEN 未设置，允许写入，但会记录警告。这仅用于开发。

身份验证失败时的错误响应（403）：

{
  "ok": false,
  "tool": "append_log",
  "error": {
    "code": "UNAUTHORISED",
    "message": "Missing or invalid X-Api-Key for write tool"
  }
}

发展

看 BACKLOG.md 对于计划中的功能和 DESIGN.md 了解架构细节。

许可证

麻省理工学院