Cursor Background Agent Api

🚀 Cursor Background Agent API Client

Cursorの背景コンポーザーの自動化を行う強力なNode.js APIクライアントとCLIツール

TypeScriptベースのAPIクライアントで、Cursorの背景コンポーザー機能にプログラムからアクセスできます。CLIとMCP（Model Context Protocol）サーバーの両方をサポートし、背景でのコーディングタスクを作成、管理、監視できます。

✨ 主な機能

• CLIインターフェイス - 背景コンポーザーを管理するためのコマンドラインツール
• MCPサーバー - AIアシスタントを統合するためのModel Context Protocolサーバー
• TypeScriptサポート - 完全な型安全性とIntelliSense
• 背景コンポーザー管理 - コーディングタスクを作成、一覧表示、監視
• ユーザー設定管理 - プライバシーモードとWebアクセス設定を管理
• リポジトリ統合 - 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. セッショントークンの取得

APIリクエストを認証するには、Cursorのセッショントークンが必要です。

オプションA: 環境変数（推奨）

export CURSOR_SESSION_TOKEN="your_session_token_here"

オプションB: クッキーファイル Cursorのセッションクッキーを含む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    # エージェントのWebアクセスを確認
cursor-api privacy       # プライバシーモード設定を確認
cursor-api 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ワークフローを使用して、新しいissueごとに自動的に背景エージェントをトリガーできます。

設定

1. ワークフローファイルを追加する（このリポジトリにすでに含まれています）

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

2. Cursorのセッショントークンシークレットを設定する

   • リポジトリのSettings > Secrets and variables > Actionsに移動します。
   • CURSOR_SESSION_TOKENという名前の新しいリポジトリシークレットを追加します。
   • 値にCursorのセッショントークンを設定します。

3. ワークフローを有効にする

   • 新しいissueが作成されると、ワークフローが自動的にトリガーされます。
   • issueを分析し、背景コンポーザータスクを作成します。
   • issueにエージェントがトリガーされたことを確認するコメントが投稿されます。

動作原理

新しいissueが作成されると、ワークフローは以下の処理を行います。

1. Cursorの背景コンポーザーエンドポイントに直接API呼び出しを行います。
2. 完全なissue情報（タイトル、本文、作者、ラベル、URL）を渡します。
3. issueにエージェントがトリガーされたことを確認するコメントを投稿します。

背景エージェントは以下の情報を受け取ります。

• issueのタイトルと説明
• 作者情報
• ラベル
• リポジトリのコンテキスト
• issueへの直接リンク

結果はCursor Background Composerインターフェイスで確認できます。

ワークフローの機能

• 自動トリガー - 新しいissueごとに実行されます。
• 高速実行 - セットアップ手順なしで直接API呼び出しを行います。
• 豊富なコンテキスト - 完全なissue情報をエージェントに渡します。
• ユーザーフィードバック - issueにコメントを投稿してアクティベーションを確認します。
• リポジトリ認識 - 現在のリポジトリの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ファイルを参照してください。