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