Cursor Background Agent Api

🚀 Cursor背景代理API客戶端

Cursor背景代理API客戶端是一個強大的Node.js API客戶端和CLI工具，用於自動化Cursor背景編寫器。它基於TypeScript，能讓你以編程方式訪問Cursor的背景編寫器功能。藉助它，你不僅可以通過命令行工具管理背景編寫任務，還能利用MCP（模型上下文協議）服務器進行集成，輕鬆創建、管理和監控背景編碼任務。

✨ 主要特性

• 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：Cookie文件 創建一個包含Cursor會話Cookie的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 "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的背景編寫器端點。
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: '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文件。