HAOps MCP服务器
模型上下文协议(MCP)服务器 HAOps(人工智能操作) -使Claude能够与HAOps项目管理系统进行交互。
特性
- 资源:访问项目、模块、功能和问题
- 工具:通过Claude创建、更新和管理HAOps实体
- API密钥验证:使用HAOps API密钥进行安全访问
设置
先决条件
- Node.js>=18.0.0
- HAOps实例正在运行(本地或远程)
- HAOps API密钥(通过管理员生成→ API密钥)
安装```bash
cd haops-mcp-server
npm install
### 配置
创建 `.env` 文件:```env
HAOPS_API_URL=http://localhost:3000
HAOPS_API_KEY=your-api-key-here
构建```bash
npm run build
### 发展```bash
npm run dev
用法
克劳德代码(CLI/VS代码扩展)
通过Claude CLI注册MCP服务器:```bash
claude mcp add-json --scope user haops '{
"type": "stdio",
"command": "node",
"args": ["/path/to/feature-tracker/haops-mcp-server/dist/index.js"],
"env": {
"HAOPS_API_URL": "http://localhost:3000",
"HAOPS_API_KEY": "your-api-key-here"
}
}'
验证: `claude mcp list` 应该显示 `haops: ... - ✓ Connected`
> **注:** 请勿手动编辑 `~/.claude/mcp-servers.json` --Claude Code无法读取该文件。总是使用 `claude mcp add-json`.
### 克劳德桌面(APP)
添加 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):```json
{
"mcpServers": {
"haops": {
"command": "node",
"args": ["/path/to/feature-tracker/haops-mcp-server/dist/index.js"],
"env": {
"HAOPS_API_URL": "http://localhost:3000",
"HAOPS_API_KEY": "your-api-key-here"
}
}
}
}
手动测试
手动运行服务器:```bash
npm start
服务器将在stdio上监听MCP协议消息。
## HTTP模式(共享守护进程)
除了默认的stdio传输外,服务器还可以长期运行
HTTP守护进程。一个守护进程可以为多个并发的Claude客户端提供服务
(CLI、VS Code扩展、桌面应用程序)。因为每个会话共享相同的内容
HAOps API客户端单例,与
每个Claude会话启动一个stdio子进程。
### 启动守护进程```bash
# Default port (3100)
HAOPS_API_URL=http://localhost:3000 HAOPS_API_KEY=your-key \
node dist/index.js --http
# Custom port
HAOPS_API_URL=http://localhost:3000 HAOPS_API_KEY=your-key \
node dist/index.js --http --port 3199
守护进程绑定 127.0.0.1 仅并验证 Host 每个标题
请求(DNS重新绑定保护)。它是 不 适合暴露
超越localhost——将其视为开发人员机器的便利。
开 SIGTERM / SIGINT 守护进程干净地关闭所有活动的MCP会话
退出0。
端点
| 方法 | 路径 | 目的 |
|---|---|---|
POST |
/mcp |
MCP JSON-RPC(初始化、工具/列表、工具/调用等) |
GET |
/mcp |
服务器发起的通知的SSE流(每个会话) |
DELETE |
/mcp |
显式会话结束 |
GET |
/health |
活体探针-- { status, uptime, version, connections, sessions } |
Claude Code客户端配置```bash
Add the HTTP transport to Claude Code
claude mcp add-json --scope user haops '{
"type": "http",
"url": "http://127.0.0.1:3100/mcp"
}'
Or for a non-default port
claude mcp add-json --scope user haops '{
"type": "http",
"url": "http://127.0.0.1:3199/mcp"
}'
当两者都没有时,Stdio模式仍然是默认模式 `--http` 也不 `--port` 是
通过,因此现有的基于stdio的配置保持不变。
### 卷曲烟雾测试```bash
# Health
curl http://127.0.0.1:3100/health
# Initialize a session (save the Mcp-Session-Id header from the response)
curl -i -X POST http://127.0.0.1:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}},"id":1}'
# List tools (reuse the session id from above)
curl -X POST http://127.0.0.1:3100/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: " \
-H "Mcp-Protocol-Version: 2025-03-26" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":2}'
何时使用哪种模式
| 场景 | 运输 |
|---|---|
| 单克劳德代码会话,默认设置 | stdio |
| 同一台机器上的多个Claude Code会话 | HTTP守护进程 |
| 克劳德桌面 | stdio |
| VS代码扩展(与CLI会话一起) | HTTP守护进程 |
建筑```
haops-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── api/
│ │ └── client.ts # HAOps API client (HTTP)
│ ├── resources/ # MCP resources (projects, modules, etc.)
│ └── tools/ # MCP tools (CRUD operations)
├── dist/ # Compiled JavaScript (generated)
└── package.json
## 资源
此服务器暴露的MCP资源(带查询过滤):
- `haops://projects` -列出所有项目
- `haops://projects/{slug}/modules?status=&priority=&ownerId=` -列出模块
- `haops://projects/{slug}/features?status=&priority=` -列出功能
- `haops://projects/{slug}/issues?status=&priority=&assignedTo=&type=` -列出问题
## 工具
该服务器提供的MCP工具(共103个)。下面列出的关键工具——请参阅 `src/index.ts` 完整列表:
### 读取操作
- `haops_list_projects()` -列出所有项目
- `haops_list_members(projectSlug)` -列出具有角色和统计信息的项目成员
### CRUD模块
- `haops_create_module(projectSlug, moduleData)` -创建新模块
- `haops_update_module(projectSlug, moduleId, moduleData)` -更新模块
- `haops_delete_module(projectSlug, moduleId, confirm?)` -删除模块(级联安全检查)
### 特征CRUD
- `haops_create_feature(projectSlug, featureData)` -创建新功能
- `haops_update_feature(projectSlug, featureId, featureData)` -更新功能
- `haops_delete_feature(projectSlug, featureId, confirm?)` -删除功能(级联安全检查)
### 发出CRUD
- `haops_create_issue(projectSlug, issueData)` -创建新问题
- `haops_update_issue(projectSlug, issueId, issueData)` -更新问题
- `haops_delete_issue(projectSlug, issueId)` -删除问题
- `haops_bulk_update_issues(projectSlug, issueIds, updates)` -批量更新问题
### 沟通
- `haops_create_discussion(projectSlug, title, ...)` -创建讨论话题
- `haops_post_message(projectSlug, discussionId, content)` -发布讨论
- `haops_send_dm(projectSlug, recipientUserId, content)` -发送直接消息
### 团队管理
- `haops_add_member(projectSlug, userId, role?)` -添加项目成员
- `haops_update_member_role(projectSlug, userId, role)` -更新成员角色
### 审计与活动
- `haops_get_activity(projectSlug, entityType, entityId)` -实体活动日志
- `haops_get_audit_log(page?, limit?, action?, entityType?)` -系统审核日志(管理员)
## 工具使用示例
### 1.创建模块```json
{
"projectSlug": "my-project",
"title": "Authentication Module",
"description": "User authentication and authorization",
"ownerId": "user-uuid-here",
"status": "in-progress",
"priority": "high",
"startDate": "2026-02-24",
"targetDate": "2026-03-15"
}
必填字段: projectSlug, title, ownerId
状态选项: backlog, in-progress, review, done, blocked, on-hold, cancelled
优先级选项: low, medium, high, critical
2.更新模块```json
{
"projectSlug": "my-project",
"moduleId": "module-uuid-here",
"status": "done",
"completedDate": "2026-03-10"
}
**必填字段**: `projectSlug`, `moduleId`
所有其他字段都是可选的,只包括您要更改的字段。
### 3.创建功能```json
{
"projectSlug": "my-project",
"moduleId": "module-uuid-here",
"title": "OAuth2 Integration",
"description": "Support Google and GitHub OAuth",
"acceptanceCriteria": "Users can sign in with Google or GitHub accounts",
"ownerId": "user-uuid-here",
"status": "backlog",
"priority": "medium"
}
必填字段: projectSlug, moduleId, title, ownerId
备注:功能具有 acceptanceCriteria 字段(可选)。
4.更新功能```json
{
"projectSlug": "my-project",
"featureId": "feature-uuid-here",
"status": "review",
"ownerId": "new-owner-uuid"
}
**必填字段**: `projectSlug`, `featureId`
### 5.创建问题```json
{
"projectSlug": "my-project",
"featureId": "feature-uuid-here",
"title": "Fix OAuth redirect URL bug",
"description": "Redirect URL is incorrect after GitHub login",
"acceptanceCriteria": "Redirect URL points to dashboard after login",
"type": "bug",
"status": "backlog",
"priority": "critical",
"targetDate": "2026-02-28",
"assignedTo": "user-uuid-here"
}
必填字段: projectSlug, featureId, title
类型选项: feature, bug, task, optimization, refactor, documentation, research
备注:问题用途 assignedTo 字段(非 ownerId 如模块/功能)。
6.更新问题```json
{
"projectSlug": "my-project",
"issueId": "issue-uuid-here",
"status": "done",
"type": "feature",
"completedDate": "2026-02-25"
}
**必填字段**: `projectSlug`, `issueId`
### 7.删除模块(带安全检查)```json
{
"projectSlug": "my-project",
"moduleId": "module-uuid-here"
}
没有 confirm: true,返回一个列出子功能/问题的警告。添加 "confirm": true 继续进行级联删除。
8.批量更新问题```json
{
"projectSlug": "my-project",
"issueIds": ["issue-1-uuid", "issue-2-uuid", "issue-3-uuid"],
"updates": {
"status": "done",
"priority": "high"
}
}
以原子方式更新所有指定的问题(使用带回滚的DB事务)。
### 9.创建讨论```json
{
"projectSlug": "my-project",
"title": "Architecture Review",
"type": "question",
"channelId": "channel-uuid-here",
"firstMessage": "Let's discuss the new auth flow."
}
支持基于渠道、实体链接(discussableType + discussableId)或两者皆有。
10.发送直接消息```json
{
"projectSlug": "my-project",
"recipientUserId": "user-uuid-here",
"content": "Hey, can you review my PR?"
}
## 测试
### 运行单元测试```bash
npm test # All tests
npm run test:unit # Unit tests only (src/)
单元测试 (共22个):
src/api/__tests__/client.test.ts-API客户端方法(6个测试)- 后端:
lib/utils/__tests__/apiKeys.test.ts-密钥生成/哈希(9次测试) - 后端:
lib/auth/__tests__/requireApiKey.test.ts-身份验证中间件(7次测试)
运行集成测试```bash
npm run test:integration # Integration tests (tests/integration/)
npm run test:all # All tests (unit + integration)
**集成测试** (13项骨骼测试):
- 看 `tests/integration/README.md` 有关设置说明
- 测试目前是带有注释的API调用的模板
- 运行E2E需要测试数据库和种子数据
## 发展
### 项目结构```
haops-mcp-server/
├── src/
│ ├── index.ts # Main MCP server (stdio transport)
│ ├── api/
│ │ ├── client.ts # HAOps API HTTP client
│ │ └── __tests__/ # API client unit tests
│ └── types/
│ └── entities.ts # TypeScript interfaces
├── tests/
│ └── integration/ # Integration tests (E2E)
├── dist/ # Compiled JavaScript (npm run build)
├── package.json
└── README.md
添加新工具
- 在中添加TypeScript类型
src/types/entities.ts(如果需要) - 在中添加API客户端方法
src/api/client.ts - 在中定义工具架构
src/index.ts(ListToolsRequestSchema处理程序)
- 包含所有参数+必填字段的inputSchema - 在CallToolRequestSchema处理程序中实现工具逻辑
- 使用正确的TypeScript类型提取args
- 构建请求有效负载(仅包括已定义的字段)
- 调用API客户端方法
- 返回格式化响应 - 在中编写单元测试
src/api/__tests__/ - 将使用示例添加到此README中
代码质量
- TypeScript:启用严格模式,需要正确打字
- 测试使用 TS-IS for ESM 模块
- 代码检查:ESLint与TypeScript插件
- 构建:
npm run build编译到dist/目录
故障排除
“需要HAOPS_API_KEY环境变量”
- 确保
.env文件存在于haops-mcp-server/目录 - 或者在Claude Desktop配置中设置环境变量
“无法连接到HAOps API”
- 检查
HAOPS_API_URL指向运行HAOps实例 - 验证HAOps服务器是否可访问(尝试
curl $HAOPS_API_URL/api/projects)
“API密钥身份验证失败”
- 在HAOps生成新的API密钥→ 管理员→ API密钥
- 复制完整密钥(仅显示一次)
- 确保密钥未过期
许可证
麻省理工学院