Cursor Background Agent API

光标后台代理API客户端

用于光标后台生成器自动化的强大Node.js API客户端和CLI工具

一个基于类型脚本的API客户端，提供对Cursor的后台生成器功能的编程访问。使用CLI和MCP（模型上下文协议）服务器支持创建、管理和监视后台编码任务。

特性

• CLI接口 -用于管理后台作曲家的命令行工具
• MCP服务器 -用于AI辅助集成的模型上下文协议服务器
• TypeScript支持 -全类型安全和智能感知
• 后台编辑器管理 -创建、列出和监控编码任务
• 用户设置控制 -管理隐私模式和网络访问设置
• 存储库集成 -自动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：Cookie文件 创建一个 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    # Check agent web access
cursor-api privacy       # Check privacy mode settings  
cursor-api settings      # Get user settings

可用命令

• list -列出所有背景作曲家
• create -创建新的背景编辑器任务
• details -获取详细的作曲家信息
• web-access -检查代理web访问状态
• 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

1. 配置游标会话令牌密钥:

- 转到存储库的“设置”>“机密和变量”>“操作” - 添加名为的新存储库密钥 CURSOR_SESSION_TOKEN - 为您的Cursor会话令牌设置值

1. 启用工作流:

- 创建新问题时，工作流将自动触发 - 它将分析问题并创建背景作曲任务 - 将对该问题发表评论，确认代理已被触发

原理

创建新问题时，工作流：

1. 对Cursor的后台编写器终结点进行直接的API调用
2. 传递完整的问题信息（标题、正文、作者、标签、URL）
3. 发布关于该问题的评论，确认代理已被触发

后台代理将收到：

• 问题标题和描述
• 作者信息
• 标签
• 存储库上下文
• 直接链接到问题

结果将在光标背景编辑器界面中显示。

工作流功能

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

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Start MCP server in development
npm run mcp-server:dev

API客户端使用情况

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

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

// Create background composer
const result = await client.createBackgroundComposer({
  taskDescription: 'Add user authentication',
  repositoryUrl: 'https://github.com/user/repo.git',
  branch: 'main',
  model: 'claude-4-sonnet-thinking'
});

// List composers
const composers = await client.listComposers();

// Get settings
const settings = await client.getUserSettings();

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。