context-doctor 0.17.0 → 0.18.0

package/README.md

@@ -179,7 +179,20 @@ The proxy dedupes repeated content, trims stale tool results, and strips base64
 
 Because prompt caching matches byte-identical prefixes, deterministic strategies are chosen so repeated requests stay stable — but if you rely on aggressive cache prefixes, start with `--strategy strip-base64 --strategy dedupe` and add more as you verify.
 
-> **Note on desktop chat apps:** Claude Desktop and the ChatGPT app talk to their own backends — no tool can sit in that path. For those, use the MCP integration below and add a line to your custom instructions like: *"When a conversation gets long or includes large pasted content, proactively use context-doctor's profile_context tool and tell me what to trim."* The model will then invoke it on its own.
+### Putting the proxy on a public URL (Cursor with your own OpenAI key, remote apps)
+
+Some apps let you set a base URL but call it from *their* servers, not your machine. Cursor is one: with your own OpenAI key, "Override OpenAI Base URL" is sent to Cursor's backend inside the model configuration, and Cursor's servers make the request (only the key-verification ping is client-side; we checked the app bundle, 3.18.25). So `127.0.0.1` cannot work there; the proxy has to be reachable from the internet, and an open relay on the internet is a bad idea. Hence the token:
+
+```bash
+npx context-doctor proxy --token "$(openssl rand -hex 16)"   # or CONTEXT_DOCTOR_PROXY_TOKEN=...
+ngrok http 8787                                               # or any HTTPS tunnel / reverse proxy
+```
+
+With `--token`, every path except `/health` must start with `/t/<token>/`; anything else gets 401 before any upstream call, and the comparison is constant time. Then in Cursor: Settings > Models > OpenAI API Key > Override OpenAI Base URL = `https://<your-host>/t/<token>/v1`. Every agent request Cursor makes with your key now passes through the proxy: deduped, stale tool results trimmed, base64 stripped, real usage counted in `/t/<token>/stats`. This is the one Cursor path that is model-independent and needs no hook. It applies only to BYO-key traffic; Cursor's own subscription models never leave Cursor's servers.
+
+Your API key still rides in the request headers, as before. The token protects the relay, not the key; keep the tunnel HTTPS.
+
+> **Note on desktop chat apps:** Claude Desktop and the ChatGPT app talk to their own backends — no tool can sit in that path. For those, use the MCP integration below (Claude Desktop gets the standing rules and a cheap `profile_context` sketch call) and `context-doctor instructions --copy` for the per-account preferences.
 
 ## Use with the Claude & ChatGPT apps
 

package/dist/cli.js

@@ -110,6 +110,9 @@ Options:
                           overwrites a statusLine you already have)
   --port <n>              (proxy) Port to listen on (default 8787)
   --host <addr>           (proxy) Bind address (default 127.0.0.1; use 0.0.0.0 to expose)
+  --token <secret>        (proxy) Require /t/<secret>/ in every request path; needed before
+                          putting the proxy on a public URL (Cursor BYO-key, tunnels).
+                          Also read from CONTEXT_DOCTOR_PROXY_TOKEN
   --config <file>         (proxy) Per-route overrides: {"routes":[{"modelPrefix":"gpt","strategies":[...],
                           "keepRecent":n,"maxToolResultTokens":n}]} — first prefix match wins
   --upstream-anthropic <url>  (proxy) Override Anthropic upstream (testing)
@@ -199,6 +202,9 @@ function parseArgs(argv) {
             case "--host":
                 args.host = argv[++i];
                 break;
+            case "--token":
+                args.token = argv[++i];
+                break;
             case "--config":
                 args.config = argv[++i];
                 break;
@@ -461,6 +467,7 @@ function main() {
             routes: routes,
             port: args.port,
             host: args.host,
+            token: args.token ?? process.env.CONTEXT_DOCTOR_PROXY_TOKEN,
             anthropicUpstream: args.upstreamAnthropic,
             openaiUpstream: args.upstreamOpenai,
             strategies: args.strategies.length > 0 ? args.strategies : loadedRc.config.strategies,

package/dist/mcp.js

@@ -49,7 +49,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.17.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.18.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~100 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/proxy.d.ts

@@ -23,9 +23,24 @@ export interface ProxyOptions extends OptimizeOptions {
      * the user explicitly opts in (e.g. --host 0.0.0.0 inside a container).
      */
     host?: string;
+    /**
+     * When set, every request except /health must arrive under the path prefix
+     * `/t/<token>/`, which is stripped before routing. This is what makes the
+     * proxy safe to put on a public URL (a tunnel) for apps whose servers call
+     * the base URL, such as Cursor with your own OpenAI key: those apps can set a
+     * URL but not a header, so the secret rides in the path. Compared with
+     * constant time; a wrong or missing prefix gets 401 and no upstream call.
+     */
+    token?: string;
     anthropicUpstream?: string;
     openaiUpstream?: string;
 }
+/**
+ * Remove a leading `/t/<token>` from a request path, or return undefined when
+ * the prefix is absent or the token differs. The comparison is constant time
+ * so the token cannot be guessed a character at a time.
+ */
+export declare function stripToken(url: string, token: string): string | undefined;
 export interface ProxyStats {
     startedAt: string;
     requests: number;

package/dist/proxy.js

@@ -12,6 +12,7 @@
  * Streaming responses are piped through unchanged.
  */
 import http from "node:http";
+import { timingSafeEqual } from "node:crypto";
 import { optimizeConversation } from "./optimize.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
@@ -19,6 +20,23 @@ import { recordLedger } from "./ledger.js";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);
+/**
+ * Remove a leading `/t/<token>` from a request path, or return undefined when
+ * the prefix is absent or the token differs. The comparison is constant time
+ * so the token cannot be guessed a character at a time.
+ */
+export function stripToken(url, token) {
+    const prefix = "/t/";
+    if (!url.startsWith(prefix))
+        return undefined;
+    const end = url.indexOf("/", prefix.length);
+    const candidate = end === -1 ? url.slice(prefix.length) : url.slice(prefix.length, end);
+    const a = Buffer.from(candidate), b = Buffer.from(token);
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return undefined;
+    const rest = end === -1 ? "/" : url.slice(end);
+    return rest;
+}
 function upstreamFor(url, opts) {
     if (url.startsWith("/v1/messages"))
         return opts.anthropicUpstream ?? "https://api.anthropic.com";
@@ -75,13 +93,23 @@ export function startProxy(opts = {}) {
         console.error(`[context-doctor] cache advisor: ${msg}`);
     };
     const server = http.createServer(async (req, res) => {
-        const url = req.url ?? "/";
+        let url = req.url ?? "/";
         try {
             if (url === "/health") {
                 res.setHeader("content-type", "application/json");
                 res.end(JSON.stringify({ ok: true, service: "context-doctor-proxy" }));
                 return;
             }
+            if (opts.token) {
+                const stripped = stripToken(url, opts.token);
+                if (stripped === undefined) {
+                    res.statusCode = 401;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ error: "context-doctor proxy: this proxy requires its token in the path: /t/<token>/v1/..." }));
+                    return;
+                }
+                url = stripped;
+            }
             if (url === "/stats") {
                 res.setHeader("content-type", "application/json");
                 res.end(JSON.stringify({ ...stats, estUsdSaved: Number(stats.estUsdSaved.toFixed(4)) }, null, 2));
@@ -278,11 +306,18 @@ export function startProxy(opts = {}) {
     server.on("close", checkpoint);
     const host = opts.host ?? "127.0.0.1";
     server.listen(port, host, () => {
+        // Print the token as <token>, never the value: this log is what people paste into bug reports.
+        const prefix = opts.token ? "/t/<token>" : "";
         console.error(`context-doctor proxy listening on http://${host}:${port}`);
-        console.error(`  Anthropic apps/SDKs: export ANTHROPIC_BASE_URL=http://localhost:${port}`);
-        console.error(`  OpenAI apps/SDKs:    export OPENAI_BASE_URL=http://localhost:${port}/v1`);
+        console.error(`  Anthropic apps/SDKs: export ANTHROPIC_BASE_URL=http://localhost:${port}${prefix}`);
+        console.error(`  OpenAI apps/SDKs:    export OPENAI_BASE_URL=http://localhost:${port}${prefix}/v1`);
         console.error(`  Every request's context is optimized in flight; savings are logged here.`);
-        console.error(`  Cumulative savings: http://localhost:${port}/stats`);
+        console.error(`  Cumulative savings: http://localhost:${port}${prefix}/stats`);
+        if (opts.token) {
+            console.error(`  Token required: every path except /health must start with /t/<token>/.`);
+            console.error(`  Cursor with your own OpenAI key: expose this port on HTTPS (a tunnel), then Settings > Models > OpenAI API Key >`);
+            console.error(`  "Override OpenAI Base URL" = https://<your-host>/t/<token>/v1. Cursor's servers call that URL, so 127.0.0.1 will not work there.`);
+        }
     });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude Code, Claude Desktop, Cursor, Codex (OpenAI), and any MCP-capable AI app.",
   "keywords": [
     "claude",