context-doctor 0.3.5 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # context-doctor 🩺
 
+[![CI](https://github.com/KushalP1/context-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/KushalP1/context-doctor/actions) [![npm](https://img.shields.io/npm/v/context-doctor)](https://www.npmjs.com/package/context-doctor)
+
 **See what's eating your LLM context window — and fix it.**
 
 Every long-running LLM conversation slowly fills up with junk: duplicated documents, 10k-token tool outputs nobody reads again, base64 blobs, stale history. You pay for those tokens on **every single call**, and model quality drops as the window fills.
@@ -64,7 +66,7 @@ One run of `npx context-doctor install` writes five things (each config edit mak
 **In every Claude Code / Cowork session afterward:** all of the above via MCP, plus two more layers:
 
 - the **skill** loads whenever context work is relevant, and
-- the **hook runs on every single prompt you send**: it measures the session's real size in ~100ms. Under 80k tokens it stays completely silent. Above, it injects a note the model sees with your message — actual token count, cost per message, the single largest recoverable waste — with instructions to work leaner and offer you compaction. It re-fires only after ~40% further growth, and can never break a prompt (any failure exits silently).
+- the **hook runs on every single prompt you send**: lean sessions cost a ~1ms file-size check; once a session is heavy it profiles on growth events and injects a note the model sees with your message — actual token count, cost per message, the single largest recoverable waste — with instructions to work leaner and offer you compaction. It re-fires only after ~40% further growth, can never break a prompt (any failure exits silently), and logs each deep check to a small local ledger that feeds `context-doctor report`.
 
 **What it never does:** delete or rewrite your history without asking (pruning is consent-only, and the model writes the replacement summary so nothing is lost silently), send data anywhere (everything runs on your machine), or touch an API key.
 
@@ -83,6 +85,19 @@ MCP is just one of six delivery mechanisms. It's only required when you want the
 
 Practical upshot: a developer who only wants cheaper, faster API calls never touches MCP (proxy + CLI). A Claude Code user gets the hook and skill without MCP either — the MCP server just adds in-chat tools on top. `install` sets up all of it at once precisely so you don't have to think about which mechanism is which.
 
+## All commands at a glance
+
+| Command | What it does |
+|---|---|
+| `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor, the Agent Skill, the every-prompt hook |
+| `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates |
+| `context-doctor optimize <file>` | Apply the safe fixes; `--strategy prune-history` for consented lossy compaction |
+| `context-doctor session [file]` | Profile a Claude Code session transcript (defaults to your most recent; `--list` to browse) |
+| `context-doctor report` | Machine-wide impact report: exact proxy savings, hook activity, recoverable waste in recent sessions |
+| `context-doctor proxy` | Always-on local proxy that optimizes every Anthropic/OpenAI API request in flight (`/stats` for cumulative savings) |
+| `context-doctor hook` | The every-prompt Claude Code hook (registered by `install`; you never run this yourself). Warning threshold tunable via `CONTEXT_DOCTOR_WARN_TOKENS` (default 80000) |
+| `context-doctor-mcp` | The MCP server itself — stdio by default (what the installer wires); `--http [--port 8808] [--host H]` serves streamable HTTP at `/mcp` for URL-based clients like ChatGPT developer-mode connectors |
+
 ## What "always-on" means, per surface
 
 | Where you run LLMs | Mechanism | Guarantee |
@@ -163,7 +178,7 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 | Claude Desktop | `npx context-doctor install` writes the config — just restart the app |
 | Claude Code | Same command — MCP + skill + every-prompt hook, all automatic |
 | Cursor | Same command — writes `~/.cursor/mcp.json` |
-| ChatGPT desktop | **Manual, one time** (ChatGPT's connectors live inside its own settings): Settings → Connectors → Developer mode → add local server, command `npx`, args `-y context-doctor-mcp` |
+| ChatGPT (developer mode) | **Manual + a reachable URL** — ChatGPT connects to servers over the internet, never local commands. Run `context-doctor-mcp --http` on a host/tunnel, then add the URL as a connector. Normal ChatGPT (no dev mode) has no MCP — use the CLI |
 
 For any other MCP client, the server entry is:
 
@@ -185,14 +200,15 @@ For any other MCP client, the server entry is:
 3. Chat normally. When a conversation grows heavy, Claude proactively offers: *"this chat is getting large — want me to profile it?"* — or you ask *"what's eating my context?"* and it calls `profile_context` and shows the token/cost breakdown.
 4. Say *"optimize it"* and Claude applies the safe fixes; if you agree to pruning old history, **Claude itself writes the replacement summary** (that's the no-API-key summarization).
 
-### How it works in ChatGPT, step by step
+### How it works in ChatGPT, step by step (honest version)
+
+ChatGPT's MCP support differs fundamentally from Claude Desktop's: **it never spawns local processes**. Its custom connectors (developer mode) have OpenAI's servers connect to a **URL** — so the MCP server must be reachable from the internet.
 
-1. ChatGPT's desktop app supports MCP in **developer mode**: Settings → Connectors → Advanced → Developer mode, then add a local MCP server with command `npx` and args `-y context-doctor-mcp`.
-2. Enable the connector in a chat. GPT sees the same three tools with the same trigger guidance baked into their descriptions.
-3. Ask *"profile this conversation"* or paste an exported chat and ask *"what's eating my context?"* — GPT calls `profile_context` and reports the breakdown; *"optimize it"* works the same, including GPT writing the pruning summary itself.
-4. Caveat: how prominently standing server instructions surface varies by ChatGPT version — the tool descriptions carry the trigger rules regardless, so profiling still fires on the right questions.
+1. **Normal ChatGPT (no developer mode): no MCP at all.** context-doctor still helps via the CLI: export the conversation and run `npx context-doctor analyze chat.json --model gpt-5` / `optimize` — no account settings required.
+2. **ChatGPT developer mode**: run our HTTP transport somewhere reachable — `context-doctor-mcp --http --port 8808` on a small host (bind `--host 0.0.0.0` there), or expose your machine temporarily with a tunnel (`ngrok http 8808`). Then Settings → Connectors → Advanced → Developer mode → add connector with URL `https://<your-host>/mcp`.
+3. Once connected, GPT gets the same three tools with the same trigger guidance: ask *"what's eating my context?"* → it calls `profile_context`; *"optimize it"* works the same, including GPT writing the pruning summary itself.
 
-For ChatGPT on the web (no MCP): export the conversation and use the CLI — `npx context-doctor analyze chat.json --model gpt-5`.
+Security note for step 2: the HTTP endpoint is unauthenticated — put it behind your tunnel's auth or a reverse proxy if it stays up long-term.
 
 ### claude.ai on the web
 
@@ -246,6 +262,20 @@ Everything the optimizer does is inspectable: it prints exactly which messages c
 
 `skills/context-doctor/SKILL.md` (installed by `npx context-doctor install`) teaches Claude to practice context hygiene proactively: summarize big tool results after consuming them, never re-paste duplicated content, keep stable content cache-friendly, and offer compaction when a session gets heavy — so sessions get inherently leaner without you asking.
 
+## Measuring the impact: `context-doctor report`
+
+```bash
+npx context-doctor report
+```
+
+One report for your whole machine, led by a headline of **tokens context-doctor saved**, built only from measured sources:
+
+- **exact** proxy savings (real before/after on every request),
+- **exact** savings from every optimization applied via the CLI or the in-chat tools — split by model family (Claude vs GPT), with dollar estimates,
+- **observed per-session shrinkage**: real context reductions recorded between the hook's deep checks after hygiene warnings — shown per session in the table alongside remaining waste.
+
+Honest measurement note: proxy numbers are exact. Session numbers are measured-now. What no tool can report is the counterfactual — tokens Claude *avoided* adding because of the hygiene guidance — since the same session can't be re-run without it. The report says so instead of inventing a number.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:

package/dist/cli.js

@@ -18,6 +18,8 @@ import { startProxy } from "./proxy.js";
 import { runInstall, runUninstall } from "./install.js";
 import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
+import { buildImpactReport } from "./impact.js";
+import { recordLedger } from "./ledger.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -32,6 +34,8 @@ Usage:
                                                 (default: the most recent session; --list to browse)
   context-doctor hook                           Claude Code UserPromptSubmit hook (installed
                                                 automatically by \`install\`; reads hook JSON on stdin)
+  context-doctor report                         Impact report: exact proxy savings, hook activity,
+                                                and remaining recoverable waste in recent sessions
 
 Input: a conversation JSON file (OpenAI or Anthropic message format, or a bare
 message array). Use "-" to read from stdin.
@@ -119,6 +123,10 @@ function main() {
         void runHook();
         return;
     }
+    if (args.command === "report") {
+        void buildImpactReport(args.port).then((r) => console.log(r));
+        return;
+    }
     if (args.command === "session") {
         if (args.list) {
             const sessions = listSessions();
@@ -215,6 +223,9 @@ function main() {
             console.log(output);
         }
         const saved = result.tokensBefore - result.tokensAfter;
+        if (saved > 0) {
+            recordLedger({ ev: "optimize", src: "cli", saved, model: result.conversation?.model });
+        }
         const pct = result.tokensBefore > 0 ? Math.round((saved / result.tokensBefore) * 100) : 0;
         console.error(`\ncontext-doctor: ${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)} tokens ` +
             `(saved ~${formatTokens(saved)}, ${pct}%) via ${result.applied.length} change(s)` +

package/dist/hook.js

@@ -11,15 +11,14 @@
  * ~/.claude/settings.json; removed by `context-doctor uninstall`.
  */
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd } from "./pricing.js";
-/** Start nudging at 80k tokens of context. */
-const WARN_TOKENS = 80_000;
+/** Start nudging at 80k tokens of context (override: CONTEXT_DOCTOR_WARN_TOKENS). */
+const WARN_TOKENS = Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS) > 0 ? Number(process.env.CONTEXT_DOCTOR_WARN_TOKENS) : 80_000;
 /** Re-nudge only after the context grows another 40% — one reminder, not a nag. */
 const REGROWTH_FACTOR = 1.4;
 /**
@@ -29,9 +28,6 @@ const REGROWTH_FACTOR = 1.4;
  * transcript is never even read.
  */
 const MIN_BYTES_FOR_WARN = WARN_TOKENS * 4;
-function statePath() {
-    return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
-}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -77,6 +73,7 @@ export async function runHook() {
         const nextState = { t: shouldWarn ? profile.totalTokens : prev.t, b: sizeBytes };
         const entries = Object.entries({ ...state, [sessionId]: nextState });
         writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
+        recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: profile.totalTokens, warn: shouldWarn });
         if (!shouldWarn)
             return;
         const lines = [

package/dist/impact.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `context-doctor report` — one impact report for this machine.
+ *
+ * Honesty rules baked in: proxy numbers are EXACT (real before/after on every
+ * request). Session numbers are MEASURED-NOW (current size + what optimization
+ * would still recover). The behavioral counterfactual — what Claude avoided
+ * wasting because of hygiene guidance — cannot be measured by anyone: the same
+ * session cannot be re-run without it. The report says so instead of inventing
+ * a number.
+ */
+export declare function buildImpactReport(proxyPort?: number): Promise<string>;

package/dist/impact.js

@@ -0,0 +1,147 @@
+/**
+ * `context-doctor report` — one impact report for this machine.
+ *
+ * Honesty rules baked in: proxy numbers are EXACT (real before/after on every
+ * request). Session numbers are MEASURED-NOW (current size + what optimization
+ * would still recover). The behavioral counterfactual — what Claude avoided
+ * wasting because of hygiene guidance — cannot be measured by anyone: the same
+ * session cannot be re-run without it. The report says so instead of inventing
+ * a number.
+ */
+import { readLedger } from "./ledger.js";
+import { listSessions, parseSessionFile } from "./session.js";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+/** Sessions larger than this are skipped in the report (keeps it snappy). */
+const MAX_SESSION_BYTES = 30 * 1024 * 1024;
+async function fetchProxyStats(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/stats`, { signal: AbortSignal.timeout(500) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildImpactReport(proxyPort = 8787) {
+    const lines = [];
+    lines.push("CONTEXT DOCTOR — impact report");
+    lines.push("═".repeat(56));
+    const ledger = readLedger();
+    const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
+    const optimizes = ledger.filter((e) => e.ev === "optimize");
+    // Observed per-session reductions: when a session SHRANK between two deep
+    // checks (compaction/cleanup after a warning), that drop is measured fact.
+    const bySession = new Map();
+    for (const c of checks) {
+        if (!c.sid || typeof c.tok !== "number")
+            continue;
+        const s = bySession.get(c.sid) ?? { toks: [], warns: 0 };
+        s.toks.push(c.tok);
+        if (c.warn)
+            s.warns++;
+        bySession.set(c.sid, s);
+    }
+    const reductionBySession = new Map();
+    for (const [sid, s] of bySession) {
+        let reduction = 0;
+        for (let i = 1; i < s.toks.length; i++) {
+            if (s.toks[i] < s.toks[i - 1])
+                reduction += s.toks[i - 1] - s.toks[i];
+        }
+        reductionBySession.set(sid, reduction);
+    }
+    const totalReduction = [...reductionBySession.values()].reduce((a, b) => a + b, 0);
+    // Optimize-event savings, split by model family (claude / gpt / other).
+    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0);
+    const savedByFamily = new Map();
+    let optimizeUsd = 0;
+    for (const e of optimizes) {
+        const family = /claude/i.test(e.model ?? "") ? "claude" : /gpt|^o\d/i.test(e.model ?? "") ? "gpt" : "other";
+        savedByFamily.set(family, (savedByFamily.get(family) ?? 0) + (e.saved ?? 0));
+        const pricing = pricingFor(e.model);
+        if (pricing && e.saved)
+            optimizeUsd += inputCostUsd(e.saved, pricing);
+    }
+    const proxy = await fetchProxyStats(proxyPort);
+    const proxySaved = proxy?.tokensSaved ?? 0;
+    // -- Headline: what context-doctor has saved ----------------------------------
+    const totalSaved = proxySaved + optimizeSaved + totalReduction;
+    lines.push("Tokens context-doctor saved (measured)");
+    lines.push("─".repeat(56));
+    lines.push(`TOTAL: ~${formatTokens(totalSaved)} tokens`);
+    if (proxy) {
+        lines.push(`  · proxy (exact, current run): ${formatTokens(proxySaved)} across ${proxy.optimizedRequests}/${proxy.requests} requests ≈ ${formatUsd(proxy.estUsdSaved)}`);
+    }
+    else {
+        lines.push(`  · proxy: not running on :${proxyPort} (its exact savings appear here while it runs)`);
+    }
+    const familyNote = [...savedByFamily.entries()]
+        .filter(([, v]) => v > 0)
+        .map(([k, v]) => `${k}: ${formatTokens(v)}`)
+        .join(", ");
+    lines.push(`  · optimizations applied via CLI/chat tools (exact): ${formatTokens(optimizeSaved)} over ${optimizes.length} run(s)` +
+        (familyNote ? ` [${familyNote}]` : "") +
+        (optimizeUsd > 0 ? ` ≈ ${formatUsd(optimizeUsd)}` : ""));
+    lines.push(`  · observed session shrinkage after hygiene warnings: ${formatTokens(totalReduction)}`);
+    lines.push("");
+    // -- Hook activity ------------------------------------------------------------
+    lines.push("Hygiene activity (every-prompt hook)");
+    lines.push("─".repeat(56));
+    if (checks.length > 0) {
+        const warnings = checks.filter((e) => e.warn).length;
+        lines.push(`${checks.length} deep context checks across ${bySession.size} session(s); ${warnings} warning(s) delivered to the model.`);
+        lines.push("(Prompt-level fast checks are not logged — they cost ~1ms and leave no trace by design.)");
+    }
+    else {
+        lines.push("No hook activity recorded yet (ledger appears after the first deep check of a heavy session).");
+    }
+    lines.push("");
+    // -- Measured-now: recent session profiles ------------------------------------
+    lines.push("Your recent sessions — waste still recoverable today");
+    lines.push("─".repeat(56));
+    const sessions = listSessions(8).filter((s) => s.sizeBytes <= MAX_SESSION_BYTES);
+    if (sessions.length === 0) {
+        lines.push("No Claude Code session transcripts found.");
+    }
+    else {
+        let totalTokens = 0;
+        let totalWaste = 0;
+        let totalWasteUsd = 0;
+        for (const s of sessions) {
+            try {
+                const parsed = parseSessionFile(s.path);
+                if (parsed.messageCount === 0)
+                    continue;
+                const p = profileConversation(parseConversation(parsed.conversationJson), parsed.model);
+                totalTokens += p.totalTokens;
+                totalWaste += p.totalEstSavings;
+                if (p.cost)
+                    totalWasteUsd += p.cost.savingsPerCallUsd;
+                const wastePct = p.totalTokens > 0 ? Math.round((p.totalEstSavings / p.totalTokens) * 100) : 0;
+                // Ledger sids are the session UUID's first 12 chars (= filename prefix).
+                const sid = (s.path.split("/").pop() ?? "").slice(0, 12);
+                const saved = reductionBySession.get(sid) ?? 0;
+                const warns = bySession.get(sid)?.warns ?? 0;
+                lines.push(`  ${(parsed.title ?? s.path.split("/").pop() ?? "session").slice(0, 40).padEnd(42)} ` +
+                    `${formatTokens(p.totalTokens).padStart(6)} tok · waste ${String(wastePct).padStart(2)}%` +
+                    (saved > 0 ? ` · saved ${formatTokens(saved)}` : warns > 0 ? ` · ${warns} warning(s)` : ""));
+            }
+            catch {
+                /* unreadable session — skip */
+            }
+        }
+        lines.push("");
+        lines.push(`Across these sessions: ~${formatTokens(totalTokens)} tokens held; ~${formatTokens(totalWaste)} still recoverable` +
+            (totalWasteUsd > 0 ? ` (≈ ${formatUsd(totalWasteUsd)} of input per message sent in them)` : ""));
+    }
+    lines.push("");
+    lines.push("What no report can show: tokens Claude AVOIDED adding thanks to the standing");
+    lines.push("hygiene guidance — the same session cannot be re-run without it. Proxy numbers");
+    lines.push("above are exact; session numbers are what optimization would still save now.");
+    return lines.join("\n");
+}

package/dist/install.js

@@ -167,5 +167,13 @@ export function runUninstall() {
         console.log("✓ Agent Skill removed");
     }
     uninstallHook();
+    // Remove our bookkeeping files too — uninstall means gone.
+    for (const file of [".context-doctor-hook-state.json", ".context-doctor-ledger.jsonl"]) {
+        const p = join(homedir(), ".claude", file);
+        if (existsSync(p)) {
+            rmSync(p);
+            console.log(`✓ Removed ${file}`);
+        }
+    }
     console.log("Done.");
 }

package/dist/ledger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Local activity ledger: one JSONL line per notable event, feeding
+ * `context-doctor report`. Best-effort by design — a ledger failure must
+ * never break a prompt, a tool call, or an optimize run.
+ *
+ * Event shapes (all carry ts):
+ *   check    — hook deep-parsed a session   {ev?: undefined|"check", sid, tok, warn}
+ *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
+ *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
+ */
+export interface LedgerEntry {
+    ts: number;
+    ev?: "check" | "optimize";
+    sid?: string;
+    tok?: number;
+    warn?: boolean;
+    src?: "cli" | "mcp";
+    saved?: number;
+    model?: string;
+}
+export declare function statePath(): string;
+export declare function ledgerPath(): string;
+export declare function recordLedger(entry: Omit<LedgerEntry, "ts">): void;
+export declare function readLedger(): LedgerEntry[];

package/dist/ledger.js

@@ -0,0 +1,57 @@
+/**
+ * Local activity ledger: one JSONL line per notable event, feeding
+ * `context-doctor report`. Best-effort by design — a ledger failure must
+ * never break a prompt, a tool call, or an optimize run.
+ *
+ * Event shapes (all carry ts):
+ *   check    — hook deep-parsed a session   {ev?: undefined|"check", sid, tok, warn}
+ *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
+ *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function statePath() {
+    return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
+}
+export function ledgerPath() {
+    return join(dirname(statePath()), ".context-doctor-ledger.jsonl");
+}
+export function recordLedger(entry) {
+    const path = ledgerPath();
+    try {
+        // Claude-Desktop-only machines have no ~/.claude — create it so their
+        // optimize events count in `context-doctor report` too.
+        mkdirSync(dirname(path), { recursive: true });
+        // Cap growth: past ~256KB keep the most recent 500 entries.
+        if (existsSync(path) && statSync(path).size > 256 * 1024) {
+            const lines = readFileSync(path, "utf8").trimEnd().split("\n");
+            writeFileSync(path, lines.slice(-500).join("\n") + "\n");
+        }
+        appendFileSync(path, JSON.stringify({ ts: Date.now(), ...entry }) + "\n");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export function readLedger() {
+    const path = ledgerPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        return readFileSync(path, "utf8")
+            .trimEnd()
+            .split("\n")
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/mcp.js

@@ -20,6 +20,7 @@ import { profileConversation } from "./profile.js";
 import { optimizeConversation } from "./optimize.js";
 import { renderProfile } from "./report.js";
 import { formatTokens } from "./tokens.js";
+import { recordLedger } from "./ledger.js";
 /**
  * Server instructions are injected by MCP clients (Claude Desktop, Cursor, …)
  * into the system context of EVERY conversation where this server is enabled.
@@ -29,60 +30,77 @@ import { formatTokens } from "./tokens.js";
 // Kept deliberately terse: these ride in EVERY conversation's context, and a
 // context-saving tool must not itself be context overhead (~110 tokens).
 const SERVER_INSTRUCTIONS = `Context hygiene, always: summarize large pastes/tool results instead of carrying them verbatim; reference earlier content, don't re-quote; never inline base64. Past ~30 turns or several large pastes, proactively offer to run profile_context. Any question about tokens, cost, or latency: call profile_context, don't estimate. If optimize_context returns a pruned-turns digest, you write the ≤150-token replacement summary.`;
-const server = new McpServer({ name: "context-doctor", version: "0.3.5" }, { instructions: SERVER_INSTRUCTIONS });
 const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-history"];
-server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
-    conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
-    model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
-}, async ({ conversation, model }) => {
-    const profile = profileConversation(parseConversation(conversation), model);
-    return { content: [{ type: "text", text: renderProfile(profile) }] };
-});
-server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using deterministic strategies: dedupe repeated content, trim stale tool results, strip base64 blobs, optionally prune old history. Returns the slimmed conversation JSON plus a savings summary. No LLM calls — safe and inspectable. Call this after profile_context finds recoverable waste and the user wants it fixed; add the prune-history strategy only with the user's consent, then write the replacement summary yourself as the result instructs.", {
-    conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array)"),
-    strategies: z.array(z.enum(STRATEGY_IDS)).optional()
-        .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add prune-history for lossy compaction of old turns."),
-    keep_recent: z.number().int().positive().optional().describe("Messages at the tail to leave untouched (default 6)"),
-    max_tool_result_tokens: z.number().int().positive().optional().describe("Token budget for trimmed tool results (default 300)"),
-}, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
-    const result = optimizeConversation(conversation, {
-        strategies: strategies,
-        keepRecent: keep_recent,
-        maxToolResultTokens: max_tool_result_tokens,
+/**
+ * Build a fully-configured server instance. A factory (not a singleton) so the
+ * stateless HTTP mode can hand every request its own server, per the MCP SDK's
+ * recommended pattern.
+ */
+function createServer() {
+    const server = new McpServer({ name: "context-doctor", version: "0.4.0" }, { instructions: SERVER_INSTRUCTIONS });
+    server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
+        conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
+        model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
+    }, async ({ conversation, model }) => {
+        const profile = profileConversation(parseConversation(conversation), model);
+        return { content: [{ type: "text", text: renderProfile(profile) }] };
     });
-    const saved = result.tokensBefore - result.tokensAfter;
-    const summary = `Saved ~${formatTokens(saved)} tokens (${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)}) ` +
-        `via ${result.applied.length} change(s):\n` +
-        result.applied.map((c) => `- [${c.strategy}] message #${c.messageIndex}: ${c.note} (~${formatTokens(c.tokensSaved)})`).join("\n");
-    // Echoing a huge optimized conversation back inline would flood the very
-    // context this tool exists to save. Above the cap, return the summary and
-    // point at the CLI (compact JSON keeps mid-size results affordable).
-    const ECHO_CAP_CHARS = 100_000;
-    const conversationJson = JSON.stringify(result.conversation);
-    const content = [
-        { type: "text", text: summary },
-        conversationJson.length <= ECHO_CAP_CHARS
-            ? { type: "text", text: conversationJson }
-            : {
-                type: "text",
-                text: `[optimized conversation is ${conversationJson.length} chars — too large to echo into this context. ` +
-                    `Tell the user the savings above and that \`npx context-doctor optimize <file> --out slim.json\` produces the file directly.]`,
-            },
-    ];
-    // Host-model summarization: instead of calling an LLM ourselves (which would
-    // need an API key), hand the pruned material to the model that invoked this
-    // tool and ask IT to write the summary.
-    if (result.prunedDigest) {
-        content.push({
-            type: "text",
-            text: "ACTION REQUIRED (you, the assistant calling this tool): the pruned turns are digested below. " +
-                "Write a dense factual summary of them (≤150 tokens: decisions, current state, open items, key identifiers) " +
-                "and replace the '[context-doctor: ... pruned]' stub message in the conversation above with your summary " +
-                "before presenting the result.\n\nPRUNED TURNS DIGEST:\n" + result.prunedDigest,
+    server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using deterministic strategies: dedupe repeated content, trim stale tool results, strip base64 blobs, optionally prune old history. Returns the slimmed conversation JSON plus a savings summary. No LLM calls — safe and inspectable. Call this after profile_context finds recoverable waste and the user wants it fixed; add the prune-history strategy only with the user's consent, then write the replacement summary yourself as the result instructs.", {
+        conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array)"),
+        strategies: z.array(z.enum(STRATEGY_IDS)).optional()
+            .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add prune-history for lossy compaction of old turns."),
+        keep_recent: z.number().int().positive().optional().describe("Messages at the tail to leave untouched (default 6)"),
+        max_tool_result_tokens: z.number().int().positive().optional().describe("Token budget for trimmed tool results (default 300)"),
+    }, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
+        const result = optimizeConversation(conversation, {
+            strategies: strategies,
+            keepRecent: keep_recent,
+            maxToolResultTokens: max_tool_result_tokens,
         });
-    }
-    return { content };
-});
+        const saved = result.tokensBefore - result.tokensAfter;
+        if (saved > 0) {
+            recordLedger({ ev: "optimize", src: "mcp", saved, model: result.conversation?.model });
+        }
+        const summary = `Saved ~${formatTokens(saved)} tokens (${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)}) ` +
+            `via ${result.applied.length} change(s):\n` +
+            result.applied.map((c) => `- [${c.strategy}] message #${c.messageIndex}: ${c.note} (~${formatTokens(c.tokensSaved)})`).join("\n");
+        // Echoing a huge optimized conversation back inline would flood the very
+        // context this tool exists to save. Above the cap, return the summary and
+        // point at the CLI (compact JSON keeps mid-size results affordable).
+        const ECHO_CAP_CHARS = 100_000;
+        const conversationJson = JSON.stringify(result.conversation);
+        const content = [
+            { type: "text", text: summary },
+            conversationJson.length <= ECHO_CAP_CHARS
+                ? { type: "text", text: conversationJson }
+                : {
+                    type: "text",
+                    text: `[optimized conversation is ${conversationJson.length} chars — too large to echo into this context. ` +
+                        `Tell the user the savings above and that \`npx context-doctor optimize <file> --out slim.json\` produces the file directly.]`,
+                },
+        ];
+        // Host-model summarization: instead of calling an LLM ourselves (which would
+        // need an API key), hand the pruned material to the model that invoked this
+        // tool and ask IT to write the summary.
+        if (result.prunedDigest) {
+            content.push({
+                type: "text",
+                text: "ACTION REQUIRED (you, the assistant calling this tool): the pruned turns are digested below. " +
+                    "Write a dense factual summary of them (≤150 tokens: decisions, current state, open items, key identifiers) " +
+                    "and replace the '[context-doctor: ... pruned]' stub message in the conversation above with your summary " +
+                    "before presenting the result.\n\nPRUNED TURNS DIGEST:\n" + result.prunedDigest,
+            });
+        }
+        return { content };
+    });
+    server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
+        provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
+    }, async ({ provider }) => {
+        const tips = [...BEST_PRACTICES.general, ...(provider && provider !== "general" ? BEST_PRACTICES[provider] : [])];
+        return { content: [{ type: "text", text: tips.map((t, i) => `${i + 1}. ${t}`).join("\n") }] };
+    });
+    return server;
+}
 const BEST_PRACTICES = {
     general: [
         "Put stable content first (system prompt, tool definitions, reference docs) and volatile content last — prompt caches match byte-identical prefixes only.",
@@ -102,11 +120,61 @@ const BEST_PRACTICES = {
         "Use max_completion_tokens headroom math: input + output must fit the window together.",
     ],
 };
-server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
-    provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
-}, async ({ provider }) => {
-    const tips = [...BEST_PRACTICES.general, ...(provider && provider !== "general" ? BEST_PRACTICES[provider] : [])];
-    return { content: [{ type: "text", text: tips.map((t, i) => `${i + 1}. ${t}`).join("\n") }] };
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// -- Transport dispatch --------------------------------------------------------
+// Default: stdio (Claude Desktop, Claude Code, Cursor spawn us as a child).
+// --http [--port N] [--host H]: streamable-HTTP endpoint at /mcp for clients
+// that connect to a URL instead of spawning a process — ChatGPT developer-mode
+// connectors (which require a reachable URL), web MCP clients, remote setups.
+const argv = process.argv.slice(2);
+if (argv.includes("--http")) {
+    const argAfter = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const port = Number(argAfter("--port")) > 0 ? Number(argAfter("--port")) : 8808;
+    const host = argAfter("--host") ?? "127.0.0.1";
+    const { createServer: createHttpServer } = await import("node:http");
+    const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
+    createHttpServer(async (req, res) => {
+        try {
+            if (req.url === "/health") {
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({ ok: true, service: "context-doctor-mcp" }));
+                return;
+            }
+            if (!(req.url ?? "").startsWith("/mcp")) {
+                res.statusCode = 404;
+                res.end(JSON.stringify({ error: "MCP endpoint is /mcp" }));
+                return;
+            }
+            if (req.method !== "POST") {
+                // Stateless mode: no standalone SSE stream, no sessions to delete.
+                res.statusCode = 405;
+                res.setHeader("allow", "POST");
+                res.end(JSON.stringify({ error: "Stateless server: POST /mcp only" }));
+                return;
+            }
+            // Fresh server + transport per request (stateless — nothing shared).
+            const server = createServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            res.on("close", () => {
+                void transport.close();
+                void server.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        catch (e) {
+            if (!res.headersSent)
+                res.statusCode = 500;
+            res.end(JSON.stringify({ error: e.message }));
+        }
+    }).listen(port, host, () => {
+        console.error(`context-doctor MCP (streamable HTTP) on http://${host}:${port}/mcp`);
+        console.error(`ChatGPT developer-mode connectors need a URL their servers can reach — expose this via your host or a tunnel.`);
+    });
+}
+else {
+    const transport = new StdioServerTransport();
+    await createServer().connect(transport);
+}

package/dist/test/mcp-http.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP streamable-HTTP transport: spawn `mcp.js --http`, run the initialize
+ * handshake and a tool call over plain HTTP, exactly as a URL-based client
+ * (e.g. a ChatGPT developer-mode connector) would.
+ */
+export {};

package/dist/test/mcp-http.test.js

@@ -0,0 +1,63 @@
+/**
+ * MCP streamable-HTTP transport: spawn `mcp.js --http`, run the initialize
+ * handshake and a tool call over plain HTTP, exactly as a URL-based client
+ * (e.g. a ChatGPT developer-mode connector) would.
+ */
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const mcpPath = join(dirname(fileURLToPath(import.meta.url)), "..", "mcp.js");
+const PORT = 8898;
+const child = spawn(process.execPath, [mcpPath, "--http", "--port", String(PORT)], { stdio: ["ignore", "ignore", "pipe"] });
+await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("HTTP MCP server did not start")), 8000);
+    child.stderr.on("data", (d) => {
+        if (d.toString().includes("streamable HTTP")) {
+            clearTimeout(timer);
+            resolve();
+        }
+    });
+});
+after(() => child.kill());
+async function rpc(body) {
+    const res = await fetch(`http://127.0.0.1:${PORT}/mcp`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    // Streamable HTTP may answer as SSE ("data: {...}") or plain JSON.
+    const dataLine = text.split("\n").find((l) => l.startsWith("data: "));
+    return { status: res.status, json: JSON.parse(dataLine ? dataLine.slice(6) : text) };
+}
+test("initialize over HTTP returns server info + instructions", async () => {
+    const { status, json } = await rpc({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "t", version: "1" } },
+    });
+    assert.equal(status, 200);
+    assert.equal(json.result.serverInfo.name, "context-doctor");
+    assert.ok(json.result.instructions.includes("Context hygiene"));
+});
+test("tools/call works statelessly over HTTP", async () => {
+    const { json } = await rpc({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/call",
+        params: {
+            name: "profile_context",
+            arguments: { conversation: JSON.stringify({ messages: [{ role: "user", content: "hello world" }] }) },
+        },
+    });
+    assert.ok(json.result.content[0].text.includes("CONTEXT DOCTOR"));
+});
+test("health endpoint responds; non-POST is rejected", async () => {
+    const health = (await (await fetch(`http://127.0.0.1:${PORT}/health`)).json());
+    assert.equal(health.ok, true);
+    const get = await fetch(`http://127.0.0.1:${PORT}/mcp`);
+    assert.equal(get.status, 405);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude, GPT, Gemini, and any MCP-capable AI app.",
   "keywords": [
     "llm",
@@ -38,10 +38,10 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm run build",
     "dev": "tsc --watch",
-    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/hook.test.js"
+    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/hook.test.js dist/test/mcp-http.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",