内容
# TeamStorm MCP 服务器
TeamStorm MCP 服务器用于集成 AI 代理（Claude Code、Cursor）与 TeamStorm API。提供 **48 种工具** 用于处理任务、文件夹、文档、评论、属性、附件、权限、链接、用户、冲刺、workflow 和时间跟踪。
## 快速入门
### 1. 启动容器
```bash
docker compose up -d --build
```
进行完全干净的构建（无缓存）：
```bash
docker compose build --no-cache && docker compose up -d
```
服务器将在 `http://localhost:3001/mcp` 上可用，健康检查将在 `http://localhost:3002/health` 上进行。
> **网络访问（Linux 服务器）：** 如果 `TEAMSTORM_API_TOKEN` **未设置**，服务器将在所有接口 (`0.0.0.0`) 上监听，并可通过服务器的 IP 地址访问：`http://192.168.x.x:3001/mcp`。如果 `TEAMSTORM_API_TOKEN` **已设置**（单用户部署），服务器将自动切换到 `127.0.0.1` 以保护令牌。要在设置令牌时恢复网络访问，请在 `.env` 中设置 `LISTEN_HOST=0.0.0.0`。
> **注意：** `.env` 中的 `TEAMSTORM_API_TOKEN` 变量不是必需的 - 在 HTTP 模式下，每个客户端都通过 `Authorization` 头部发送自己的令牌。`TEAMSTORM_API_URL` 可以通过工具中的 `apiUrl` 传递（自动补充到 `http://<host>/cwm/public/api/v1`），但通常服务器已预先配置了 URL 参数。
> 📦 **部署。** 部署方案（本地单用户/多用户，远程服务器使用 HTTPS，裸 Node，多实例），更新顺序和诊断在单独的指南中 - [README-deploy.md](README-deploy.md)。重要：会话存储在内存中，因此每次重新构建后都需要重新连接客户端。
### 2. 与 Claude Code 集成
服务器已经启动（参见步骤 1）。将其添加到 Claude Code 中：
```bash
claude mcp add --scope user --transport http teamstorm http://localhost:3001/mcp \
-H "Authorization: PrivateToken 您的令牌"
```
> **注意：** `PrivateToken` 是您的个人 TeamStorm 令牌。它随每个请求发送，并在 API 端用于身份验证。
### 3. 与 Codex / Codex Desktop 集成
在 `~/.codex/config.toml` 中添加一个部分。根据 MCP 服务器的启动方式，有两种可能的情况。
**选项 A - 服务器上设置了令牌（推荐用于本地启动）**
如果 `.env` 中已设置 `TEAMSTORM_API_TOKEN`，服务器将把令牌插入到对 TeamStorm 的请求中。Codex 不应发送任何头部：
```toml
[mcp_servers.teamstorm]
url = "http://localhost:3001/mcp"
```
**选项 B - 客户端发送令牌（多用户部署）**
如果服务器上未设置令牌，每个客户端都发送自己的令牌。将令牌保存到环境变量中（在 `~/.zshrc` 或 `~/.bashrc` 中）：
```bash
export TEAMSTORM_TOKEN="您的令牌"
```
然后在配置文件中指定此变量的名称：
```toml
[mcp_servers.teamstorm]
url = "http://localhost:3001/mcp"
bearer_token_env_var = "TEAMSTORM_TOKEN"
```
> **注意：** Codex 将令牌作为 `Authorization: Bearer <令牌>` 发送，服务器接受这一点。重新启动 Codex 以应用配置更改。
### 4. 与 Cursor 集成
在项目根目录（或全局 `~/.cursor/mcp.json`）中创建 `.cursor/mcp.json` 文件：
```json
{
"mcpServers": {
"teamstorm": {
"url": "http://localhost:3001/mcp",
"headers": {
"Authorization": "PrivateToken 您的令牌"
}
}
}
}
```
> **注意：** 将 `您的令牌` 替换为实际的 TeamStorm 私有令牌。添加后重启 Cursor，MCP 工具将出现在侧边栏中。
### 5. 与 Claude Desktop 集成
自定义连接器（应用程序中的设置 → 连接器）**不适合** - 它们连接到 Anthropic 云服务器，而不是本地机器，因此看不到 `http://localhost`。对于本地 HTTP 服务器，需要 `mcp-remote` 代理，Claude Desktop 作为普通本地 MCP 服务器启动。
打开配置（通过 Claude → 设置… → 开发者 → 编辑配置，或直接编辑文件）：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"teamstorm": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://localhost:3001/mcp",
"--allow-http",
"--header",
"Authorization:${TEAMSTORM_AUTH_HEADER}"
],
"env": {
"TEAMSTORM_AUTH_HEADER": "PrivateToken 您的令牌"
}
}
}
}
```
> **注意：** `--allow-http` 是必需的 - `mcp-remote` 默认情况下需要 HTTPS。令牌通过 `env` 传递，以避免在 `--header` 参数值中的空格破坏解析。需要 Node.js（用于 `npx`）。完全重启 Claude Desktop（退出，而不是关闭窗口）- 聊天输入字段中将出现 MCP 工具图标。
### 6. 检查
添加完成后重启 IDE 并检查：
```
显示 TeamStorm 空间中的任务列表
```
## 配置
### 环境变量
| 变量 | 描述 | 是否必需 | 示例 |
| --- | --- | --- | --- |
| `TEAMSTORM_API_URL` | TeamStorm API 基本 URL | 否（服务器预配置；可通过工具中的 `apiUrl` 重定义） | `http://teamstorm.local/cwm/public/api/v1` |
| `TEAMSTORM_API_TOKEN` | 私有令牌身份验证 | 否（每个客户端通过 `Authorization` 头部发送） | `your_token_here` |
| `TEAMSTORM_WORKSPACE` | 默认工作空间（如果工具未指定） | 否 | `MYSPACE` |
| `PORT` | MCP 服务器端口 | 否（默认为 3001） | `3001` |
| `LISTEN_HOST` | 服务器监听地址。如果未设置：`127.0.0.1`（当设置 `TEAMSTORM_API_TOKEN` 时），否则 `0.0.0.0` | 否 | `0.0.0.0` |
| `TRUST_PROXY` | 信任 `X-Forwarded-For` 头部（仅限反向代理） | 否（默认为 `false`） | `false` |
> `TEAMSTORM_API_URL` 通过 `.env` 进行全局设置。如有必要，可以通过工具中的 `apiUrl` 参数重定义 - 服务器自动将 URL 补充为完整格式 `http://<host>/cwm/public/api/v1`。
### .env 文件
```bash
cp .env.example .env
```
## 使用
集成 IDE 后，您可以使用命令。
> **注意：** 所有工具均需要 `workspace` 参数。如果在 `.env` 中设置了 `TEAMSTORM_WORKSPACE` 环境变量，可以可选地传递 `workspace` - 它将自动应用。否则，请显式指定：`"在 TS 空间中"`。
**获取任务列表：**
```
显示 TS 空间中的任务列表
```
**按 ID 获取任务：**
```
在 TS 空间中找到任务 TS-13
```
**创建任务：**
```
在 TS 空间中创建任务 "修复 bug"，类型为 "缺陷"，执行人为 "ivan.ivanov"，文件夹为 "开发"
```
### 文件夹操作
```
显示 TS 空间的文件夹树
在 TS 空间中找到文件夹 "开发"
查找所有任务在文件夹 "Backend" 并显示重复项分析
```
### 评论操作
```
显示任务 TS-671 在 TS 空间中的评论
添加评论到任务 TS-671： "准备合并"
```
### 属性操作
```
显示任务 TS-671 在 TS 空间中的属性
TS 空间中有哪些属性？
```
### 附件操作
**上传文件：**
```bash
curl -X POST http://localhost:3001/upload \
-H "Authorization: PrivateToken 您的令牌" \
-F "file=@/path/to/file.pdf"
```
上传后获取 `uploadId`。然后附加文件：
```
将 ID 为 abc-123 的文件附加到 TS 空间中的任务 TS-100
```
### 时间跟踪
```
在 TS 空间中为任务 TS-671 添加 2 小时 30 分钟的时间记录
显示任务 TS-671 的时间记录
```
### 多实例操作
```
显示 TS 空间中任务 TS-100 的列表，URL 为 http://teamstorm-staging.local/cwm/public/api/v1
```
> **注意：** 传递 `apiUrl` 时，可以仅指定域名（`http://teamstorm-staging.local`）- 服务器会自动追加后缀 `/cwm/public/api/v1`。
## 文件上传安全性
`POST /upload` 端点（带外上传）：
- **身份验证** - 需要 `PrivateToken` 或 `Bearer` 在 `Authorization` 中
- **速率限制** - 10 请求/分钟/ IP 地址（考虑 `TRUST_PROXY`）
- **大小限制** - 最大 50 MB
- **TTL** - 文件在 1 小时后删除
- **权限** - 只有所有者（系统）有权访问文件
## 开发
```bash
npm install
npm run dev # 热重载
npm run build # tsc → dist/
npm run test:run # 测试
npm run lint # ESLint
```
## 架构
- **`src/index.ts`** - 入口点：HTTP 服务器（端口 3001）+ 健康检查（3002）+ 带外上传。每个 MCP 请求都会创建一个新的 `McpServer`。
- **`src/client/teamstorm.ts`** - `TeamStormClient`：具有 `setBaseUrl()` 的 axios 客户端，用于在运行时切换 URL（自动补充不完整的 URL 为 `/cwm/public/api/v1`）。
- **`src/tools/`** - 48 种按域划分的工具。每个工具：Zod 模式 + `apiUrl` + `execute` → 客户端 → Markdown。
- **`src/utils/`** - Pino 日志记录器（带有 redact 和延迟 NODE_ENV）+ 格式化程序（任务、字节、持续时间）。
## 项目结构
```
teamstorm-mcp-server/
├── src/
│ ├── client/
│ │ ├── teamstorm.ts # 统一的 axios 客户端：请求 TeamStorm REST API，
│ │ │ # 速率限制拦截器，日志中标头清理
│ │ └── types.ts # 所有 TeamStorm 实体的完整 TS 接口
│ ├── tools/
│ │ ├── folders/ # 文件夹工具
│ │ │ ├── list.ts, get.ts, get-tree.ts, find.ts
│ │ ├── tasks/ # 任务工具
│ │ │ ├── list.ts, get.ts, create.ts, update.ts, count.ts
│ │ │ ├── list-by-parent.ts, list-updated.ts
│ │ ├── comments/ # 评论工具
│ │ │ ├── list.ts, create.ts, visibility.ts
│ │ ├── attributes/ # 属性工具
│ │ │ ├── get.ts, list.ts
│ │ ├── attachments/ # 附件工具
│ │ │ ├── list.ts, get.ts, versions-list.ts, version-get.ts, oob-upload.ts
│ │ ├── permissions/ # 访问权限工具
│ │ │ └── get.ts
│ │ ├── links/ # 链接工具
│ │ │ └── get.ts
│ │ ├── documents/ # 文档工具
│ │ │ ├── list.ts, get.ts, create.ts, update.ts, block.ts, unblock.ts
│ │ ├── document-sharing/ # 文档共享
│ │ │ ├── list.ts, create.ts, update.ts
│ │ ├── document-statuses/ # 文档状态
│ │ │ ├── list.ts, get.ts
│ │ ├── document-links/ # 文档链接到任务
│ │ │ ├── list-tasks.ts, create.ts, list-documents.ts
│ │ ├── document-comments/ # 文档评论
│ │ │ ├── list.ts, create.ts
│ │ ├── users/ # 空间用户
│ │ │ └── list.ts
│ │ ├── sprints/ # 冲刺，状态过滤
│ │ │ └── list.ts
│ │ ├── workflows/ # 可用的流程
│ │ │ └── list.ts
│ │ ├── types/ # 任务类型
│ │ │ └── list.ts
│ │ ├── workspaces/ # 可用的空间
│ │ │ └── list.ts
│ │ └── time-tracking/ # 时间跟踪
│ │ ├── create.ts, list.ts
│ ├── utils/
│ │ ├── formatters.ts # Markdown 格式化程序：任务，字节，持续时间
│ │ └── logger.ts # Pino 日志记录器：redact 字段，延迟 NODE_ENV，开发环境下 pretty
│ ├── config.ts # Zod 验证 env，延迟单例（导入时不退出 process）
│ └── index.ts # 入口点：HTTP（3001）+ 健康检查（3002）+ 带外上传
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md
```
## 功能
工具按域分组：
### 文件夹
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_folders` | 文件夹列表，支持按名称和父文件夹过滤 |
| `teamstorm_get_folder` | 按 UUID 获取文件夹信息 |
| `teamstorm_get_folder_tree` | 请求获取完整的文件夹树（自动分页） |
| `teamstorm_find_folder` | 按名称（子字符串）或 ID 获取文件夹及其路径到根目录 |
| `teamstorm_create_folder` | 创建文件夹（名称，描述，父文件夹） |
| `teamstorm_update_folder` | 更新文件夹名称/描述，移动到另一个文件夹 |
### 任务
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_tasks` | 任务列表，支持过滤和分页 |
| `teamstorm_get_task` | 按 ID 获取完整任务信息 |
| `teamstorm_create_task` | 创建任务，指定类型、执行人、文件夹、冲刺 |
| `teamstorm_update_task` | 更新任务参数 |
| `teamstorm_get_task_count` | 获取空间中的任务总数 |
| `teamstorm_list_tasks_by_parent` | 获取父元素（文件夹或任务）的任务 |
| `teamstorm_list_updated_tasks` | 获取指定期间修改的任务 |
### 评论
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_task_comments` | 获取任务的所有评论 |
| `teamstorm_create_task_comment` | 添加评论到任务 |
| `teamstorm_get_comment_visibility` | 获取评论的访问级别（谁可以看到） |
### 属性
| 工具 | 描述 |
| --- | --- |
| `teamstorm_get_task_attributes` | 获取任务的属性值 |
| `teamstorm_list_attributes` | 获取空间的用户属性列表 |
| `teamstorm_create_attribute` | 创建属性（名称，类型，描述，UniSelect/Tag 选项） |
| `teamstorm_update_attribute` | 更新属性名称/描述和选项集 |
| `teamstorm_add_attribute_option` | 为 UniSelect/Tag 属性添加选项 |
| `teamstorm_update_attribute_option` | 按 UUID 重命名属性选项 |
### 附件
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_task_attachments` | 获取任务的附件列表 |
| `teamstorm_get_task_attachment` | 获取附件的具体元数据 |
| `teamstorm_list_attachment_versions` | 获取附件的所有版本 |
| `teamstorm_get_attachment_version` | 获取附件版本的具体元数据 |
| `teamstorm_attach_uploaded` | 将上传的文件附加到任务（POST /upload 之后） |
### 访问控制
| 工具 | 描述 |
| --- | --- |
| `teamstorm_get_task_permissions` | 获取任务的访问规则 |
### 链接
| 工具 | 描述 |
| --- | --- |
| `teamstorm_get_task_links` | 获取任务的链接（相关任务） |
### 文档
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_documents` | 获取空间的文档列表，支持分页 |
| `teamstorm_get_document` | 按 ID 获取文档，包括内容 |
| `teamstorm_create_document` | 创建文档（名称，内容，父元素，标签） |
| `teamstorm_update_document` | 更改文档状态（仅支持公共 API 的状态字段） |
| `teamstorm_block_document` | 阻止文档编辑 |
| `teamstorm_unblock_document` | 取消文档编辑限制 |
### 文档共享
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_document_sharing` | 获取文档共享列表 |
| `teamstorm_create_document_sharing` | 创建文档共享 |
| `teamstorm_update_document_sharing` | 更新文档共享 |
### 文档状态
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_document_statuses` | 获取文档状态列表 |
| `teamstorm_get_document_status` | 获取文档状态信息 |
### 文档链接
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_document_links` | 获取文档链接列表 |
| `teamstorm_create_document_links` | 创建文档链接 |
| `teamstorm_delete_document_links` | 删除文档链接 |
### 评论
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_document_comments` | 获取文档评论列表 |
| `teamstorm_create_document_comment` | 添加评论到文档 |
| `teamstorm_delete_document_comment` | 删除文档评论 |
### 用户
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_users` | 获取空间用户列表 |
### 冲刺
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_sprints` | 获取冲刺列表 |
### 工作流
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_workflows` | 获取可用工作流列表 |
### 类型
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_task_types` | 获取任务类型列表 |
### 工作空间
| 工具 | 描述 |
| --- | --- |
| `teamstorm_list_workspaces` | 获取可用工作空间列表 |
### 时间跟踪
| 工具 | 描述 |
| --- | --- |
| `teamstorm_create_time_tracking` | 创建时间跟踪 |
| `teamstorm_list_time_tracking` | 获取时间跟踪列表 |
### 文档访问权限
| 工具 | 描述 |
| -------------------------------------- | -------------------------------------------------------------- |
| `teamstorm_list_document_permissions` | 文档权限列表（用户和组） |
| `teamstorm_share_document` | 授予用户/组访问权限（阅读、编辑、评论） |
| `teamstorm_update_document_permission` | 修改现有权限的访问级别 |
### 文档状态
| 工具 | 描述 |
| ---------------------------------- | ------------------------------------------- |
| `teamstorm_list_document_statuses` | 可用的文档状态列表 |
| `teamstorm_get_document_status` | 通过ID获取文档状态 |
### 文档关联
| 工具 | 描述 |
| ----------------------------------- | ------------------------------------------------- |
| `teamstorm_get_document_task_links` | 与文档关联的任务 |
| `teamstorm_link_document_to_task` | 将文档与任务关联 |
| `teamstorm_get_task_document_links` | 与任务关联的文档 |
### 文档评论
| 工具 | 描述 |
| ----------------------------------- | ----------------------------------- |
| `teamstorm_list_document_comments` | 文档的所有评论 |
| `teamstorm_create_document_comment` | 添加文档评论 |
### 字典
| 工具 | 描述 |
| --------------------------- | ------------------------------------------------------- |
| `teamstorm_list_users` | 工作空间的用户列表（支持搜索） |
| `teamstorm_list_sprints` | 按状态筛选的冲刺列表（进行中/已完成/未来） |
| `teamstorm_list_workflows` | 可用的工作流程列表 |
| `teamstorm_list_task_types` | 任务类型列表 |
| `teamstorm_list_workspaces` | 所有可用的工作空间和页面列表 |
### 时间
| 工具 | 描述 |
| ----------------------------- | ------------------------------------------ |
| `teamstorm_create_time_entry` | 添加时间记录（工时） |
| `teamstorm_list_time_entries` | 任务的时间记录历史 |
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器