Freedmcpcamp

🚀 Freedcamp MCP Server

このプロジェクトは、Freedcampのタスク管理用のModel Context Protocol (MCP) サーバーの実装です。Freedcampプロジェクト内のタスクの作成、更新、一覧表示、削除をサポートし、一括操作も可能です。

✨ 主な機能

• タイトル、説明、優先度、期限、担当者を指定して、一度に複数のタスクを作成できます。
• 既存のタスクを更新し、ステータスの変更もサポートします。
• プロジェクト内のすべてのタスクを一覧表示できます。
• タスクを完全に削除できます。
• すべてのタスク管理操作に一括操作をサポートします。
• 資格情報に環境変数を使用できます。
• 包括的なエラー処理と検証機能があります。

📦 インストール

このインストール手順は手動での実行のみに必要で、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

基本的な使用法

これはIDEやMCPクライアントで使用される従来のトランスポート方法です。

npm start

高度な使用法

コンテナ化されたデプロイメントや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に1つ以上の新しいタスクを作成します。
   • 入力: 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内の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つ以上のタスクを完全に削除します。
   • 入力: 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の詳細情報については、こちらを参照してください。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細は LICENSE ファイルを参照してください。

貢献の方法

貢献は大歓迎です！プルリクエストを送信してください。