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 文件。

貢獻

歡迎貢獻代碼！請隨時提交拉取請求。