# 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**:
```json
{
  "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):
```json
{
  "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:

```json
{
  "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

1. **LLM Gateway** aufbauen mit OpenAI-kompatiblem Interface
2. **System Prompt Builder** implementieren (konfigurierbar)
3. **Context Assembly** fuer Workspace-Informationen
4. **Streaming Response** via SSE
5. **Response Parser** fuer Dokument-Extraktion

### Phase 2: Tool-Integration

1. **Tool Registry** mit dynamischer Konfiguration
2. **File System Tools** (read, edit, grep, glob)
3. **Tool Execution Engine** mit Sandbox
4. **Multi-Turn Conversation** mit Tool-Results

### Phase 3: Plan Mode

1. **Plan Mode Flag** im Request
2. **Read-Only Enforcement** (nur lesende Tools)
3. **create_plan Response Parsing**
4. **Klaerende Fragen** als eigener Dokument-Typ

### Phase 4: Subagenten

1. **Task Delegation** an parallel laufende Sub-Agenten
2. **Result Aggregation** in Parent-Response
3. **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