内容
# Freedcamp 多项目 MCP 服务器（多项目分支）
[](./LICENSE)
[](https://nodejs.org/)
一个适用于 Freedcamp 的模型上下文协议（MCP）服务器，适用于所有项目。发现项目、任务列表和用户；创建、更新、列出和删除任务（批量和跨项目）；创建和编辑项目；以及在项目上评论 - 凭证可选地来源于 AWS SSM，因此在客户端配置中没有秘密。
> **来自 [gabeosx/freedmcpcamp](https://github.com/gabeosx/freedmcpcamp) 的分支。** 此分支添加的内容：
> - 删除单项目锁定 - `FREEDCAMP_PROJECT_ID` 现在是一个可选默认值，每个调用的 `project_id` 始终获胜。
> - 新的发现工具：`freedcamp_list_projects`、`freedcamp_list_task_groups`、`freedcamp_list_users`。
> - 项目写入工具：`freedcamp_add_project`、`freedcamp_update_project`（API 将名称/颜色/组视为每次编辑的必需字段，因此部分编辑会自动从实时项目中回填）。
> - 评论工具：`freedcamp_add_comment`、`freedcamp_update_comment`、`freedcamp_delete_comment`（在任务和其他项目上评论）。
> - 分页感知列表（无沉默的 200 项截断）。
> - 批量操作中的每个任务错误隔离（一个坏项目不会使整个批次失败）。
> - 一个 AWS SSM 凭证启动器（`dist/ssm-launch.js`）+ 一个一键 `scripts/setup.sh`。
> **未发布到 npm** - 从源代码安装（参见下文）。`npx freedcamp-mcp` 将获取上游包，但不包含这些更改。
**传输方式：** STDIO（默认；适用于 Claude Code、Cursor、Claude Desktop）和 HTTP（适用于网络/云）。
## 功能
- 跨所有 Freedcamp 项目发现和工作（不限于单个项目）
- 列出项目、任务列表（组）和项目用户以进行发现
- 在单个操作中创建多个任务，包含标题、描述、优先级、截止日期、分配者、目标项目和任务列表
- 更新现有任务，包括状态、任务列表移动和其他更改
- 列出特定项目的任务或跨所有可访问项目
- 永久删除任务
- 创建和更新项目（API 的必填编辑字段自动回填，因此部分编辑不会删除其他字段）
- 在任务（和其他 Freedcamp 项目）上添加、编辑和删除评论
- 支持所有任务、项目和评论操作的批量操作（包括跨项目）
- 分页感知列表（无沉默的 200 项截断）
- 通过 `FREEDCAMP_PROJECT_ID` 可选默认项目（每个调用的 `project_id` 始终获胜）
- 通过环境变量或 AWS SSM 参数存储进行身份验证
- 全面的错误处理和验证
## 先决条件
- Node.js 17 或更高版本
- 具有 API 访问权限的 Freedcamp 帐户 - API 密钥和密钥（Freedcamp → 头像 → 设置 → API）
- （可选）AWS CLI v2 + 配置文件，如果您需要 SSM 支持的凭证
## 安装
此分支从源代码安装（未发布到 npm）。
```bash
git clone https://github.com/justadityaraj/freedcamp-mcp.git
cd freedcamp-mcp
npm install
npm run build
```
**快速路径（Claude Code + AWS SSM）：** 如果您将凭证存储在 SSM 中，只需运行 `./scripts/setup.sh` - 它会构建、验证 AWS/SSM 访问权限，并将服务器注册到 Claude Code（幂等）。通过 `AWS_PROFILE`、`AWS_REGION`、`SSM_KEY_PARAM`、`SSM_SECRET_PARAM` 环境变量覆盖默认值。以下部分解释了其底层工作原理。
**通过 `.env` 进行身份验证**（适用于本地运行 / HTTP）：在存储库根目录中创建一个 `.env` 文件：
```bash
FREEDCAMP_API_KEY=您的_api_key
FREEDCAMP_API_SECRET=您的_api_secret
# 可选。如果设置，当调用省略 project_id 时用作默认项目。
# 每个调用的 project_id 始终覆盖此值。保持未设置以跨所有项目工作。
FREEDCAMP_PROJECT_ID=您的_project_id
```
## 用法
### 运行服务器
首先构建：
```bash
npm run build
```
#### STDIO 传输（默认）
IDE 和 MCP 客户端使用的传输方式：
```bash
npm start # node dist/server.js
# 或，使用 SSM 支持的凭证：
npm run start:ssm # node dist/ssm-launch.js
```
#### HTTP 传输
适用于容器化部署和基于 HTTP 的集成：
**开发（带有 .env 文件）：**
```bash
npm run start:http:test
```
**生产（带有环境变量）：**
```bash
npm run start:http
```
**直接执行：**
```bash
FREEDCAMP_API_KEY=您的密钥 FREEDCAMP_API_SECRET=您的密钥 node dist/http-server.js
```
HTTP 服务器在端口 3000（或 `PORT`）上启动，并提供：
- **MCP 端点：** `http://localhost:3000/mcp`
- **健康检查：** `http://localhost:3000/health`
> **⚠️ 安全 - HTTP 传输默认情况下没有身份验证。** 任何可以访问该端口的人都可以使用您的凭证驱动 Freedcamp 帐户。设置 `MCP_AUTH_TOKEN` 以要求在每个 `/mcp` 请求上使用 `Authorization: Bearer <token>` 头部，并且仅在受信任的网络（或具有身份验证的代理/隧道）上公开服务器。STDIO 传输不受影响 - 它没有网络表面。
>
> ```bash
> MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run start:http
> # 然后使用：Authorization: Bearer <该令牌>
> ```
**HTTP 传输功能：**
- 无状态操作 - 每个请求都是独立的
- 具有正确错误处理的 JSON 响应
- 通过 `MCP_AUTH_TOKEN` 进行可选的令牌身份验证（默认关闭；参见上面的警告）
- 内置健康监测（`/health` 报告版本和是否需要身份验证）
- 适用于负载均衡和集群
### Docker 部署
对于生产部署，您可以使用 Docker 运行 HTTP 传输：
#### 使用 Docker Compose（推荐）
1. 使用 Freedcamp 凭证（`FREEDCAMP_API_KEY`、`FREEDCAMP_API_SECRET`，可选的 `FREEDCAMP_PROJECT_ID`）创建 `.env` 文件。
2. 启动服务：
```bash
docker-compose up -d
```
#### 直接使用 Docker
```bash
# 构建镜像
docker build -t freedcamp-mcp .
# 运行容器
docker run -d \
--name freedcamp-mcp \
-p 3000:3000 \
-e FREEDCAMP_API_KEY=您的_api_key \
-e FREEDCAMP_API_SECRET=您的_api_secret \
-e MCP_AUTH_TOKEN=您的_long_random_token \
freedcamp-mcp
```
容器化服务器通过 HTTP 传输提供相同的 MCP 功能，适用于云、Kubernetes 和负载均衡设置。因为容器通常将端口发布到 localhost 之外，因此设置 `MCP_AUTH_TOKEN`（如上所示），以便 `/mcp` 需要 `Authorization: Bearer <token>`。
### 运行测试套件
```bash
npm test # STDIO：离线单元测试 +（如果凭证存在）一个实时集成场景
npm run test:http # HTTP 传输（需要 HTTP 服务器运行）
```
STDIO 测试套件运行离线 `resolveProjectId` 单元测试，无需凭证，并且当设置 `FREEDCAMP_API_KEY` / `FREEDCAMP_API_SECRET` 时，进行实时场景：列出项目 → 列出任务组 + 列出用户 → 添加 → 列出 → 更新 → 删除。如果凭证不存在，它会跳过实时部分（退出 0），因此它是 CI 安全的。
### 多项目工作流（发现，然后操作）
该服务器不限于单个项目。推荐的工作流程：
1. **`freedcamp_list_projects`** - 发现您可以访问的项目 ID。
2. **`freedcamp_list_task_groups`**（可选）- 查找项目中特定任务列表的 `list_id`。
3. **`freedcamp_list_users`**（可选）- 查找要用作 `assigned_to_id` 的 `user_id`。
4. **`freedcamp_add_task` / `freedcamp_update_task` / `freedcamp_list_tasks`** - 通过传递 `project_id` 对任何项目执行操作。
如果您设置了 `FREEDCAMP_PROJECT_ID`，它将成为默认项目，用于每次调用省略 `project_id` 时。每个调用的 `project_id` 始终优先于默认值。如果两者均未设置，需要项目的工具将返回一个明确的错误，指向 `freedcamp_list_projects`，而 `freedcamp_list_tasks` 将列出所有可访问项目中的任务。
## 通过 AWS SSM 进行身份验证（将机密存储在配置之外）
您可以在 AWS SSM 参数存储中存储 `FREEDCAMP_API_KEY` / `FREEDCAMP_API_SECRET`，然后让捆绑的启动器（`dist/ssm-launch.js`）在启动时获取它们。然后，配置仅引用参数**名称**，而非机密值。
**新机器上的最快路径：** 一旦 SSM 参数存在（下面的步骤 1），请从存储库根目录运行 `./scripts/setup.sh`。它会构建服务器，验证 AWS 配置文件 + SSM 访问权限，并将 `freedcamp` MCP 服务器注册到 Claude Code（幂等）。通过 `AWS_PROFILE`、`AWS_REGION`、`SSM_KEY_PARAM`、`SSM_SECRET_PARAM` 环境变量覆盖默认值。以下部分解释了其底层工作原理。
**1. 存储机密一次**（在您自己的终端中运行，以便它们永远不会接触到配置）：
```bash
aws ssm put-parameter --name "/freedcamp-mcp/api-key" \
--type SecureString --value "您的_API_KEY" --region ap-south-1 --profile 您的配置文件
aws ssm put-parameter --name "/freedcamp-mcp/api-secret" \
--type SecureString --value "您的_API_SECRET" --region ap-south-1 --profile 您的配置文件
```
**2. 将 MCP 客户端指向启动器**（`dist/ssm-launch.js`）。它读取参数，注入它们作为环境变量，然后在相同的标准输入通道上运行服务器：
```json
{
"mcpServers": {
"freedcamp": {
"command": "node",
"args": ["/绝对路径/到/freedcamp-mcp/dist/ssm-launch.js"],
"env": {
"AWS_PROFILE": "您的配置文件",
"AWS_REGION": "ap-south-1"
}
}
}
}
```
启动器环境变量（均为可选，默认值为默认值）：
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `FREEDCAMP_SSM_KEY_PARAM` | `/freedcamp-mcp/api-key` | 包含 API 密钥的 SSM 参数 |
| `FREEDCAMP_SSM_SECRET_PARAM` | `/freedcamp-mcp/api-secret` | 包含 API 机密的 SSM 参数 |
| `FREEDCAMP_SSM_PROJECT_PARAM` | （未设置） | 包含默认项目 ID 的 SSM 参数 |
| `AWS_PROFILE` | （CLI 默认值）| 要使用的 AWS 配置文件 |
| `AWS_REGION` | `ap-south-1` | AWS 区域 |
需要安装 AWS CLI v2 并配置一个具有 `ssm:GetParameter`（和 `kms:Decrypt`，用于 SecureString）的配置文件。诊断信息写入 stderr，因此它们永远不会破坏 MCP 协议。
> **Git Bash 注意（Windows）：** MSYS 将以斜杠开头的参数重写为 Windows 路径，这会破坏 SSM 参数名称。当您从 Git Bash 调用 `aws ssm get-parameter --name /freedcamp-mcp/...` 时，您会得到一个令人误解的 `ParameterNotFound`。在 `MSYS_NO_PATHCONV=1` 前加上前缀。这不会影响启动器（Node 的 `execFileSync` 跳过 shell）或 MCP 客户端。
### 可用工具
1. **`freedcamp_list_projects`**（发现）
- 列出您有权访问的所有 Freedcamp 项目（活动和存档）
- 无参数
- 返回：`project_id`、`project_name`、`f_active`（`true` = 活动，`false` = 存档），以及（当可用时）`project_description`、`role_name`、`group_id`
- 分页感知（返回所有项目，而不仅仅是前 200 个）
2. **`freedcamp_list_task_groups`**（发现）
- 列出项目的任务列表（组）
- 输入：`project_id`（可选 - 默认项目）
- 返回：`id`（这是您在任务上传递的 `list_id`）、`title`、`project_id`
3. **`freedcamp_list_users`**（发现）
- 列出项目中的用户
- 输入：`project_id`（可选 - 默认项目）
- 返回：`user_id`（这是您在任务上传递的 `assigned_to_id`）、`full_name`、`email`
4. **`freedcamp_add_task`**
- 在 Freedcamp 中创建一项或多项新任务（支持批量操作，包括跨项目）
- 输入：具有 `tasks` 数组的对象，包含任务详细信息
- 任务参数：
- `title`（必填）：任务标题 - 应该清晰和描述性
- `project_id`（可选）：要在其中创建任务的项目。默认为默认项目；此处的值将覆盖默认值。
- `description`（可选）：任务涉及的详细描述
- `list_id`（可选）：任务列表（组）ID，用于将任务放入其中。默认为项目的第一个任务列表。
- `priority`（可选）：任务优先级级别（0 = 无，1 = 低，2 = 中，3 = 高）
- `due_date`（可选）：截止日期，格式为 `YYYY-MM-DD` 字符串（例如，`2026-01-26`）。不是 Unix 时间戳 - API 拒绝时间戳作为截止日期。
- `assigned_to_id`（可选）：要分配给任务的用户 ID（必须是有效的 Freedcamp 用户 ID）
5. **`freedcamp_update_task`**
- 在 Freedcamp 中更新一项或多项现有任务
- 输入：具有 `tasks` 数组的对象，包含任务更新
- 任务参数：
- `task_id`（必填）：要更新的任务 ID（必须是有效的现有 Freedcamp 任务 ID）
- `title`（可选）：新任务标题
- `description`（可选）：新任务描述
- `list_id`（可选）：任务列表（组）ID，用于将任务移动到其中
- `priority`（可选）：新任务优先级（0 = 无，1 = 低，2 = 中，3 = 高）
- `due_date`（可选）：新截止日期，格式为 `YYYY-MM-DD` 字符串（例如，`2026-01-26`）。不是 Unix 时间戳。
- `assigned_to_id`（可选）：要重新分配任务给的用户 ID
- `status`（可选）：新任务状态（0 = 未开始，1 = 已完成，2 = 进行中）
6. **`freedcamp_list_tasks`**
- 从 Freedcamp 检索任务（分页感知）
- 输入：`project_id`（可选）。如果提供，则限定为该项目；否则使用默认项目。如果两者均未设置，则列出所有可访问项目中的任务。
- 返回任务详细信息，包括 ID、标题、状态和其他元数据
7. **`freedcamp_delete_task`**
- 永久删除 Freedcamp 中的一项或多项任务
- 输入：具有 `tasks` 数组的对象，包含要删除的任务 ID
- 任务参数：
- `task_id`（必填）：要删除的任务 ID（警告：此操作不可撤销）
8. **`freedcamp_add_project`**
- 创建一项或多项新项目（支持批量操作）
- 输入：具有 `projects` 数组的对象
- 项目参数：
- `project_name`（必填）：项目名称（最多 255 个字符）
- `project_description`（可选）
- `project_color`（可选）：十六进制颜色，不带 `#`，例如 `34ad22`（默认为 `34ad22`）
- `group_id` / `group_name`（可选）：将项目放在一个组（文件夹）中；如果未提供，则项目将无组创建
- `todo_view_type`（可选）：`default`（列表）或 `kanban`
- 返回新的 `project_id`
9. **`freedcamp_update_project`**
- 更新一项或多项现有项目：重命名、更改描述/颜色、移动到其他组、存档/取消存档（支持批量操作）
- 输入：具有 `projects` 数组的对象
- 项目参数：
- `project_id`（必填）
- `project_name`、`project_description`、`project_color`、`group_id` / `group_name`（可选）
- `f_active`（可选）：`true` = 取消存档，`false` = 存档
- Freedcamp API 在每次编辑时将名称 + 颜色 + 组视为必填。任何未提供的参数都将使用项目的当前值自动填充，因此部分编辑（例如仅重命名）不会删除其他参数。如果无法加载当前项目，则编辑将被拒绝，而不是冒着破坏性部分写入的风险。
10. **`freedcamp_add_comment`**
- 将一项或多项评论添加到项目 - 默认情况下为任务（支持批量操作）
- 输入：具有 `comments` 数组的对象
- 评论参数：
- `item_id`（必填）：要评论的项目（例如 `task_id`）
- `description`（必填）：评论文本（支持 HTML）
- `app_id`（可选）：项目的应用程序 ID，默认为 `2`（任务）。其他：3 = 文件/讨论，13 = Bug Tracker，14 = Wiki，19 = 日历
- 返回新的 `comment_id`
11. **`freedcamp_update_comment`**
- 编辑一项或多项现有评论（支持批量操作）
- 输入：具有 `comments` 数组的对象
- 评论参数：
- `comment_id`（必填）
- `description`（必填）：新的评论文本
12. **`freedcamp_delete_comment`**
- 永久删除一项或多项评论（支持批量操作）
- 输入：具有 `comments` 数组的对象
- 评论参数：
- `comment_id`（必填）：要删除的评论 ID（警告：此操作不可撤销）
### 示例用法
**创建多个任务（使用默认项目）：**
```json
{
"tasks": [
{
"title": "设置项目结构",
"description": "初始化基本项目文件夹结构",
"priority": 2,
"due_date": "2026-01-26"
},
{
"title": "实施身份验证",
"description": "添加用户登录和注册功能",
"priority": 3,
"assigned_to_id": "12345"
}
]
}
```
**跨多个项目创建任务：**
首先使用 `freedcamp_list_projects` 发现项目 ID，然后针对每个任务指定它们。一个批量调用可以一次写入不同的项目。出现故障的任务（例如未解析的项目）不会使整个批次失败。
```json
{
"tasks": [
{
"project_id": "111111",
"title": "起草 Q3 路线图",
"list_id": "555555",
"priority": 3
},
{
"project_id": "222222",
"title": "审查营销文案",
"assigned_to_id": "98765"
}
]
}
```
**列出特定项目的任务：**
```json
{
"project_id": "111111"
}
```
省略 `project_id`（并保持 `FREEDCAMP_PROJECT_ID` 未设置）以列出所有可访问项目中的任务。
**更新多个任务：**
```json
{
"tasks": [
{ "task_id": "67890", "status": 1, "description": "更新：已添加 OAuth 集成" },
{ "task_id": "67891", "priority": 3, "due_date": "2026-01-27" }
]
}
```
**删除多个任务：**
```json
{
"tasks": [
{ "task_id": "67892" },
{ "task_id": "67893" }
]
}
```
## IDE / 客户端集成
由于此分支从源代码安装，MCP 客户端指向 `dist/` 中的已编译文件（首先运行 `npm install && npm run build`）。通过 **AWS SSM**（推荐 - 指向 `dist/ssm-launch.js`）或 **环境变量**（指向 `dist/server.js`）提供凭证。
### 克劳德代码
最简单的方法是捆绑脚本（构建，验证 AWS/SSM，注册用户范围）：
```bash
./scripts/setup.sh
```
或手动注册：
```bash
# 选项 A - SSM 启动器（配置中没有机密）
claude mcp add freedcamp -s user -e AWS_PROFILE=您的配置文件 -e AWS_REGION=ap-south-1 \
-- node /绝对路径/到/freedcamp-mcp/dist/ssm-launch.js
# 选项 B - 环境变量中的凭证
claude mcp add freedcamp -s user \
-e FREEDCAMP_API_KEY=您的密钥 -e FREEDCAMP_API_SECRET=您的密钥 \
-- node /绝对路径/到/freedcamp-mcp/dist/server.js
```
### 光标/克劳德桌面（JSON 配置）
添加到 `.cursor/mcp.json`（光标）或 `claude_desktop_config.json`（克劳德桌面 - `~/Library/Application Support/Claude/` 在 macOS 上，`%APPDATA%/Claude/` 在 Windows 上）：
```json
{
"mcpServers": {
"freedcamp": {
"command": "node",
"args": ["/绝对路径/到/freedcamp-mcp/dist/ssm-launch.js"],
"env": {
"AWS_PROFILE": "您的配置文件",
"AWS_REGION": "ap-south-1"
}
}
}
}
```
对于基于环境的凭证而不是 SSM，请将 `args` 指向 `dist/server.js`，并在 `env` 中设置 `FREEDCAMP_API_KEY` / `FREEDCAMP_API_SECRET`（和可选的 `FREEDCAMP_PROJECT_ID` 默认值）。在编辑后重启/重新加载客户端。
### HTTP 传输
对于托管设置，运行 `npm run start:http`（或 `node dist/http-server.js`），并让客户端指向 `http://localhost:3000/mcp`。
## API 参考
有关 Freedcamp API 的详细信息，请访问：https://freedcamp.com/api-docs
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](./LICENSE) 文件。由 [gabeosx/freedmcpcamp](https://github.com/gabeosx/freedmcpcamp) 分叉。
<!-- 作者：[Aditya Raj Singh](https://adityarajsingh.com/) -->
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器