Cursor Cloud Agent MCP

🚀 雲代理MCP服務器

雲代理MCP服務器用於 Cursor雲代理API，它允許AI助手創建和管理在GitHub倉庫上工作的雲代理。

🚀 快速開始

# 安裝
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安裝和從源代碼安裝。
• 支持多種客戶端連接，如Cursor、Claude Desktop和MCP Inspector。
• 提供豐富的工具和API，用於管理雲任務和獲取倉庫信息。

📦 安裝指南

從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	列出可用的大語言模型

任務生命週期工具

工具	描述
create_task	使用任務提示啟動雲任務
list_tasks	列出所有云任務
get_task	獲取特定任務的狀態
add_followup	向正在運行的任務發送額外指令
get_conversation	獲取完整的對話歷史記錄
delete_task	永久刪除任務

常見示例

創建任務

{
  "tool": "create_task",
  "arguments": {
    "prompt": "添加一個包含安裝說明的README.md文件",
    "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-.*"]
  }
}

多個過濾模式（或邏輯）：

{
  "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": "添加一個包含安裝說明的README.md文件",
    "repository": "https://github.com/your-org/your-repo"
  }
}

指定分支：

{
  "tool": "create_task",
  "arguments": {
    "prompt": "修復身份驗證漏洞",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  }
}

自動創建PR：

{
  "tool": "create_task",
  "arguments": {
    "prompt": "添加用戶身份驗證",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

自定義分支名稱：

{
  "tool": "create_task",
  "arguments": {
    "prompt": "實現新功能",
    "repository": "https://github.com/your-org/your-repo",
    "branch_name": "feature/new-feature"
  }
}

指定模型：

{
  "tool": "create_task",
  "arguments": {
    "prompt": "重構代碼庫",
    "repository": "https://github.com/your-org/your-repo",
    "model": "claude-4-sonnet-thinking"
  }
}

使用計劃文件：

{
  "tool": "create_task",
  "arguments": {
    "prompt": "實現計劃中描述的功能",
    "repository": "https://github.com/your-org/your-repo",
    "plan_file": "./plan.md"
  }
}

包含所有選項的完整示例：

{
  "tool": "create_task",
  "arguments": {
    "prompt": "添加全面的測試覆蓋",
    "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": "另外添加一個故障排除部分"
  }
}

get_conversation - 獲取對話歷史記錄

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

delete_task - 刪除任務

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

響應格式

所有工具返回符合 雲代理API 規範的結構化JSON響應。完整的API文檔請參閱 docs.md。

get_me 響應

{
  "apiKeyName": "生產API密鑰",
  "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": "添加README文檔",
  "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": "添加README文檔",
      "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": "添加了包含安裝說明和使用示例的README.md文件",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "bc_ghi789"
}

get_task 響應

{
  "id": "bc_abc123",
  "name": "添加README文檔",
  "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": "添加了包含安裝說明和使用示例的README.md文件",
  "createdAt": "2024-01-15T10:30:00Z"
}

狀態值： CREATING、RUNNING、FINISHED、FAILED、CANCELLED

get_conversation 響應

{
  "id": "bc_abc123",
  "messages": [
    {
      "id": "msg_001",
      "type": "user_message",
      "text": "添加一個包含安裝說明的README.md文件"
    },
    {
      "id": "msg_002",
      "type": "assistant_message",
      "text": "我將幫助你創建一個全面的README.md文件..."
    }
  ]
}

add_followup 響應

{
  "id": "bc_abc123"
}

delete_task 響應

{
  "id": "bc_abc123"
}

🔧 高級用法

規劃並行任務

使用 /plan-parallel-tasks 來將項目分解為多個並行任務：

/plan-parallel-tasks
project_description: "添加具有登錄、註冊和密碼重置功能的用戶身份驗證"

這將：

1. 調用 get_repos 檢測你的倉庫
2. 將項目分解為獨立的任務
3. 將任務分組到不同階段（並行 → 順序）
4. 為每個 create_task 調用提供確切的提示

並行化規則

可以並行運行：

• 修改完全不同文件的任務
• 創建新文件且不觸及共享文件的任務

不能並行運行：

• 修改同一文件的任務
• 一個任務依賴於另一個任務輸出的任務
• 都修改package.json、tsconfig.json等文件的任務

服務器版本

此包包含兩個服務器版本：

• 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

該包將在npm上以 cursor-cloud-agent-mcp 名稱提供。

📄 許可證

MIT