Cursor Background Agent Api

🚀 Cursor Background Agent API 客户端

强大的 Node.js API 客户端和 CLI 工具，用于 Cursor 后台作曲器自动化

这是一个基于 TypeScript 的 API 客户端，可通过编程方式访问 Cursor 的后台作曲器功能。借助 CLI 和 MCP（模型上下文协议）服务器支持，你可以创建、管理和监控后台编码任务。

🚀 快速开始

本客户端可帮助你轻松管理 Cursor 的后台作曲器，通过 CLI 或 API 接口即可创建、监控和管理编码任务。

✨ 主要特性

• CLI 界面：用于管理后台作曲器的命令行工具。
• MCP 服务器：用于集成 AI 助手的模型上下文协议服务器。
• TypeScript 支持：具备完整的类型安全和智能提示功能。
• 后台作曲器管理：可创建、列出和监控编码任务。
• 用户设置控制：管理隐私模式和网络访问设置。
• 仓库集成：自动检测 Git 仓库。
• 多种输出格式：支持 JSON、表格和原始输出格式。

📦 安装指南

使用 npm 全局安装

npm install -g cursor-api-client

克隆仓库并本地构建

git clone https://github.com/mjdierkes/cursor-background-agent-api.git
cd cursor-background-agent-api
npm install
npm run build

🔧 配置步骤

1. 获取会话令牌

你需要一个 Cursor 会话令牌来验证 API 请求： 选项 A：环境变量（推荐）

export CURSOR_SESSION_TOKEN="your_session_token_here"

选项 B：Cookies 文件 创建一个 cookies.json 文件，包含你的 Cursor 会话 cookie：

[
  {
    "name": "WorkosCursorSessionToken", 
    "value": "your_session_token_here"
  }
]

2. 验证配置

测试你的配置：

cursor-api test

💻 使用示例

CLI 使用示例

列出后台作曲器

cursor-api list
cursor-api list --format json

创建后台作曲器

cursor-api create --task-description "Add user authentication to the app"
cursor-api create -d "Fix bug in payment processing" -r "https://github.com/user/repo.git"

获取作曲器详情

cursor-api details --composer-id "your-composer-id"

检查设置

cursor-api web-access    # 检查代理网络访问权限
cursor-api privacy       # 检查隐私模式设置
cursor-api settings      # 获取用户设置

可用命令

• list：列出所有后台作曲器。
• create：创建新的后台作曲器任务。
• details：获取作曲器详细信息。
• web-access：检查代理网络访问状态。
• privacy：获取隐私模式设置。
• settings：获取用户设置。
• test：测试所有 API 端点。
• mcp-server：启动 MCP 服务器。

全局选项

• --format, -f：输出格式：json、table、raw（默认：table）。
• --verbose, -v：启用详细日志记录。
• --token, -T：覆盖会话令牌。
• --help, -h：显示帮助信息。

GitHub 工作流集成

借助包含的 GitHub Actions 工作流，为每个新问题自动触发后台代理。

配置步骤

1. 添加工作流文件（本仓库已包含）：
   • .github/workflows/issue-background-agent.yml
2. 配置 Cursor 会话令牌密钥：
   • 转到你的仓库设置 > 密钥和变量 > Actions。
   • 添加一个名为 CURSOR_SESSION_TOKEN 的新仓库密钥。
   • 将值设置为你的 Cursor 会话令牌。
3. 启用工作流：
   • 当创建新问题时，工作流将自动触发。
   • 它将分析问题并创建一个后台作曲器任务。
   • 会在问题上发表评论，确认代理已触发。

工作原理

当创建新问题时，工作流会：

1. 直接调用 Cursor 的后台作曲器端点的 API。
2. 传递完整的问题信息（标题、正文、作者、标签、URL）。
3. 在问题上发表评论，确认代理已触发。 后台代理将接收：

• 问题标题和描述。
• 作者信息。
• 标签。
• 仓库上下文。
• 问题的直接链接。 结果将在 Cursor 后台作曲器界面中显示。

工作流特性

• 自动触发：在每个新问题上运行。
• 快速执行：直接调用 API，无需设置步骤。
• 丰富上下文：将完整的问题信息传递给代理。
• 用户反馈：在问题上发表评论确认激活。
• 仓库感知：自动使用当前仓库 URL。

API 客户端使用示例

import { CursorAPIClient } from 'cursor-api-client';

const client = new CursorAPIClient('your-session-token');

// 创建后台作曲器
const result = await client.createBackgroundComposer({
  taskDescription: 'Add user authentication',
  repositoryUrl: 'https://github.com/user/repo.git',
  branch: 'main',
  model: 'claude-4-sonnet-thinking'
});

// 列出作曲器
const composers = await client.listComposers();

// 获取设置
const settings = await client.getUserSettings();

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。