ValueOn AG 040067f6af cursor-mode-integration-mvp

2026-02-23 17:13:26 +01:00

11 KiB

Raw Blame History

Cursor Chat-Komponente als API - Integrationskonzept

Stand: Februar 2026 Zweck: Konzept zur Extraktion der Chat-Funktionalitaet aus Cursor als eigenstaendige, API-gesteuerte Komponente

1. Zielsetzung

Die Chat-Funktionalitaet von Cursor soll als eigenstaendige Komponente ueber ein API nutzbar sein, ohne den Cursor selbst zu gefaehrden. Das Ziel:

User-Prompt in Chat-Fenstern als Komponente ueber API nutzen
Antworten als JSON-Objekt erhalten, in welchem Antwortteile als einzelne Dokumente erfasst sind
Neue Funktionen zuerst isoliert testen, bevor sie in den Cursor integriert werden

2. Architektur-Optionen

Option A: Cursor Backend direkt ansprechen (Recommended)

Cursor's Backend ist ueber zwei Protokolle erreichbar:

Variante 1: ConnectRPC / Protobuf

Eigene App → ConnectRPC Client → api2.cursor.sh → LLM Response Stream

Verwendet aiserver.v1.ChatService
Methode: StreamChat() oder StreamUnifiedChatWithTools()
Authentifizierung: Cursor Session Token
Vorteil: Direkter Zugriff auf alle Modelle und Features
Nachteil: Abhaengigkeit von Cursor's Backend, Protobuf-Schema kann sich aendern

Variante 2: Background Agent API

Eigene App → REST/HTTP → Cursor Background Composer API → Agent Response

Nutzt den offiziellen Background Agent Endpoint
Authentifizierung: WorkosCursorSessionToken
Vorteil: Offiziell unterstuetzt, stabiler
Nachteil: Weniger Kontrolle, asynchron

Option B: Eigener LLM-Orchestrierungslayer (Empfohlen fuer Unabhaengigkeit)

Die Cursor-Architektur nachbauen, aber als eigene Komponente:

Eigene App
  ↓
Chat API Gateway (eigener Service)
  ├─> Prompt Assembly
  │     ├─> System Prompt (konfigurierbar)
  │     ├─> Context Injection (Dateien, Projekt-Layout)
  │     └─> Tool-Definitionen
  ├─> LLM Provider (OpenAI / Anthropic / eigener)
  │     ├─> POST /v1/chat/completions (OpenAI-kompatibel)
  │     ├─> Streaming via SSE
  │     └─> Tool Calling
  ├─> Response Parser
  │     ├─> Text-Segmente extrahieren
  │     ├─> Tool-Calls identifizieren
  │     ├─> Code-Bloecke parsen
  │     └─> Plan/Todo-Strukturen erkennen
  └─> JSON Response Builder
        └─> Strukturiertes JSON mit Dokumenten-Array

Vorteile:

Keine Abhaengigkeit von Cursor's Backend
Eigene Modelle und Provider waehlbar
Volle Kontrolle ueber Prompt-Struktur
Testbar ohne Cursor-Installation
Erweiterbar mit eigenen Tools

3. API-Design

3.1 Chat Endpoint

POST /api/v1/chat/completions
Content-Type: application/json
Authorization: Bearer <token>

Request:

{
  "model": "claude-4.6-opus",
  "mode": "agent",
  "context": {
    "workspacePath": "/path/to/project",
    "openFiles": ["src/main.py", "src/utils.py"],
    "projectLayout": "src/\n  main.py\n  utils.py\nREADME.md",
    "rules": [
      "camelCase fuer Variablen",
      "Interne Funktionen mit _ Prefix"
    ]
  },
  "messages": [
    {
      "role": "user",
      "content": "Implementiere eine Authentication-Middleware"
    }
  ],
  "tools": ["codebase_search", "read_file", "edit_file", "grep"],
  "stream": false
}

Response (siehe doc_cursor_response_json_structure.md fuer Details):

{
  "id": "chat_abc123",
  "model": "claude-4.6-opus",
  "mode": "agent",
  "created": "2026-02-23T10:30:00Z",
  "documents": [
    {
      "id": "doc_001",
      "type": "text",
      "content": "Ich werde eine Authentication-Middleware implementieren..."
    },
    {
      "id": "doc_002",
      "type": "tool_call",
      "toolName": "read_file",
      "arguments": { "target_file": "src/main.py" },
      "result": "import os\nimport sys..."
    },
    {
      "id": "doc_003",
      "type": "code_reference",
      "filePath": "src/main.py",
      "startLine": 12,
      "endLine": 25,
      "content": "def main():\n    app = Flask(__name__)..."
    },
    {
      "id": "doc_004",
      "type": "code_block",
      "language": "python",
      "content": "def authMiddleware(f):\n    @wraps(f)\n    def decorated(*args):\n        ..."
    },
    {
      "id": "doc_005",
      "type": "file_edit",
      "filePath": "src/middleware/auth.py",
      "operation": "create",
      "content": "from functools import wraps\n..."
    },
    {
      "id": "doc_006",
      "type": "plan",
      "title": "Auth Middleware Plan",
      "todos": [
        { "id": "setup-auth", "content": "Middleware-Funktion erstellen", "status": "completed" },
        { "id": "add-routes", "content": "Routes schuetzen", "status": "pending" }
      ]
    }
  ],
  "usage": {
    "promptTokens": 2450,
    "completionTokens": 890,
    "totalTokens": 3340
  }
}

3.2 Streaming Endpoint

POST /api/v1/chat/completions
Content-Type: application/json
Accept: text/event-stream

Gleicher Request wie oben, aber mit "stream": true.

SSE Response:

data: {"type": "document_start", "document": {"id": "doc_001", "type": "text"}}

data: {"type": "content_delta", "documentId": "doc_001", "delta": "Ich werde "}

data: {"type": "content_delta", "documentId": "doc_001", "delta": "eine Authentication-"}

data: {"type": "content_delta", "documentId": "doc_001", "delta": "Middleware implementieren..."}

data: {"type": "document_end", "documentId": "doc_001"}

data: {"type": "document_start", "document": {"id": "doc_002", "type": "tool_call", "toolName": "read_file"}}

data: {"type": "tool_call_arguments", "documentId": "doc_002", "arguments": {"target_file": "src/main.py"}}

data: {"type": "tool_result", "documentId": "doc_002", "result": "import os\n..."}

data: {"type": "document_end", "documentId": "doc_002"}

data: {"type": "done", "usage": {"promptTokens": 2450, "completionTokens": 890}}

data: [DONE]

3.3 Plan Mode Endpoint

POST /api/v1/chat/plan

Gleiche Struktur, aber:

Nur Read-Only Tools verfuegbar
Response enthaelt type: "plan" Dokument mit strukturiertem Markdown
Klaerende Fragen als type: "clarification" Dokumente

4. Prompt Assembly Service

Der Kern der Integration ist der Prompt Assembly Service, der die gleiche Logik wie Cursor implementiert:

4.1 System Prompt Builder

buildSystemPrompt(config)
  ├─> Base Role Prompt
  │     "You are an AI coding assistant..."
  ├─> Communication Rules
  │     Markdown, Code Citations
  ├─> Tool Calling Rules
  │     Parallel Execution, Standard Format
  ├─> Context Strategy
  │     Thorough Exploration, Semantic Search
  ├─> Code Change Rules
  │     Read before Edit, Fix Lints
  ├─> Mode-Specific Rules
  │     Agent: Full tools | Plan: Read-only | Ask: Explain only
  ├─> Workspace Rules
  │     Aus .cursor/rules/ oder eigener Konfiguration
  └─> User Rules
        Benutzerdefinierte Praeferenzen

4.2 Context Assembly

assembleContext(request)
  ├─> User Info
  │     { os, date, shell, workspacePath }
  ├─> Project Layout
  │     File Tree (einmalig generiert)
  ├─> Open Files
  │     Aktuell geoeffnete Dateien mit Inhalt
  ├─> Recent Files
  │     Kuerzlich angesehene Dateien
  ├─> Git Status
  │     Branch, Staged/Unstaged Changes
  └─> Linter Errors
        Aktuelle Diagnostics

4.3 Tool-Registry

Tools werden dynamisch registriert und koennen pro Request konfiguriert werden:

{
  "availableTools": {
    "codebase_search": { "enabled": true, "scope": "workspace" },
    "read_file": { "enabled": true, "allowedPaths": ["src/", "tests/"] },
    "edit_file": { "enabled": true, "requireApproval": true },
    "run_terminal_cmd": { "enabled": false },
    "web_search": { "enabled": true }
  }
}

5. Response Parser

Der Response Parser wandelt den LLM-Stream in strukturierte Dokumente um:

5.1 Parsing-Pipeline

LLM Streaming Response
  ↓
Token Accumulator
  ↓
Segment Detector
  ├─> Text-Segment (alles ausserhalb von Code/Tools)
  ├─> Code-Block (``` ... ```)
  │     ├─> Code Reference (startLine:endLine:filepath)
  │     └─> Markdown Code Block (language tag)
  ├─> Tool Call (function call JSON)
  ├─> Plan (create_plan Tool-Aufruf)
  └─> Todo (todo_write Tool-Aufruf)
        ↓
Document Builder
  ├─> Jedem Segment eine Document-ID zuweisen
  ├─> Typ klassifizieren
  ├─> Metadaten extrahieren (Datei, Zeilen, Sprache)
  └─> In documents[] Array einfuegen
        ↓
JSON Response

5.2 Segment-Erkennung

Pattern	Dokument-Typ	Extrahierte Metadaten
Freitext	`text`	content
```startLine:endLine:filepath	`code_reference`	filePath, startLine, endLine, content
```python	`code_block`	language, content
Tool Call: `edit_file`	`file_edit`	filePath, operation, content
Tool Call: `read_file`	`tool_call`	toolName, arguments, result
Tool Call: `create_plan`	`plan`	title, overview, todos
Tool Call: `todo_write`	`todo_update`	todos mit id/status
Tool Call: `run_terminal_cmd`	`terminal_command`	command, output, exitCode

6. Implementierungsschritte

Phase 1: Chat API Kern

LLM Gateway aufbauen mit OpenAI-kompatiblem Interface
System Prompt Builder implementieren (konfigurierbar)
Context Assembly fuer Workspace-Informationen
Streaming Response via SSE
Response Parser fuer Dokument-Extraktion

Phase 2: Tool-Integration

Tool Registry mit dynamischer Konfiguration
File System Tools (read, edit, grep, glob)
Tool Execution Engine mit Sandbox
Multi-Turn Conversation mit Tool-Results

Phase 3: Plan Mode

Plan Mode Flag im Request
Read-Only Enforcement (nur lesende Tools)
create_plan Response Parsing
Klaerende Fragen als eigener Dokument-Typ

Phase 4: Subagenten

Task Delegation an parallel laufende Sub-Agenten
Result Aggregation in Parent-Response
Background Agent fuer lang laufende Tasks

7. Technologie-Empfehlung

Komponente	Empfehlung	Begruendung
API Framework	FastAPI (Python) oder Express (Node.js)	SSE-Support, async, schnell
LLM Client	`openai` SDK oder `anthropic` SDK	Standard, gut gewartet
Streaming	Server-Sent Events (SSE)	Browser-kompatibel, einfach
Prompt Templates	Jinja2 (Python) oder Handlebars (JS)	Flexibel, testbar
File System Access	Lokaler Zugriff oder MCP Server	Sicherheit, Modularitaet
Codebase Search	tree-sitter + Vektor-DB	Wie Cursor, AST-basiert

Referenzen

Cursor Architektur: doc_cursor_ai_agent_architecture.md
JSON Response Struktur: doc_cursor_response_json_structure.md
OpenAI Chat Completions API: https://platform.openai.com/docs/api-reference/chat
Server-Sent Events: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

11 KiB Raw Blame History