Cursor Cloud Agent MCP

🚀 Cloud Agent MCP Server

Cursor Cloud Agents APIのMCPサーバーです。このサーバーを使用すると、AIアシスタントがGitHubリポジトリで動作するクラウドエージェントを作成および管理できます。 詳細はCursor Cloud Agents APIを参照してください。

🚀 クイックスタート

# インストール
npm install -g cursor-cloud-agent-mcp

# APIキーの設定
export CURSOR_API_KEY=your_api_key_here

# Cursorでの使用 (.cursor/mcp.jsonの作成)
{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

✨ 主な機能

• AIアシスタントがGitHubリポジトリ上でクラウドエージェントを作成・管理できます。
• さまざまなツールを提供し、タスクの作成、管理、リポジトリ情報の取得などが可能です。
• 並列タスクの計画機能を備えており、プロジェクトを効率的に分割できます。

📦 インストール

npmからのインストール

npm install -g cursor-cloud-agent-mcp

または、プロジェクト内にローカルインストールする場合は、以下のコマンドを実行します。

npm install cursor-cloud-agent-mcp

ソースからのインストール

開発用またはソースから実行する場合は、以下の手順を実行します。

# リポジトリのクローンと依存関係のインストール
git clone https://github.com/jxnl/cursor-cloud-agent-mcp
cd cloud-agent-mcp
npm install

# APIキーの設定
export CURSOR_API_KEY=your_api_key_here

# HTTPサーバーの起動
npm start
# サーバーは http://localhost:3000/mcp で起動します

# または、stdioサーバーの起動
npm run start:stdio

📚 ドキュメント

環境変数

変数	必須	説明
CURSOR_API_KEY	はい	cursor.com/settings から取得したAPIキー
PORT	いいえ	HTTPバージョンのサーバーポート (デフォルト: 3000)

クライアントの接続

Cursor

オプション1: npmパッケージの使用 (推奨) npmを通じてインストールした後、.cursor/mcp.jsonを作成します。

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

または、グローバルにインストールした場合は、以下のように設定します。

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "cursor-cloud-agent-mcp",
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

オプション2: ソースからの実行 (開発用) ソースから実行する場合は、.cursor/mcp.jsonを作成します。

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

オプション3: HTTPサーバー (代替案) HTTPバージョンを使用する場合は、以下のように設定します。

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "url": "http://localhost:3000/mcp",
      "headers": {}
    }
  }
}

その後、別のターミナルでnpm startを実行してHTTPサーバーを起動します。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.jsonに以下の内容を追加します。

{
  "mcpServers": {
    "cloud-agent": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector
# http://localhost:3000/mcp に接続します

💻 使用例

典型的なワークフロー

1. get_repos          → 現在のリポジトリのURLとブランチを取得
2. create_task       → プロンプトを指定してタスクを起動
3. get_task          → タスクのステータスを確認 (CREATING → RUNNING → FINISHED)
4. add_followup       → (オプション) 実行中に追加の指示を送信
5. get_conversation   → タスクの実行内容を確認

利用可能なツール

ディスカバリーツール

ツール	説明
get_repos	現在のgitリポジトリを検出 (リポジトリURL、ブランチ、未コミットの変更)。必要に応じて、アクセス可能なすべてのリポジトリをリストします。最初にこれを呼び出してください。 注意: include_all: trueを使用する場合、regex_patternsによるフィルターが必須です。すべてのリポジトリを取得するには、厳しいレート制限 (1/分、30/時間) が適用されます。
get_me	APIキーの情報を取得 (認証を検証)
get_models	利用可能なLLMモデルをリスト

タスクライフサイクルツール

ツール	説明
create_task	タスクのプロンプトを指定してクラウドタスクを起動
list_tasks	すべてのクラウドタスクをリスト
get_task	特定のタスクのステータスを取得
add_followup	実行中のタスクに追加の指示を送信
get_conversation	完全な会話履歴を取得
delete_task	タスクを永久に削除

一般的な使用例

タスクの作成

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add a README.md file with installation instructions",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

タスクのリスト

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED|RUNNING",
    "limit": 10
  }
}

リポジトリ情報の取得

{
  "tool": "get_repos"
}

🔧 技術詳細

ツールドキュメント

各ツールの詳細な使用方法は以下の通りです。

get_repos - リポジトリの取得

基本的な使用法 (現在のリポジトリのみ):

{
  "tool": "get_repos"
}

アクセス可能なすべてのリポジトリを取得 (フィルター必須): 重要: include_all: trueを使用する場合、結果をフィルターするためにregex_patternsを指定する必要があります。これにより、過度に多くのリポジトリが返されるのを防ぎます。 正規表現パターンでリポジトリをフィルター:

{
  "tool": "get_repos",
  "arguments": {
    "include_all": true,
    "regex_patterns": ["^my-.*"]
  }
}

複数のフィルターパターン (OR論理):

{
  "tool": "get_repos",
  "arguments": {
    "include_all": true,
    "regex_patterns": [".*api.*", ".*backend.*", ".*frontend.*"]
  }
}

作業ディレクトリを指定:

{
  "tool": "get_repos",
  "arguments": {
    "working_directory": "/path/to/project"
  }
}

フィルターの例:

• ["^my-.*"] - "my-"で始まるリポジトリ
• [".*api.*"] - "api"を含むリポジトリ
• ["github.com/myorg"] - 特定の組織のリポジトリ
• [".*backend.*", ".*server.*"] - いずれかのパターンに一致するリポジトリ

get_me - 認証の検証

{
  "tool": "get_me"
}

get_models - 利用可能なモデルのリスト

{
  "tool": "get_models"
}

create_task - クラウドタスクの起動

基本的な使用法:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add a README.md file with installation instructions",
    "repository": "https://github.com/your-org/your-repo"
  }
}

ブランチを指定する場合:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Fix authentication bug",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  }
}

自動でPRを作成する場合:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add user authentication",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

カスタムブランチ名を指定する場合:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Implement new feature",
    "repository": "https://github.com/your-org/your-repo",
    "branch_name": "feature/new-feature"
  }
}

モデルを指定する場合:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Refactor codebase",
    "repository": "https://github.com/your-org/your-repo",
    "model": "claude-4-sonnet-thinking"
  }
}

計画ファイルを使用する場合:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Implement the features described in the plan",
    "repository": "https://github.com/your-org/your-repo",
    "plan_file": "./plan.md"
  }
}

すべてのオプションを指定した完全な例:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add comprehensive test coverage",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "develop",
    "branch_name": "feature/add-tests",
    "auto_pr": true,
    "model": "o3",
    "plan_file": "./test-plan.md"
  }
}

list_tasks - すべてのタスクのリスト

基本的なリスト表示:

{
  "tool": "list_tasks"
}

結果を制限する場合:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 10
  }
}

カーソルを使用したページネーション:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 20,
    "cursor": "bc_ghi789"
  }
}

ステータスでフィルターする場合:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED|RUNNING"
  }
}

リポジトリでフィルターする場合:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": ".*my-repo.*"
  }
}

ブランチ名でフィルターする場合:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "feature/.*"
  }
}

要約内容でフィルターする場合:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": ".*README.*"
  }
}

フィルターを組み合わせる場合:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED.*my-repo"
  }
}

フィルターの例:

• "FINISHED" - 完了したタスクのみ
• "RUNNING|CREATING" - アクティブなタスク
• ".*api.*" - APIリポジトリで動作するタスク
• "feature/.*" - フィーチャーブランチ上のタスク
• "FINISHED.*README" - 要約にREADMEが含まれる完了したタスク
• "FAILED|CANCELLED" - 失敗またはキャンセルされたタスク

get_task - タスクのステータスを取得

{
  "tool": "get_task",
  "arguments": {
    "id": "bc_abc123"
  }
}

add_followup - フォローアップ指示の送信

{
  "tool": "add_followup",
  "arguments": {
    "id": "bc_abc123",
    "prompt": "Also add a troubleshooting section"
  }
}

get_conversation - 会話履歴の取得

{
  "tool": "get_conversation",
  "arguments": {
    "id": "bc_abc123"
  }
}

delete_task - タスクの削除

{
  "tool": "delete_task",
  "arguments": {
    "id": "bc_abc123"
  }
}

レスポンスの形式

すべてのツールは、Cloud Agents APIの仕様に準拠した構造化されたJSONレスポンスを返します。完全なAPIドキュメントはdocs.mdを参照してください。

get_me レスポンス

{
  "apiKeyName": "Production API Key",
  "createdAt": "2024-01-15T10:30:00Z",
  "userEmail": "developer@example.com"
}

get_models レスポンス

{
  "models": [
    "claude-4-sonnet-thinking",
    "o3",
    "claude-4-opus-thinking"
  ]
}

get_repos レスポンス

{
  "current": {
    "repository": "https://github.com/your-org/your-repo",
    "branch": "main",
    "has_uncommitted_changes": false
  },
  "available": [
    {
      "owner": "your-org",
      "name": "your-repo",
      "repository": "https://github.com/your-org/your-repo"
    }
  ],
  "total_count": 1
}

create_task レスポンス

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "feature/add-readme",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "autoCreatePr": true,
    "openAsCursorGithubApp": false,
    "skipReviewerRequest": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

list_tasks レスポンス

{
  "tasks": [
    {
      "id": "bc_abc123",
      "name": "Add README Documentation",
      "status": "FINISHED",
      "source": {
        "repository": "https://github.com/your-org/your-repo",
        "ref": "main"
      },
      "target": {
        "branchName": "cursor/add-readme-1234",
        "url": "https://cursor.com/agents?id=bc_abc123",
        "prUrl": "https://github.com/your-org/your-repo/pull/1234",
        "autoCreatePr": false,
        "openAsCursorGithubApp": false,
        "skipReviewerRequest": false
      },
      "summary": "Added README.md with installation instructions and usage examples",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "bc_ghi789"
}

get_task レスポンス

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "FINISHED",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "cursor/add-readme-1234",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234",
    "autoCreatePr": false,
    "openAsCursorGithubApp": false,
    "skipReviewerRequest": false
  },
  "summary": "Added README.md with installation instructions and usage examples",
  "createdAt": "2024-01-15T10:30:00Z"
}

ステータス値: CREATING, RUNNING, FINISHED, FAILED, CANCELLED

get_conversation レスポンス

{
  "id": "bc_abc123",
  "messages": [
    {
      "id": "msg_001",
      "type": "user_message",
      "text": "Add a README.md file with installation instructions"
    },
    {
      "id": "msg_002",
      "type": "assistant_message",
      "text": "I'll help you create a comprehensive README.md file..."
    }
  ]
}

add_followup レスポンス

{
  "id": "bc_abc123"
}

delete_task レスポンス

{
  "id": "bc_abc123"
}

高度な機能

並列タスクの計画

/plan-parallel-tasksを使用して、プロジェクトを複数の並列タスクに分割できます。

/plan-parallel-tasks
project_description: "Add user authentication with login, signup, and password reset"

これにより、以下の処理が行われます。

1. get_reposを呼び出してリポジトリを検出します。
2. プロジェクトを独立したタスクに分割します。
3. タスクをフェーズにグループ化します (並列 → 直列)。
4. 各create_task呼び出しに必要な正確なプロンプトを提供します。

並列化のルール

並列実行可能なタスク:

• 完全に異なるファイルを変更するタスク
• 共有ファイルに触れずに新しいファイルを作成するタスク

並列実行不可能なタスク:

• 同じファイルを変更するタスク
• 一方のタスクが他方の出力に依存するタスク
• 両方がpackage.json、tsconfig.jsonなどを変更するタスク

サーバーバージョン

このパッケージには、2つのサーバーバージョンが含まれています。

• HTTPサーバー (src/server.ts): ポート3000でExpress HTTPサーバーを実行します。リモート接続またはHTTPエンドポイントが必要な場合に使用します。
• Stdioサーバー (src/server-stdio.ts): 標準入出力を使用します。ローカル統合に推奨されます。プロセスベースの起動に適しています。

以下のコマンドで実行できます。

• HTTP: npm start (デフォルト)
• Stdio: npm run start:stdio

開発に関する情報

ヘルスチェック

サーバーはヘルスチェックエンドポイントを公開しています。

curl http://localhost:3000/health

これにより、以下のようなレスポンスが返されます。

{"status":"ok","service":"cursor-cloud-agent-mcp","version":"1.0.2"}

npmへの公開

このパッケージをnpmに公開するには、以下の手順を実行します。

# ログインしていることを確認
npm login

# 公開
npm publish

パッケージはcursor-cloud-agent-mcpとしてnpmで利用可能になります。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。