cursor-api-proxy 0.3.0

package/README.md

@@ -0,0 +1,219 @@
+# cursor-api-proxy
+
+OpenAI-compatible proxy for Cursor CLI. Expose Cursor models on localhost so any LLM client (OpenAI SDK, LiteLLM, LangChain, etc.) can call them as a standard chat API.
+
+This package works as **one npm dependency**: use it as an **SDK** in your app to call the proxy API, and/or run the **CLI** to start the proxy server. Core behavior is unchanged.
+
+## Prerequisites (required for the proxy to work)
+
+- **Node.js** 18+
+- **Cursor agent CLI** (`agent`). This package does **not** install or bundle the CLI. You must install and set it up separately. This project is developed and tested with `agent` version **2026.02.27-e7d2ef6**.
+
+  ```bash
+  curl https://cursor.com/install -fsS | bash
+  agent login
+  agent --list-models
+  ```
+
+  For automation, set `CURSOR_API_KEY` instead of using `agent login`.
+
+## Install
+
+**From npm (use as SDK in another project):**
+
+```bash
+npm install cursor-api-proxy
+```
+
+**From source (develop or run CLI locally):**
+
+```bash
+git clone <this-repo>
+cd cursor-api-proxy
+npm install
+npm run build
+```
+
+## Run the proxy (CLI)
+
+Start the server so the API is available (e.g. for the SDK or any HTTP client):
+
+```bash
+npx cursor-api-proxy
+# or from repo: npm start / node dist/cli.js
+```
+
+To expose on your network (e.g. Tailscale):
+
+```bash
+npx cursor-api-proxy --tailscale
+```
+
+By default the server listens on **http://127.0.0.1:8765**. Optionally set `CURSOR_BRIDGE_API_KEY` to require `Authorization: Bearer <key>` on requests.
+
+### HTTPS with Tailscale (MagicDNS)
+
+To serve over HTTPS so browsers and clients trust the connection (e.g. `https://macbook.tail4048eb.ts.net:8765`):
+
+1. **Generate Tailscale certificates** on this machine (run from the project directory or where you want the cert files):
+
+   ```bash
+   sudo tailscale cert macbook.tail4048eb.ts.net
+   ```
+
+   This creates `macbook.tail4048eb.ts.net.crt` and `macbook.tail4048eb.ts.net.key` in the current directory.
+
+2. **Run the proxy with TLS** and optional Tailscale bind:
+
+   ```bash
+   export CURSOR_BRIDGE_API_KEY=your-secret
+   export CURSOR_BRIDGE_TLS_CERT=/path/to/macbook.tail4048eb.ts.net.crt
+   export CURSOR_BRIDGE_TLS_KEY=/path/to/macbook.tail4048eb.ts.net.key
+   # Bind to Tailscale IP so the service is only on the tailnet (optional):
+   export CURSOR_BRIDGE_HOST=100.123.47.103
+   npm start
+   ```
+
+   Or bind to all interfaces and use HTTPS:
+
+   ```bash
+   CURSOR_BRIDGE_TLS_CERT=./macbook.tail4048eb.ts.net.crt \
+   CURSOR_BRIDGE_TLS_KEY=./macbook.tail4048eb.ts.net.key \
+   CURSOR_BRIDGE_API_KEY=your-secret \
+   npm start -- --tailscale
+   ```
+
+3. **Access the API** from any device on your tailnet:
+
+   - Base URL: `https://macbook.tail4048eb.ts.net:8765/v1` (use your MagicDNS name and port)
+   - Browsers will show a padlock; no certificate warnings when using Tailscale-issued certs.
+
+## Use as SDK in another project
+
+Install the package and ensure the **Cursor agent CLI is installed and set up** (see Prerequisites). When you use the SDK with the default URL, **the proxy starts in the background automatically** if it is not already running. You can still start it yourself with `npx cursor-api-proxy` or set `CURSOR_PROXY_URL` to point at an existing proxy (then the SDK will not start another).
+
+- **Base URL**: `http://127.0.0.1:8765/v1` (override with `CURSOR_PROXY_URL` or options).
+- **API key**: Use any value (e.g. `unused`), or set `CURSOR_BRIDGE_API_KEY` and pass it in options or env.
+- **Disable auto-start**: Pass `startProxy: false` (or use a custom `baseUrl`) if you run the proxy yourself and don’t want the SDK to start it.
+- **Shutdown behavior**: When the SDK starts the proxy, it also stops it automatically when the Node.js process exits or receives normal termination signals. `stopManagedProxy()` is still available if you want to shut it down earlier. `SIGKILL` cannot be intercepted.
+
+### Option A: OpenAI SDK + helper (recommended)
+
+This is an optional consumer-side example. `openai` is not a dependency of `cursor-api-proxy`; install it only in the app where you want to use this example.
+
+```js
+import OpenAI from "openai";
+import { getOpenAIOptionsAsync } from "cursor-api-proxy";
+
+const opts = await getOpenAIOptionsAsync();  // starts proxy if needed
+const client = new OpenAI(opts);
+
+const completion = await client.chat.completions.create({
+  model: "gpt-5.2",
+  messages: [{ role: "user", content: "Hello" }],
+});
+console.log(completion.choices[0].message.content);
+```
+
+For a sync config without auto-start, use `getOpenAIOptions()` and ensure the proxy is already running.
+
+### Option B: Minimal client (no OpenAI SDK)
+
+```js
+import { createCursorProxyClient } from "cursor-api-proxy";
+
+const proxy = createCursorProxyClient();  // proxy starts on first request if needed
+const data = await proxy.chatCompletionsCreate({
+  model: "auto",
+  messages: [{ role: "user", content: "Hello" }],
+});
+console.log(data.choices?.[0]?.message?.content);
+```
+
+### Option C: Raw OpenAI client (no SDK import from this package)
+
+```js
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "http://127.0.0.1:8765/v1",
+  apiKey: process.env.CURSOR_BRIDGE_API_KEY || "unused",
+});
+// Start the proxy yourself (npx cursor-api-proxy) or use Option A/B for auto-start.
+```
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Server and config info |
+| GET | `/v1/models` | List Cursor models (from `agent --list-models`) |
+| POST | `/v1/chat/completions` | Chat completion (OpenAI shape; supports `stream: true`) |
+| POST | `/v1/messages` | Anthropic Messages API (used by Claude Code; supports `stream: true`) |
+
+## Environment variables
+
+Environment handling is centralized in one module. Aliases, defaults, path resolution, platform fallbacks, and `--tailscale` host behavior are resolved consistently before the server starts.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CURSOR_BRIDGE_HOST` | `127.0.0.1` | Bind address |
+| `CURSOR_BRIDGE_PORT` | `8765` | Port |
+| `CURSOR_BRIDGE_API_KEY` | — | If set, require `Authorization: Bearer <key>` on requests |
+| `CURSOR_BRIDGE_WORKSPACE` | process cwd | Workspace directory for Cursor CLI |
+| `CURSOR_BRIDGE_MODE` | — | Ignored; proxy always runs in **ask** (chat-only) mode so the CLI never creates or edits files. |
+| `CURSOR_BRIDGE_DEFAULT_MODEL` | `auto` | Default model when request omits one |
+| `CURSOR_BRIDGE_STRICT_MODEL` | `true` | Use last requested model when none specified |
+| `CURSOR_BRIDGE_FORCE` | `false` | Pass `--force` to Cursor CLI |
+| `CURSOR_BRIDGE_APPROVE_MCPS` | `false` | Pass `--approve-mcps` to Cursor CLI |
+| `CURSOR_BRIDGE_TIMEOUT_MS` | `300000` | Timeout per completion (ms) |
+| `CURSOR_BRIDGE_TLS_CERT` | — | Path to TLS certificate file (e.g. Tailscale cert). Use with `CURSOR_BRIDGE_TLS_KEY` for HTTPS. |
+| `CURSOR_BRIDGE_TLS_KEY` | — | Path to TLS private key file. Use with `CURSOR_BRIDGE_TLS_CERT` for HTTPS. |
+| `CURSOR_BRIDGE_SESSIONS_LOG` | `~/.cursor-api-proxy/sessions.log` | Path to log file; each request is appended as a line (timestamp, method, path, IP, status). |
+| `CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE` | `true` | When `true` (default), the CLI runs in an empty temp dir so it **cannot read or write your project**; pure chat only. Set to `false` to pass the real workspace (e.g. for `X-Cursor-Workspace`). |
+| `CURSOR_BRIDGE_VERBOSE` | `false` | When `true`, print full request messages and response content to stdout for every completion (both stream and sync). |
+| `CURSOR_BRIDGE_MAX_MODE` | `false` | When `true`, enable Cursor **Max Mode** for all requests (larger context window, higher tool-call limits). The proxy writes `maxMode: true` to `cli-config.json` before each run. Works when using `CURSOR_AGENT_NODE`/`CURSOR_AGENT_SCRIPT` or the default Windows `.cmd` layout (node.exe + index.js next to agent.cmd). |
+| `CURSOR_AGENT_BIN` | `agent` | Path to Cursor CLI binary. Alias precedence: `CURSOR_AGENT_BIN`, then `CURSOR_CLI_BIN`, then `CURSOR_CLI_PATH`. |
+| `CURSOR_AGENT_NODE` | — | **(Windows)** Path to Node.js executable. When set together with `CURSOR_AGENT_SCRIPT`, spawns Node directly instead of going through cmd.exe, bypassing the ~8191 character command line limit. |
+| `CURSOR_AGENT_SCRIPT` | — | **(Windows)** Path to the agent script (e.g. `agent.cmd` or the underlying `.js`). Use with `CURSOR_AGENT_NODE` to bypass cmd.exe for long prompts. |
+
+Notes:
+- `--tailscale` changes the default host to `0.0.0.0` only when `CURSOR_BRIDGE_HOST` is not already set.
+- Relative paths such as `CURSOR_BRIDGE_WORKSPACE`, `CURSOR_BRIDGE_SESSIONS_LOG`, `CURSOR_BRIDGE_TLS_CERT`, and `CURSOR_BRIDGE_TLS_KEY` are resolved from the current working directory.
+
+#### Windows command line limit bypass
+
+On Windows, cmd.exe has a ~8191 character limit on the command line. Long prompts passed as arguments can exceed this and cause the agent to fail. To avoid that, set both `CURSOR_AGENT_NODE` (path to `node.exe`) and `CURSOR_AGENT_SCRIPT` (path to the agent script). The proxy will then spawn Node directly with the script and args instead of using cmd.exe, avoiding the limit.
+
+Example (adjust paths to your install):
+
+```bash
+set CURSOR_AGENT_NODE=C:\Program Files\nodejs\node.exe
+set CURSOR_AGENT_SCRIPT=C:\path\to\Cursor\resources\agent\agent.cmd
+# or wherever your agent script lives
+```
+
+CLI flags:
+
+| Flag | Description |
+|------|-------------|
+| `--tailscale` | Bind to `0.0.0.0` for access from tailnet/LAN (unless `CURSOR_BRIDGE_HOST` is already set) |
+| `-h`, `--help` | Show CLI usage |
+
+Optional per-request override: send header `X-Cursor-Workspace: <path>` to use a different workspace for that request.
+
+## Streaming
+
+The proxy supports `stream: true` on `POST /v1/chat/completions` and `POST /v1/messages`. It returns Server-Sent Events (SSE) in OpenAI’s streaming format. Cursor CLI emits incremental deltas plus a final full message; the proxy deduplicates output so clients receive each chunk only once.
+
+**Test streaming:** from repo root, with the proxy running:
+
+```bash
+node examples/test-stream.mjs
+```
+
+See [examples/README.md](examples/README.md) for details.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+export declare function parseArgs(argv: string[]): {
+    tailscale: boolean;
+    help: boolean;
+};

package/dist/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import pkg from "../package.json" with { type: "json" };
+import { loadBridgeConfig } from "./lib/config.js";
+import { startBridgeServer } from "./lib/server.js";
+const __filename = fileURLToPath(import.meta.url);
+const realArgv1 = process.argv[1]
+    ? fs.realpathSync(process.argv[1])
+    : "";
+const isMainModule = realArgv1 === fs.realpathSync(__filename);
+export function parseArgs(argv) {
+    let tailscale = false;
+    let help = false;
+    for (const arg of argv) {
+        if (arg === "--tailscale") {
+            tailscale = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return { tailscale, help };
+}
+function printHelp() {
+    console.log("cursor-api-proxy");
+    console.log("");
+    console.log("Usage:");
+    console.log("  cursor-api-proxy [--tailscale]");
+    console.log("");
+    console.log("Options:");
+    console.log("  --tailscale  Bind to 0.0.0.0 for tailnet/LAN access");
+    console.log("  -h, --help   Show this help message");
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printHelp();
+        return;
+    }
+    const config = loadBridgeConfig({ tailscale: args.tailscale });
+    startBridgeServer({ version: pkg.version, config });
+}
+if (isMainModule) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,EAAE,CAAC;AACP,MAAM,YAAY,GAAG,SAAS,KAAK,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;AAE/D,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,IAAI,GAAG,KAAK,CAAC;IAEjB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YAC1B,SAAS,GAAG,IAAI,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACrC,IAAI,GAAG,IAAI,CAAC;YACZ,SAAS;QACX,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACxB,OAAO,CAAC,GAAG,CAAC,uDAAuD,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AACvD,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9C,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/D,iBAAiB,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,IAAI,YAAY,EAAE,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SDK for calling cursor-api-proxy from another project.
+ *
+ * When startProxy is true (default), the SDK will start the proxy in the
+ * background if it is not already reachable. Prerequisites: Cursor agent CLI
+ * must be installed and set up separately (see README).
+ */
+export type CursorProxyClientOptions = {
+    /** Proxy base URL (e.g. http://127.0.0.1:8765). Default: env CURSOR_PROXY_URL or http://127.0.0.1:8765 */
+    baseUrl?: string;
+    /** Optional API key; if the proxy is started with CURSOR_BRIDGE_API_KEY, pass it here. */
+    apiKey?: string;
+    /**
+     * When true (default), start the proxy in the background if it is not reachable.
+     * Only applies when using the default base URL. Set to false if you run the proxy yourself.
+     */
+    startProxy?: boolean;
+};
+/**
+ * Ensures the proxy is running at the given base URL. If the URL is the default
+ * and the proxy is not reachable, starts it in the background (Node.js only).
+ * Resolves when /health returns 200 or rejects on timeout.
+ */
+export declare function ensureProxyRunning(options?: {
+    baseUrl?: string;
+    timeoutMs?: number;
+}): Promise<string>;
+export declare function stopManagedProxy(options?: {
+    timeoutMs?: number;
+}): Promise<boolean>;
+/**
+ * Options suitable for the OpenAI SDK constructor.
+ * Use: new OpenAI(getOpenAIOptions())
+ * For auto-starting the proxy first, use getOpenAIOptionsAsync() and await it.
+ */
+export declare function getOpenAIOptions(options?: CursorProxyClientOptions): {
+    baseURL: string;
+    apiKey: string;
+};
+/**
+ * Like getOpenAIOptions but ensures the proxy is running first (starts it in the background if needed).
+ * Use: new OpenAI(await getOpenAIOptionsAsync())
+ */
+export declare function getOpenAIOptionsAsync(options?: CursorProxyClientOptions & {
+    timeoutMs?: number;
+}): Promise<{
+    baseURL: string;
+    apiKey: string;
+}>;
+/**
+ * Minimal client to call the proxy HTTP API.
+ * When startProxy is true (default), the proxy is started in the background on first request if not reachable.
+ */
+export declare function createCursorProxyClient(options?: CursorProxyClientOptions): {
+    /** Base URL of the proxy (no /v1 suffix) */
+    baseUrl: string;
+    /** Headers to send (Content-Type and optional Authorization) */
+    headers: Record<string, string>;
+    /** Get options for the OpenAI SDK constructor */
+    getOpenAIOptions: () => {
+        baseURL: string;
+        apiKey: string;
+    };
+    /**
+     * POST to a path (e.g. /v1/chat/completions). Body is JSON-serialized.
+     */
+    request<T = unknown>(path: string, body: unknown): Promise<{
+        data: T;
+        ok: boolean;
+        status: number;
+    }>;
+    /** OpenAI-style chat completions (non-streaming). */
+    chatCompletionsCreate(params: {
+        model?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        stream?: false;
+    }): Promise<{
+        choices?: Array<{
+            message?: {
+                content?: string;
+            };
+        }>;
+        error?: {
+            message?: string;
+        };
+    }>;
+    /**
+     * Use for streaming: returns a fetch Response so you can read the body stream.
+     * Ensures the proxy is running first when startProxy is true.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+};