Freedmcpcamp

🚀 Freedcamp MCP 服务器

这是一个用于 Freedcamp 任务管理的模型上下文协议（MCP）服务器实现。它提供了在 Freedcamp 项目中创建、更新、列出和删除任务的工具，并且支持批量操作。

🚀 快速开始

本项目提供了一个用于 Freedcamp 任务管理的 MCP 服务器，你可以按照以下步骤进行操作：

1. 确保满足前置要求，如安装 Node.js 17 或更高版本、TypeScript，拥有 Freedcamp 账户及 API 访问权限等。
2. 进行安装，包括克隆仓库、安装依赖和配置环境变量。
3. 运行服务器，可选择 STDIO 传输或 HTTP 传输方式。
4. 你可以根据需要进行测试、使用提供的工具进行任务管理，还能将其集成到 IDE 中。

✨ 主要特性

• 可在一次操作中创建多个任务，支持设置标题、描述、优先级、截止日期和负责人。
• 能够更新现有任务，包括更改任务状态。
• 可以列出项目中的所有任务。
• 可永久删除任务。
• 所有任务管理操作均支持批量处理。
• 支持使用环境变量配置凭证。
• 具备全面的错误处理和验证机制。

📦 安装指南

手动调用安装（使用 IDE 或其他 MCP 桌面客户端时无需此步骤）

1. 克隆仓库：

git clone <repository-url>
cd freedcamp-mcp

2. 安装依赖：

npm install

3. 在根目录下创建一个 .env 文件，并配置你的 Freedcamp 凭证：

FREEDCAMP_API_KEY=your_api_key
FREEDCAMP_API_SECRET=your_api_secret
FREEDCAMP_PROJECT_ID=your_project_id

💻 使用示例

基础用法

运行服务器

首先构建 TypeScript 代码：

npm run build

STDIO 传输（默认）

这是 IDE 和 MCP 客户端常用的传统传输方式：

npm start

HTTP 传输

适用于容器化部署和基于 HTTP 的集成：

开发环境（使用 .env 文件）：

npm run start:http:test

生产环境（使用环境变量）：

npm run start:http

直接执行：

# 使用环境变量
FREEDCAMP_API_KEY=your_key FREEDCAMP_API_SECRET=your_secret FREEDCAMP_PROJECT_ID=your_project npm run start:http

# 或者使用 npx
npx freedcamp-mcp --http

HTTP 服务器将在端口 3000 启动（或使用 PORT 环境变量指定的端口），并提供以下接口：

• MCP 端点：http://localhost:3000/mcp
• 健康检查：http://localhost:3000/health

高级用法

Docker 部署

对于生产环境部署，你可以使用 Docker 运行 HTTP 传输服务：

使用 Docker Compose（推荐）

1. 创建一个 .env 文件，并配置你的 Freedcamp 凭证：

FREEDCAMP_API_KEY=your_api_key
FREEDCAMP_API_SECRET=your_api_secret
FREEDCAMP_PROJECT_ID=your_project_id

2. 启动服务：

docker-compose up -d

直接使用 Docker

# 构建镜像
docker build -t freedcamp-mcp .

# 运行容器
docker run -d \
  --name freedcamp-mcp \
  -p 3000:3000 \
  -e FREEDCAMP_API_KEY=your_api_key \
  -e FREEDCAMP_API_SECRET=your_api_secret \
  -e FREEDCAMP_PROJECT_ID=your_project_id \
  freedcamp-mcp

容器化服务器通过 HTTP 传输提供相同的 MCP 功能，适用于：

• 云部署
• Kubernetes 环境
• 负载均衡设置
• 与基于 HTTP 的 MCP 客户端集成

运行测试套件

项目包含全面的测试套件，可验证两种传输方式的所有 MCP 功能：

STDIO 传输测试：

npm test

HTTP 传输测试：

npm run test:http

两个测试套件都会执行以下检查：

1. 使用正确的协议版本初始化服务器。
2. 列出工具并验证功能。
3. 单个任务的创建、更新和删除。
4. 批量任务操作（创建、更新、删除）。
5. 任务列表和验证。
6. 错误处理和边界情况。

注意：HTTP 测试套件需要 HTTP 服务器正在运行。使用 npm run start:http:test 启动服务器并加载测试环境变量。

可用工具

1. freedcamp_add_task

   • 在 Freedcamp 中创建一个或多个新任务。
   • 输入：包含 tasks 数组的对象，数组中包含任务详细信息。
   • 任务参数：
     • title（必填）：任务标题，应清晰且具有描述性。
     • description（可选）：任务详细描述。
     • priority（可选）：任务优先级（0=低，1=正常，2=高，3=紧急）。
     • due_date（可选）：截止日期，以 Unix 时间戳字符串表示（例如，'1735689600' 表示 2025-01-01）。
     • assigned_to_id（可选）：分配任务的用户 ID（必须是有效的 Freedcamp 用户 ID）。

2. freedcamp_update_task

   • 更新 Freedcamp 中的一个或多个现有任务。
   • 输入：包含 tasks 数组的对象，数组中包含任务更新信息。
   • 任务参数：
     • task_id（必填）：要更新的任务 ID（必须是有效的现有 Freedcamp 任务 ID）。
     • title（可选）：新的任务标题。
     • description（可选）：新的任务描述。
     • priority（可选）：新的任务优先级（0=低，1=正常，2=高，3=紧急）。
     • due_date（可选）：新的截止日期，以 Unix 时间戳字符串表示。
     • assigned_to_id（可选）：重新分配任务的用户 ID。
     • status（可选）：新的任务状态（0=打开，1=完成，2=关闭）。

3. freedcamp_list_tasks

   • 获取配置的 Freedcamp 项目中的所有任务。
   • 无需参数（使用环境变量中的项目 ID）。
   • 返回任务详细信息，包括 ID、标题、状态和其他元数据。

4. freedcamp_delete_task

   • 从 Freedcamp 中永久删除一个或多个任务。
   • 输入：包含 tasks 数组的对象，数组中包含要删除的任务 ID。
   • 任务参数：
     • task_id（必填）：要删除的任务 ID（警告：此操作不可撤销）。

示例用法

创建多个任务：

{
  "tasks": [
    {
      "title": "Setup project structure",
      "description": "Initialize the basic project folder structure",
      "priority": 2,
      "due_date": "1735689600"
    },
    {
      "title": "Implement authentication",
      "description": "Add user login and registration functionality",
      "priority": 3,
      "assigned_to_id": "12345"
    }
  ]
}

更新多个任务：

{
  "tasks": [
    {
      "task_id": "67890",
      "status": 1,
      "description": "Updated: Added OAuth integration"
    },
    {
      "task_id": "67891",
      "priority": 3,
      "due_date": "1735776000"
    }
  ]
}

删除多个任务：

{
  "tasks": [
    {
      "task_id": "67892"
    },
    {
      "task_id": "67893"
    }
  ]
}

IDE 集成

可以直接使用 npx 运行服务器，无需克隆仓库。根据需求选择 STDIO 传输（传统方式）或 HTTP 传输（现代方式）。

Cursor

选项 1：STDIO 传输（默认）

1. 在项目根目录下打开（或创建） .cursor/mcp.json 文件。
2. 添加你的 Freedcamp MCP 服务器配置：

{
  "mcpServers": {
    "freedcamp": {
      "command": "npx",
      "args": ["freedcamp-mcp"],
      "env": {
        "FREEDCAMP_API_KEY": "your_api_key",
        "FREEDCAMP_API_SECRET": "your_api_secret",
        "FREEDCAMP_PROJECT_ID": "your_project_id"
      }
    }
  }
}

3. 重启 Cursor 或重新加载 MCP 服务器。

选项 2：HTTP 传输

1. 首先，在单独的终端中启动 HTTP 服务器：

npx freedcamp-mcp --http
# 或者使用环境变量：
FREEDCAMP_API_KEY=your_key FREEDCAMP_API_SECRET=your_secret FREEDCAMP_PROJECT_ID=your_project npx freedcamp-mcp --http

2. 配置 Cursor 使用 HTTP 传输：

{
  "mcpServers": {
    "freedcamp": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

3. 重启 Cursor 或重新加载 MCP 服务器。

Claude Desktop

选项 1：STDIO 传输（默认）

1. 在 macOS 上打开（或创建） ~/Library/Application Support/Claude/claude_desktop_config.json 文件，在 Windows 上打开 %APPDATA%/Claude/claude_desktop_config.json 文件。
2. 添加你的 Freedcamp MCP 服务器配置：

{
  "mcpServers": {
    "freedcamp": {
      "command": "npx",
      "args": ["freedcamp-mcp"],
      "env": {
        "FREEDCAMP_API_KEY": "your_api_key",
        "FREEDCAMP_API_SECRET": "your_api_secret",
        "FREEDCAMP_PROJECT_ID": "your_project_id"
      }
    }
  }
}

3. 重启 Claude Desktop。

选项 2：HTTP 传输

1. 启动 HTTP 服务器：

npx freedcamp-mcp --http

2. 配置 Claude Desktop 使用 HTTP 传输：

{
  "mcpServers": {
    "freedcamp": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

3. 重启 Claude Desktop。

Roo

选项 1：STDIO 传输（默认）

1. 打开（或创建）你的 Roo MCP 配置文件（通常为 roo.mcp.json 或类似文件）。
2. 添加你的 Freedcamp MCP 服务器配置：

{
  "mcpServers": {
    "Freedcamp": {
      "transport": "stdio",
      "command": "npx",
      "args": ["freedcamp-mcp"],
      "env": {
        "FREEDCAMP_API_KEY": "your_api_key",
        "FREEDCAMP_API_SECRET": "your_api_secret",
        "FREEDCAMP_PROJECT_ID": "your_project_id"
      }
    }
  }
}

选项 2：HTTP 传输

1. 启动 HTTP 服务器：

npx freedcamp-mcp --http

2. 配置 Roo 使用 HTTP 传输：

{
  "mcpServers": {
    "Freedcamp": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

📚 详细文档

有关 Freedcamp API 的详细信息，请访问：https://freedcamp.com/api-docs

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

贡献

欢迎贡献代码！请随时提交拉取请求。