Cursor Background Agent API 客户端

强大的Node.js API客户端和CLI工具，用于Cursor Background Composer自动化

这是一个基于TypeScript的API客户端，提供了对Cursor背景编排功能的编程访问。通过CLI和MCP（模型上下文协议）服务器支持，创建、管理和监控后台编码任务。

功能

• CLI界面 - 命令行工具，用于管理背景编排器
• MCP服务器 - 用于AI助手集成的模型上下文协议服务器
• TypeScript支持 - 完整类型安全性和IntelliSense
• 背景编排器管理 - 创建、列出并监控编码任务
• 用户设置控制 - 管理隐私模式和网络访问设置
• 仓库集成 - 自动检测Git仓库
• 多种输出格式 - JSON、表格和原始输出格式

安装

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文件 创建一个包含你的Cursor会话cookies的cookies.json文件：

[
  {
    "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 "为应用程序添加用户认证"
cursor-api create -d "修复支付处理中的错误" -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）
• -v, --verbose - 启用详细日志
• -T, --token - 覆盖会话令牌
• -h, --help - 显示帮助

GitHub工作流集成

自动触发每个新问题的背景代理，使用包含的工作流。

配置

1. 添加工作流文件（已包含在此仓库中）：

   • .github/workflows/issue-background-agent.yml

2. 配置Cursor会话令牌密钥：

   • 进入你的仓库设置 > 密钥和变量 > 动作
   • 添加一个新的仓库密钥名为CURSOR_SESSION_TOKEN
   • 设置值为你自己的Cursor会话令牌

3. 启用工作流：

   • 当创建新问题时，工作流会自动触发
   • 它会分析问题并创建一个背景编排器任务
   • 在问题上发布评论确认代理已被触发

工作原理

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

1. 直接调用Cursor背景编排器端点的API
2. 传递完整的问题信息（标题、正文、作者、标签、URL）
3. 在问题上发布评论确认代理已被触发

背景代理将接收：

• 问题标题和描述
• 作者信息
• 标签
• 仓库上下文
• 问题的直接链接

结果将在Cursor背景编排器界面中可用。

工作流特性

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

开发

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 运行测试
npm test

# 构建生产版本
npm run build

# 开发模式启动MCP服务器
npm run mcp-server:dev

API客户端使用

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

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

// 创建背景编排器
const result = await client.createBackgroundComposer({
  taskDescription: '添加用户认证',
  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文件。