copilot-cursor-proxy 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# 🚀 Copilot Proxy for Cursor
+
+> Forked from [jacksonkasi1/copilot-for-cursor](https://github.com/jacksonkasi1/copilot-for-cursor) with fixes for full Anthropic → OpenAI message conversion.
+
+**Unlock the full power of GitHub Copilot in Cursor IDE.**
+
+This project provides a local proxy server that acts as a bridge between Cursor and GitHub Copilot. It solves key limitations by:
+1.  **Bypassing Cursor's Model Routing:** Using a custom prefix (`cus-`) to force Cursor to use your own API endpoint instead of its internal backend.
+2.  **Enabling Agentic Capabilities:** Transforming Cursor's Anthropic-style tool calls into OpenAI-compatible formats that Copilot understands. This enables **File Editing, Terminal Execution, Codebase Search, and MCP Tools**.
+3.  **Fixing Schema Errors:** Automatically sanitizing requests to prevent `400 Bad Request` errors caused by format mismatches (e.g., `tool_choice`, `cache_control`, unsupported content types).
+
+### Changes in this fork
+
+- **Full Anthropic → OpenAI message conversion:** Assistant `tool_use` blocks are converted to OpenAI `tool_calls`; user `tool_result` blocks become `tool` role messages. This fixes `unexpected tool_use_id found in tool_result blocks` errors.
+- **Unsupported content type stripping:** Blocks with types like `thinking`, `tool_use` (in user messages), etc. are filtered out before forwarding, preventing `type has to be either 'image_url' or 'text'` errors.
+- **Windows setup instructions** added below.
+
+---
+
+## 🏗 Architecture
+
+```
+Cursor → (HTTPS tunnel) → proxy-router (:4142) → copilot-api (:4141) → GitHub Copilot
+```
+
+*   **Port 4141 (`copilot-api`):** The core service that authenticates with GitHub and provides the OpenAI-compatible API.
+    *   *Powered by [caozhiyuan/copilot-api](https://github.com/caozhiyuan/copilot-api) (installed via `npx`).*
+*   **Port 4142 (`proxy-router`):** The intelligence layer. It intercepts requests, converts Anthropic-format messages to OpenAI format, handles the `cus-` prefix, and serves the dashboard.
+*   **HTTPS tunnel (Cloudflare/ngrok):** Cursor requires HTTPS — a tunnel exposes the local proxy to the internet.
+
+### Proxy Router Modules
+
+The proxy router is split into focused modules:
+
+| File | Responsibility |
+|---|---|
+| `proxy-router.ts` | Entrypoint — Bun.serve, routing, CORS, dashboard, model list |
+| `anthropic-transforms.ts` | Anthropic → OpenAI normalization (fields, tools, messages) |
+| `responses-bridge.ts` | Chat Completions → Responses API bridge for GPT-5.x / o-series |
+| `responses-converters.ts` | Responses API → Chat Completions format (sync & streaming) |
+| `stream-proxy.ts` | Streaming passthrough with chunk logging and error detection |
+| `debug-logger.ts` | Request/response debug logging helpers |
+
+---
+
+## 🛠 Setup Guide
+
+### Prerequisites
+*   [Node.js](https://nodejs.org/) & npm
+*   [Bun](https://bun.sh/) (for the proxy-router)
+*   A tunnel tool — **Cloudflare Tunnel** (free, no signup) or **ngrok**
+*   GitHub account with a **Copilot subscription** (individual, business, or enterprise)
+
+### Quick Start (Windows)
+
+Open **3 separate terminals** and run each command:
+
+**Terminal 1 — Start copilot-api (port 4141):**
+```sh
+npx @jeffreycao/copilot-api@latest start
+```
+> On first run, it will prompt you to authenticate via GitHub device flow.
+
+**Terminal 2 — Start proxy-router (port 4142):**
+```sh
+cd copilot-for-cursor
+bun run proxy-router.ts
+```
+
+**Terminal 3 — Start HTTPS tunnel:**
+
+Using Cloudflare Tunnel (recommended, free, no signup):
+```sh
+# Install (one-time)
+winget install cloudflare.cloudflared
+
+# Run tunnel
+cloudflared tunnel --url http://localhost:4142
+```
+
+Or using ngrok:
+```sh
+ngrok http 4142
+```
+
+Copy the HTTPS URL from the tunnel output (e.g., `https://xxxxx.trycloudflare.com`).
+
+### Quick Start (macOS)
+
+Run the setup scripts for persistent background services:
+```bash
+# 1. Setup Core API (Port 4141)
+chmod +x setup-copilot-service.sh
+./setup-copilot-service.sh
+
+# 2. Setup Proxy Router (Port 4142)
+chmod +x setup-proxy-service.sh
+./setup-proxy-service.sh
+
+# 3. Start tunnel
+ngrok http 4142
+```
+
+### Verify Services
+Check if the dashboard is running:
+👉 **[http://localhost:4142](http://localhost:4142)**
+
+![Dashboard Preview](./dashboard-preview.png)
+
+---
+
+## ⚙️ Cursor Configuration
+
+1.  Go to **Settings** (Gear Icon) → **Models**.
+2.  Toggle **OFF** "Copilot" (optional, to avoid conflicts).
+3.  Add a new **OpenAI Compatible** model:
+    *   **Base URL:** `https://your-tunnel-url.trycloudflare.com/v1`
+    *   **API Key:** `dummy` (any value works, unless you configured `auth.apiKeys` in copilot-api's `config.json`)
+    *   **Model Name:** Use a **prefixed name** — e.g., `cus-gpt-4o`, `cus-claude-sonnet-4`, `cus-claude-sonnet-4.5`
+
+> **💡 Tip:** Go to the [Dashboard](http://localhost:4142) to see all available models and copy their IDs.
+
+> **⚠️ Important:** You **must** use the `cus-` prefix. Without it, Cursor routes the request to its own backend instead of your proxy.
+
+### Available Models (examples)
+
+| Cursor Model Name | Actual Model |
+|---|---|
+| `cus-gpt-4o` | GPT-4o |
+| `cus-gpt-5.4` | GPT-5.4 |
+| `cus-claude-sonnet-4` | Claude Sonnet 4 |
+| `cus-claude-sonnet-4.5` | Claude Sonnet 4.5 |
+| `cus-claude-opus-4.6` | Claude Opus 4.6 |
+| `cus-gemini-2.5-pro` | Gemini 2.5 Pro |
+
+![Cursor Settings Configuration](./cursor-settings.png)
+
+---
+
+## 🔒 Security: API Key Protection
+
+If you're using a tunnel (exposing to the public internet), set an API key in copilot-api's config:
+
+**Config location:**
+- Linux/macOS: `~/.local/share/copilot-api/config.json`
+- Windows: `%USERPROFILE%\.local\share\copilot-api\config.json`
+
+```json
+{
+  "auth": {
+    "apiKeys": ["your-secret-key-here"]
+  }
+}
+```
+
+Then use the same key as the **API Key** in Cursor settings.
+
+---
+
+## ✨ Features & Supported Tools
+
+This proxy enables **full agentic workflows**:
+
+*   **💬 Chat & Reasoning:** Full conversation context with standard models.
+*   **📂 File System:** `Read`, `Write`, `StrReplace`, `Delete`.
+*   **💻 Terminal:** `Shell` (Run commands).
+*   **🔍 Search:** `Grep`, `Glob`, `SemanticSearch`.
+*   **🔌 MCP Tools:** Full support for external tools like Neon, Playwright, etc.
+
+### What the proxy handles
+
+| Cursor sends (Anthropic format) | Proxy converts to (OpenAI format) |
+|---|---|
+| `tool_use` blocks in assistant messages | `tool_calls` array |
+| `tool_result` blocks in user messages | `tool` role messages |
+| `thinking` blocks | Stripped (not supported) |
+| `cache_control` on content blocks | Stripped |
+| `input_schema` on tools | Converted to `parameters` |
+| Anthropic `tool_choice` objects | OpenAI string format |
+| Images in Claude requests | Stripped with `[Image Omitted]` placeholder |
+
+---
+
+## ⚠️ Known Limitations
+
+### Claude Vision
+*   **Gemini / GPT-4o:** Full Vision Support ✅
+*   **Claude (via Copilot):** Does **NOT** support images via the API proxy ❌
+
+The proxy automatically strips images from Claude requests to prevent crashes.
+
+### What's lost vs native Anthropic API
+Since Cursor sends to `/v1/chat/completions` (OpenAI) instead of `/v1/messages` (Anthropic), some features are unavailable:
+
+| Feature | Status |
+|---|---|
+| Extended thinking (chain-of-thought) | ❌ Stripped |
+| Prompt caching (`cache_control`) | ❌ Stripped |
+| Context management beta | ❌ Not available |
+| Premium request optimization | ❌ Bypassed |
+| Basic chat & tool calling | ✅ Works |
+| Streaming | ✅ Works |
+
+### Tunnel URL changes on restart
+Cloudflare quick tunnels generate a new URL each time. You'll need to update Cursor settings when you restart the tunnel. Consider a paid plan for a fixed subdomain.
+
+---
+
+### 📝 Troubleshooting
+
+**"Model name is not valid" in Cursor:**
+Make sure you're using the `cus-` prefix (e.g., `cus-gpt-4o`, not `gpt-4o`).
+
+**"connection refused" on tunnel:**
+Ensure all 3 services are running (copilot-api on 4141, proxy-router on 4142, tunnel).
+
+**500 errors from copilot-api:**
+Restart copilot-api. If the error mentions `messages`, the proxy should now handle it — make sure you're running the latest `proxy-router.ts`.
+
+**Logs (macOS):**
+*   Proxy: `tail -f ~/Library/Logs/copilot-proxy.log`
+*   API: `tail -f ~/Library/Logs/copilot-api.log`
+
+---
+
+> ⚠️ **DISCLAIMER:** This project is **unofficial** and created for **educational purposes only**. It interacts with undocumented internal APIs of GitHub Copilot and Cursor. Use at your own risk. The authors are not affiliated with GitHub, Microsoft, or Anysphere (Cursor). Please use your API credits responsibly and in accordance with the provider's Terms of Service.

package/anthropic-transforms.ts

@@ -0,0 +1,185 @@
+const cleanSchema = (schema: any): any => {
+    if (!schema || typeof schema !== 'object') return schema;
+    if (schema.additionalProperties !== undefined) delete schema.additionalProperties;
+    if (schema.$schema !== undefined) delete schema.$schema;
+    if (schema.title !== undefined) delete schema.title;
+    if (schema.properties) {
+        for (const key in schema.properties) cleanSchema(schema.properties[key]);
+    }
+    if (schema.items) cleanSchema(schema.items);
+    return schema;
+};
+
+const sanitizeContentPart = (part: any, isClaude: boolean): any | null => {
+    if (part.cache_control) delete part.cache_control;
+
+    if (isClaude && (part.type === 'image' || (part.source?.type === 'base64'))) {
+        return { type: 'text', text: '[Image Omitted]' };
+    }
+    if (part.type === 'image' && part.source?.type === 'base64') {
+        return { type: 'image_url', image_url: { url: `data:${part.source.media_type};base64,${part.source.data}` } };
+    }
+    if (part.type === 'image') { part.type = 'image_url'; return part; }
+
+    if (part.type === 'text' || part.type === 'image_url') return part;
+
+    return null;
+};
+
+const transformAnthropicFields = (json: any): void => {
+    if (json.system) {
+        const systemText = typeof json.system === 'string' 
+            ? json.system 
+            : Array.isArray(json.system) 
+                ? json.system.map((s: any) => typeof s === 'string' ? s : s.text || '').join('\n')
+                : String(json.system);
+        if (json.messages && Array.isArray(json.messages)) {
+            const hasSystem = json.messages.some((m: any) => m.role === 'system');
+            if (!hasSystem) {
+                json.messages.unshift({ role: 'system', content: systemText });
+            }
+        }
+        delete json.system;
+        console.log('🔧 Converted top-level system field to system message');
+    }
+
+    if (json.stop_sequences) {
+        json.stop = json.stop_sequences;
+        delete json.stop_sequences;
+        console.log('🔧 Converted stop_sequences → stop');
+    }
+
+    if (json.max_tokens_to_sample && !json.max_tokens) {
+        json.max_tokens = json.max_tokens_to_sample;
+        delete json.max_tokens_to_sample;
+    }
+
+    const anthropicOnlyFields = ['metadata', 'anthropic_version', 'top_k'];
+    for (const field of anthropicOnlyFields) {
+        if (json[field] !== undefined) {
+            console.log(`🔧 Removing Anthropic-only field: ${field}`);
+            delete json[field];
+        }
+    }
+};
+
+const transformTools = (json: any): void => {
+    if (!json.tools || !Array.isArray(json.tools)) return;
+
+    json.tools = json.tools.map((tool: any) => {
+        let parameters = tool.input_schema || tool.parameters || {};
+        parameters = cleanSchema(parameters);
+        if (tool.type === 'function' && tool.function) {
+            tool.function.parameters = cleanSchema(tool.function.parameters);
+            return tool;
+        }
+        return {
+            type: "function",
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: parameters 
+            }
+        };
+    });
+};
+
+const transformToolChoice = (json: any): void => {
+    if (!json.tool_choice || typeof json.tool_choice !== 'object') return;
+
+    if (json.tool_choice.type === 'auto') json.tool_choice = "auto";
+    else if (json.tool_choice.type === 'none') json.tool_choice = "none";
+    else if (json.tool_choice.type === 'required') json.tool_choice = "required";
+    else if (json.tool_choice.type === 'any') json.tool_choice = "required";
+    else if (json.tool_choice.type === 'tool' && json.tool_choice.name) {
+        json.tool_choice = { type: "function", function: { name: json.tool_choice.name } };
+    }
+};
+
+const transformMessages = (json: any, isClaude: boolean): void => {
+    if (!json.messages || !Array.isArray(json.messages)) return;
+
+    const newMessages: any[] = [];
+
+    for (const msg of json.messages) {
+        if (msg.role === 'assistant' && Array.isArray(msg.content)) {
+            const textParts: string[] = [];
+            const toolCalls: any[] = [];
+
+            for (const part of msg.content) {
+                if (part.type === 'tool_use') {
+                    toolCalls.push({
+                        id: part.id,
+                        type: 'function',
+                        function: {
+                            name: part.name,
+                            arguments: typeof part.input === 'string' ? part.input : JSON.stringify(part.input ?? {})
+                        }
+                    });
+                } else if (part.type === 'text') {
+                    textParts.push(part.text);
+                }
+            }
+
+            const assistantMsg: any = { role: 'assistant' };
+            assistantMsg.content = textParts.join('\n') || null;
+            if (toolCalls.length > 0) assistantMsg.tool_calls = toolCalls;
+            newMessages.push(assistantMsg);
+            continue;
+        }
+
+        if (msg.role === 'user' && Array.isArray(msg.content)) {
+            const toolResults = msg.content.filter((c: any) => c.type === 'tool_result');
+            const otherParts = msg.content.filter((c: any) => c.type !== 'tool_result' && c.type !== 'tool_use');
+
+            for (const tr of toolResults) {
+                let resultContent = tr.content;
+                if (typeof resultContent !== 'string') {
+                    if (Array.isArray(resultContent)) {
+                        resultContent = resultContent.map((p: any) => p.text || JSON.stringify(p)).join('\n');
+                    } else {
+                        resultContent = JSON.stringify(resultContent);
+                    }
+                }
+                newMessages.push({
+                    role: 'tool',
+                    tool_call_id: tr.tool_use_id,
+                    content: resultContent || ''
+                });
+            }
+
+            if (otherParts.length > 0) {
+                const cleaned = otherParts.map((p: any) => sanitizeContentPart(p, isClaude)).filter(Boolean);
+                if (cleaned.length > 0) {
+                    newMessages.push({ role: 'user', content: cleaned });
+                }
+            }
+            continue;
+        }
+
+        if (Array.isArray(msg.content)) {
+            const cleaned = msg.content.map((p: any) => sanitizeContentPart(p, isClaude)).filter(Boolean);
+            msg.content = cleaned.length > 0 ? cleaned : ' ';
+        }
+        newMessages.push(msg);
+    }
+
+    json.messages = newMessages;
+
+    for (let i = 0; i < json.messages.length; i++) {
+        const msg = json.messages[i];
+        if (Array.isArray(msg.content) && msg.content.length === 0) {
+            msg.content = ' ';
+        }
+        if (Array.isArray(msg.content) && msg.content.length === 1 && msg.content[0].type === 'text') {
+            msg.content = msg.content[0].text || ' ';
+        }
+    }
+};
+
+export const normalizeRequest = (json: any, isClaude: boolean): void => {
+    transformAnthropicFields(json);
+    transformTools(json);
+    transformToolChoice(json);
+    transformMessages(json, isClaude);
+};

package/bin/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Check if bun is installed
+let bunPath;
+try {
+    bunPath = execSync('where bun', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim().split('\n')[0];
+} catch {
+    try {
+        bunPath = execSync('which bun', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    } catch {
+        console.error('❌ Bun is required but not installed.');
+        console.error('   Install it with: curl -fsSL https://bun.sh/install | bash');
+        console.error('   Or: npm install -g bun');
+        process.exit(1);
+    }
+}
+
+// Find start.ts relative to this script
+const pkgRoot = path.resolve(__dirname, '..');
+const startScript = path.join(pkgRoot, 'start.ts');
+
+if (!fs.existsSync(startScript)) {
+    console.error('❌ start.ts not found at:', startScript);
+    process.exit(1);
+}
+
+// Forward all args and run with bun
+const args = ['run', startScript, ...process.argv.slice(2)];
+const child = spawn(bunPath.trim(), args, {
+    stdio: 'inherit',
+    cwd: pkgRoot,
+    env: { ...process.env },
+});
+
+child.on('error', (err) => {
+    console.error('❌ Failed to start:', err.message);
+    process.exit(1);
+});
+
+child.on('exit', (code) => {
+    process.exit(code || 0);
+});
+
+// Forward signals for graceful shutdown
+process.on('SIGINT', () => child.kill('SIGINT'));
+process.on('SIGTERM', () => child.kill('SIGTERM'));