Freedcamp

Freedcamp MCP サーバー

これは、Freedcamp のタスク管理向けの Model Context Protocol（MCP）サーバー実装です。一括操作に対応し、Freedcamp プロジェクト内のタスクの作成、更新、一覧表示、削除を行うツールを提供します。

利用可能なトランスポート方式：

• STDIO トランスポート - IDE 統合（Claude Desktop、Cursor など）向けの従来の MCP トランスポート
• HTTP トランスポート - ウェブアプリケーションやクラウドへのデプロイ向けの、Server-Sent Events に対応した最新の REST API

機能

• タイトル、説明、優先度、期限、担当者を指定して、1 回の操作で複数のタスクを作成
• ステータスの変更など、既存のタスクを更新
• プロジェクト内のすべてのタスクを一覧表示
• タスクを完全に削除
• すべてのタスク管理操作で一括操作に対応
• 認証情報に環境変数を使用可能
• 包括的なエラー処理と検証

前提条件

• Node.js 17 以降
• TypeScript
• API アクセスが可能な Freedcamp アカウント
• Freedcamp の API キーとシークレット
• Freedcamp のプロジェクト ID

インストール（手動で実行する場合のみ。IDE やその他の MCP デスクトップクライアントで使用する場合は不要です）

1. リポジトリをクローンします：

git clone <repository-url>
cd freedcamp-mcp

2. 依存関係をインストールします：

npm install

3. ルートディレクトリに Freedcamp の認証情報を記述した .env ファイルを作成します：

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

直接実行：

# With environment variables
FREEDCAMP_API_KEY=your_key FREEDCAMP_API_SECRET=your_secret FREEDCAMP_PROJECT_ID=your_project npm run start:http

# Or using npx
npx freedcamp-mcp --http

HTTP サーバーはポート 3000（または PORT 環境変数で指定されたポート）で起動し、以下を提供します：

• MCP エンドポイント：http://localhost:3000/mcp
• ヘルスチェック：http://localhost:3000/health

HTTP トランスポートの機能：

• ステートレスな動作 — 各リクエストは独立しています
• 適切なエラー処理を備えた JSON レスポンス
• ウェブアプリケーション向けの CORS 対応
• ヘルスモニタリングを標準搭載
• ロードバランシングやクラスタリングに適しています

Docker でのデプロイ

本番環境へのデプロイでは、Docker を使用して HTTP トランスポートを実行できます：

Docker Compose を使用（推奨）

1. Freedcamp の認証情報を記述した .env ファイルを作成します：

FREEDCAMP_API_KEY=your_api_key
FREEDCAMP_API_SECRET=your_api_secret
FREEDCAMP_PROJECT_ID=your_project_id

2. サービスを起動します：

docker-compose up -d

Docker を直接使用

# Build the image
docker build -t freedcamp-mcp .

# Run the container
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. 1 件のタスクの作成、更新、削除
4. タスクの一括操作（作成、更新、削除）
5. タスクの一覧表示と検証
6. エラー処理とエッジケース

注： HTTP テストハーネスを実行するには、HTTP サーバーが起動している必要があります。テスト用の環境変数を読み込んでサーバーを起動するには、npm run start:http:test を使用してください。

利用可能なツール

1. freedcamp_add_task

   • Freedcamp に 1 つ以上の新しいタスクを作成します
   • 入力：タスクの詳細を含む tasks 配列を持つオブジェクト
   • タスクのパラメーター：
     • title（必須）：タスクのタイトル。明確で説明的なものにします
     • description（任意）：タスクの内容の詳細な説明
     • priority（任意）：タスクの優先度（0=低、1=標準、2=高、3=緊急）
     • due_date（任意）：Unix タイムスタンプ文字列による期限（例：2025-01-01 を示す '1735689600'）
     • assigned_to_id（任意）：タスクを割り当てるユーザー ID（有効な Freedcamp ユーザー ID である必要があります）

2. freedcamp_update_task

   • Freedcamp の既存のタスクを 1 つ以上更新します
   • 入力：タスクの更新内容を含む 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 から 1 つ以上のタスクを完全に削除します
   • 入力：削除するタスク ID を含む tasks 配列を持つオブジェクト
   • タスクのパラメーター：
     • 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
   # Or with environment variables:
   FREEDCAMP_API_KEY=your_key FREEDCAMP_API_SECRET=your_secret FREEDCAMP_PROJECT_ID=your_project npx freedcamp-mcp --http
   

2. HTTP トランスポートを使用するように Cursor を設定します。

   {
     "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. HTTP トランスポートを使用するように Claude Desktop を設定します。

   {
     "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. HTTP トランスポートを使用するように Roo を設定します。

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

API リファレンス

Freedcamp の API の詳細については、こちらをご覧ください：https://freedcamp.com/api-docs

ライセンス

MIT ライセンス。詳細は LICENSE ファイルをご覧ください。

貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。