context-doctor 0.3.0 → 0.3.1

package/README.md

@@ -111,7 +111,7 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 > **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.
 
-## Use it inside your AI app (MCP)
+## Use with the Claude & ChatGPT apps
 
 `context-doctor` ships an MCP server, so the AI itself can profile and slim context on demand.
 
@@ -130,7 +130,25 @@ Because prompt caching matches byte-identical prefixes, deterministic strategies
 
 **ChatGPT desktop** (developer mode), **Cursor**, **Claude Code** (`claude mcp add context-doctor -- npx -y context-doctor-mcp`), and any other MCP client: same command, their config syntax.
 
-Then just ask: *"profile this conversation with context-doctor"* or paste an exported chat and say *"what's eating my context?"*
+### How it works in Claude Desktop, step by step
+
+1. Run `npx context-doctor install` (writes the config above for you) and restart Claude Desktop.
+2. From then on, **every conversation automatically carries context-doctor's standing instructions** — the MCP server hands Claude hygiene rules on connect: summarize big pastes instead of re-quoting them, offer profiling when the chat gets long, never inline base64.
+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
+
+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.
+
+For ChatGPT on the web (no MCP): export the conversation and use the CLI — `npx context-doctor analyze chat.json --model gpt-5`.
+
+### claude.ai on the web
+
+Your local MCP server can't reach the website, but the behavior can: upload `skills/context-doctor/SKILL.md` under Settings → Capabilities → Skills, and web conversations gain the same standing context-hygiene habits (summarize-don't-requote, offer compaction when heavy).
 
 ### MCP tools
 
@@ -195,6 +213,19 @@ Exact counts require each provider's private tokenizer. `context-doctor` uses a
 
 Contributions welcome — this project is small on purpose. Open an issue before a big PR.
 
+## Releasing (maintainers)
+
+```bash
+npm version patch        # or minor/major — bumps package.json + git tag
+npm test                 # 14 tests must pass; CI runs the same on 3 OSes
+npm publish              # prompts for the npm 2FA code
+git push --follow-tags
+```
+
+Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doctor`** on a package that clearly exists, the real cause is an **expired npm login token** — npm reports unauthenticated publishes as a 404, not a 401. Check with `npm whoami`; if that errors, run `npm login` and publish again.
+
+Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.
+
 ## License
 
 MIT

package/dist/mcp.js

@@ -31,7 +31,7 @@ const SERVER_INSTRUCTIONS = `context-doctor keeps this conversation's context wi
 2. When the conversation has grown long (roughly 30+ turns) or contains several large pastes, proactively offer to profile it and call profile_context — do not wait to be asked.
 3. When the user asks anything about token usage, cost, latency, or "what's eating my context", call profile_context immediately rather than estimating by eye.
 4. When optimize_context returns a pruned-turns digest, YOU write the replacement summary (dense, factual, ≤150 tokens) as instructed in the result.`;
-const server = new McpServer({ name: "context-doctor", version: "0.3.0" }, { instructions: SERVER_INSTRUCTIONS });
+const server = new McpServer({ name: "context-doctor", version: "0.3.1" }, { 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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",