Cloud Agent MCP Server

云代理MCP服务器

MCP服务器 光标云代理API。让AI助手创建和管理在GitHub存储库上工作的云代理。

快速开始

# Install
npm install -g cursor-cloud-agent-mcp

# Set your API key
export CURSOR_API_KEY=your_api_key_here

# Use with Cursor (create .cursor/mcp.json)
{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

安装

从npm安装

npm install -g cursor-cloud-agent-mcp

或者在项目中本地安装：

npm install cursor-cloud-agent-mcp

从源代码安装

如果你正在开发或想从源代码运行：

# Clone and install dependencies
git clone https://github.com/jxnl/cursor-cloud-agent-mcp
cd cloud-agent-mcp
npm install

# Set your API key
export CURSOR_API_KEY=your_api_key_here

# Run HTTP server
npm start
# Server runs at http://localhost:3000/mcp

# Or run stdio server
npm run start:stdio

配置

环境变量

连接客户

光标

选项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服务器。

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

MCP检查员

npx @modelcontextprotocol/inspector
# Connect to http://localhost:3000/mcp

用法

典型工作流程

1. get_repos          → Get current repo URL and branch
2. create_task       → Launch task with prompt
3. get_task          → Check status (CREATING → RUNNING → FINISHED)
4. add_followup       → (optional) Send more instructions while running
5. get_conversation   → Review what the task did

可用工具

发现工具

任务生命周期工具

常见示例

任务

{
  "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-.*"] -以“我的-”开头的repo
• [".*api.*"] -包含“api”的repo
• ["github.com/myorg"] -来自特定组织的repo
• [".*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"
  }
}

响应形状

所有工具都返回与匹配的结构化JSON响应 云代理API 规范。看 docs.md 获取完整的API文档。

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 呼叫

并行化规则

CAN并行运行：

• 修改完全不同文件的任务
• 在不接触共享文件的情况下创建新文件的任务

无法并行运行：

• 修改同一文件的任务
• 一个任务依赖于另一个任务的输出
• 同时修改package.json、tsconfig.json等的任务。

服务器版本

此软件包包括两个服务器版本：

• HTTP服务器 (src/server.ts)：在端口3000上运行Express HTTP服务器。用于远程连接或需要HTTP端点时。
• 标准服务器 (src/server-stdio.ts)：使用标准输入/输出。建议用于本地集成。更适合基于过程的产卵。

运行方式：

• HTTP： npm start （默认）
• 音乐节目 ： npm run start:stdio

发展

健康检查

服务器公开了一个健康检查终结点：

curl http://localhost:3000/health

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

发布到npm

要将此包发布到npm：

# Make sure you're logged in
npm login

# Publish
npm publish

该套餐将于以下时间提供 cursor-cloud-agent-mcp 在npm上。

许可证

麻省理工学院