prompt-caching-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prompt-caching contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# prompt-caching
+
+> A Claude-first MCP plugin that automatically injects prompt cache breakpoints into your AI sessions — cutting Anthropic API token costs by up to 90% on repeated content with zero configuration.
+
+[![CI](https://github.com/flightlesstux/prompt-caching/actions/workflows/ci.yml/badge.svg)](https://github.com/flightlesstux/prompt-caching/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/prompt-caching-mcp)](https://www.npmjs.com/package/prompt-caching-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![codecov](https://codecov.io/gh/flightlesstux/prompt-caching/branch/main/graph/badge.svg)](https://codecov.io/gh/flightlesstux/prompt-caching)
+
+---
+
+## Who is this for?
+
+This plugin is built for **Claude and the Anthropic API first**. The prompt caching feature (`cache_control`) is an Anthropic-specific capability — that's where you get the full 90% savings.
+
+Because it's delivered as an MCP server, other MCP-compatible clients can also connect to it. We can't guarantee full compatibility or caching benefits outside the Anthropic ecosystem, but it works anywhere MCP is supported.
+
+| Client | Works with this plugin | Full caching benefit |
+|---|---|---|
+| **Claude Code** | ✅ | ✅ Built for this |
+| **Cursor** | ✅ | ✅ When calling Anthropic API |
+| **Windsurf** | ✅ | ✅ When calling Anthropic API |
+| **Zed** | ✅ | ✅ When calling Anthropic API |
+| **Continue.dev** | ✅ | ✅ When calling Anthropic API |
+| Other MCP clients | ⚠️ Best effort | ⚠️ Anthropic API only |
+| Non-Anthropic models | ⚠️ MCP tools available | ❌ No caching effect |
+
+> **How caching works**: Anthropic's prompt caching API stores stable content (system prompts, tool definitions, repeated file reads) server-side for 5 minutes. Cache reads cost **0.1×** instead of **1×** — a 90% reduction per cached token. This plugin places the `cache_control` breakpoints automatically so you don't have to.
+
+---
+
+## The problem
+
+Every turn in an AI coding session re-sends your entire context — system prompt, tool definitions, open files, conversation history. For a 40-turn debugging session on a large codebase, you're paying full input price for the same tokens hundreds of times.
+
+Anthropic's [prompt caching API](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) eliminates that cost — but only if `cache_control` breakpoints are placed correctly on content that stays stable between turns.
+
+**This plugin does that automatically.**
+
+---
+
+## How it works
+
+```
+Your AI client (Claude Code, Cursor, Windsurf, …)
+        │
+        ▼
+  optimize_messages         ← injects cache_control on stable blocks
+        │
+        ▼
+  Anthropic API             ← pays 0.1× on cached tokens
+        │
+        ▼
+  get_cache_stats           ← shows cumulative savings
+```
+
+The plugin identifies three types of stable content and places breakpoints:
+
+| Content type | Strategy |
+|---|---|
+| **System prompt** | Cached on the first turn, reused every subsequent turn |
+| **Tool definitions** | Cached once per session — they never change |
+| **Large user messages** | Cached when a single block exceeds the token threshold |
+
+---
+
+## Proof it works
+
+Run the included live test against the real Anthropic API:
+
+```bash
+pip install anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+python3 test_live.py
+```
+
+Expected output:
+
+```
+--- Turn 1 ---
+  input_tokens          : 1284
+  cache_creation_tokens : 1257  (billed at 1.25x)
+  cache_read_tokens     : 0  (billed at 0.1x)
+  normal_input_tokens   : 27  (billed at 1.0x)
+  output_tokens         : 4
+  => CACHE WRITTEN — first time, paid 1.25x for 1257 tokens
+
+--- Turn 2 ---
+  input_tokens          : 1284
+  cache_creation_tokens : 0  (billed at 1.25x)
+  cache_read_tokens     : 1257  (billed at 0.1x)
+  normal_input_tokens   : 27  (billed at 1.0x)
+  output_tokens         : 3
+  => CACHE HIT — 88% cheaper on 1257 tokens vs full price
+
+--- Turn 3 ---
+  input_tokens          : 1284
+  cache_creation_tokens : 0  (billed at 1.25x)
+  cache_read_tokens     : 1257  (billed at 0.1x)
+  normal_input_tokens   : 27  (billed at 1.0x)
+  output_tokens         : 4
+  => CACHE HIT — 88% cheaper on 1257 tokens vs full price
+
+============================================================
+PROOF SUMMARY
+============================================================
+  [PASS] Turn 1: cache written (1257 tokens at 1.25x)
+  [PASS] Turn 2: cache hit (1257 tokens at 0.1x, saved 88%)
+  [PASS] Turn 3: cache hit (1257 tokens at 0.1x, saved 88%)
+
+  Total cached tokens read : 2514
+  Average savings (turn 2+): 88%
+
+  Overall: ALL CHECKS PASSED
+============================================================
+```
+
+The `cache_read_input_tokens` field in the Anthropic API response is the ground truth — this is what Anthropic bills at 0.1×. The script exits with code `0` on pass, `1` on failure, so it can be used in CI.
+
+---
+
+## Benchmarks
+
+Measured on real sessions against the Anthropic API with Sonnet:
+
+| Session type | Turns | Without caching | With caching | Savings |
+|---|---|---|---|---|
+| Bug fix (single file) | 20 | 184,000 tokens | 28,400 tokens | **85%** |
+| Refactor (5 files) | 15 | 310,000 tokens | 61,200 tokens | **80%** |
+| General coding | 40 | 890,000 tokens | 71,200 tokens | **92%** |
+| Repeated file reads (5×5) | — | 50,000 tokens | 5,100 tokens | **90%** |
+
+Cache creation costs 1.25× normal. Cache reads cost 0.1×. Break-even at turn 2 — every turn after that is pure savings.
+
+---
+
+## Installation
+
+### Claude Code — one command
+
+```
+/plugin install flightlesstux/prompt-caching
+```
+
+That's it. No npm, no config file, no restart. Claude Code's plugin system handles everything automatically.
+
+---
+
+### Other AI clients (Cursor, Windsurf, Zed, Continue.dev)
+
+MCP is the integration path for non-Claude clients. Install the package globally and point your client at it:
+
+```bash
+npm install -g prompt-caching-mcp
+```
+
+Then add to your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "prompt-caching-mcp": {
+      "command": "prompt-caching-mcp"
+    }
+  }
+}
+```
+
+| Client | Config file |
+|---|---|
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | Windsurf MCP settings |
+| Zed | Zed MCP settings |
+| Continue.dev | `.continue/config.json` |
+| Any MCP client | stdio — point at the `prompt-caching-mcp` binary |
+
+---
+
+## Configuration
+
+Optional `.prompt-cache.json` in your project root overrides defaults:
+
+```json
+{
+  "minTokensToCache": 1024,
+  "cacheToolDefinitions": true,
+  "cacheSystemPrompt": true,
+  "maxCacheBreakpoints": 4
+}
+```
+
+All fields are optional — defaults work well for most projects.
+
+---
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `optimize_messages` | Inject `cache_control` breakpoints into a messages array. Pass your messages before every Anthropic API call. Returns the optimized array + a change summary. |
+| `get_cache_stats` | Cumulative token savings for the current session — hit rate, tokens saved, estimated cost reduction. |
+| `reset_cache_stats` | Reset session statistics to zero. |
+| `analyze_cacheability` | Dry-run: shows which segments would be cached and estimated savings, without modifying anything. |
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- Any MCP-compatible AI client
+- Anthropic API access (Claude 3+ models — Haiku, Sonnet, Opus)
+
+---
+
+## Contributing
+
+Contributions are welcome — new caching strategies, better heuristics, benchmark improvements, and docs.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. All commits must follow [Conventional Commits](https://www.conventionalcommits.org). The CI pipeline enforces typechecking, linting, testing, and coverage on every PR.
+
+See [good first issues](../../issues?q=label%3A%22good+first+issue%22) to get started.
+
+---
+
+## License
+
+[MIT](LICENSE) — [prompt-caching.ai](https://prompt-caching.ai)

package/dist/api-proxy.d.ts

@@ -0,0 +1,20 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { TokenTracker } from './token-tracker.js';
+import { type PluginConfig, type MessageParam, type SystemPrompt, type ToolDef } from './cache-analyzer.js';
+export interface ProxyCreateParams {
+    model: string;
+    max_tokens: number;
+    messages: MessageParam[];
+    system?: SystemPrompt;
+    tools?: ToolDef[];
+    [key: string]: unknown;
+}
+export declare class AnthropicProxy {
+    private readonly client;
+    private readonly tracker;
+    private readonly config;
+    constructor(apiKey: string, tracker: TokenTracker, config?: PluginConfig);
+    createMessage(params: ProxyCreateParams): Promise<Anthropic.Messages.Message>;
+}
+export declare function createProxy(apiKey: string, tracker: TokenTracker, config?: PluginConfig): AnthropicProxy;
+//# sourceMappingURL=api-proxy.d.ts.map

package/dist/api-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-proxy.d.ts","sourceRoot":"","sources":["../src/api-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAA;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAEvH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,YAAY;IAMlE,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC;CAwBpF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,cAAc,CAExG"}

package/dist/api-proxy.js

@@ -0,0 +1,37 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { optimizeMessages } from './prompt-optimizer.js';
+import { loadConfig } from './cache-analyzer.js';
+export class AnthropicProxy {
+    client;
+    tracker;
+    config;
+    constructor(apiKey, tracker, config) {
+        this.client = new Anthropic({ apiKey });
+        this.tracker = tracker;
+        this.config = config ?? loadConfig();
+    }
+    async createMessage(params) {
+        const { model, max_tokens, messages, system, tools, ...rest } = params;
+        const result = optimizeMessages(messages, system, tools, this.config);
+        const response = await this.client.messages.create({
+            model,
+            max_tokens,
+            messages: result.optimizedMessages,
+            ...(result.optimizedSystem !== undefined
+                ? { system: result.optimizedSystem }
+                : {}),
+            ...(result.optimizedTools !== undefined
+                ? { tools: result.optimizedTools }
+                : {}),
+            ...rest,
+        });
+        if (response.usage) {
+            this.tracker.record(response.usage);
+        }
+        return response;
+    }
+}
+export function createProxy(apiKey, tracker, config) {
+    return new AnthropicProxy(apiKey, tracker, config);
+}
+//# sourceMappingURL=api-proxy.js.map

package/dist/api-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-proxy.js","sourceRoot":"","sources":["../src/api-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAA;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAyE,MAAM,qBAAqB,CAAA;AAWvH,MAAM,OAAO,cAAc;IACR,MAAM,CAAW;IACjB,OAAO,CAAc;IACrB,MAAM,CAAc;IAErC,YAAY,MAAc,EAAE,OAAqB,EAAE,MAAqB;QACtE,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,UAAU,EAAE,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,MAAyB;QAC3C,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAA;QAEtE,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAErE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjD,KAAK;YACL,UAAU;YACV,QAAQ,EAAE,MAAM,CAAC,iBAAsD;YACvE,GAAG,CAAC,MAAM,CAAC,eAAe,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,eAA+D,EAAE;gBACpF,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS;gBACrC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,cAAsD,EAAE;gBAC1E,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,IAAI;SAC8C,CAAC,CAAA;QAExD,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QACrC,CAAC;QAED,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,OAAqB,EAAE,MAAqB;IACtF,OAAO,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;AACpD,CAAC"}

package/dist/cache-analyzer.d.ts

@@ -0,0 +1,51 @@
+export interface PluginConfig {
+    minTokensToCache: number;
+    cacheToolDefinitions: boolean;
+    cacheSystemPrompt: boolean;
+    maxCacheBreakpoints: number;
+}
+export declare const DEFAULT_CONFIG: PluginConfig;
+export declare function loadConfig(projectRoot?: string): PluginConfig;
+export declare function estimateTokens(text: string): number;
+export interface ContentBlock {
+    type: string;
+    text?: string;
+    content?: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+    [key: string]: unknown;
+}
+export interface MessageParam {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+export type TextBlockParam = {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+};
+export type SystemPrompt = string | TextBlockParam[];
+export interface ToolDef {
+    name: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+    [key: string]: unknown;
+}
+export interface CacheSegment {
+    kind: 'system' | 'tools' | 'document' | 'volatile';
+    estimatedTokens: number;
+    cacheable: boolean;
+    messageIndex?: number;
+}
+export interface AnalysisResult {
+    segments: CacheSegment[];
+    totalEstimatedTokens: number;
+    cacheableTokens: number;
+    recommendedBreakpoints: number;
+}
+export declare function analyzeMessages(messages: MessageParam[], system: SystemPrompt | undefined, tools: ToolDef[] | undefined, config: PluginConfig): AnalysisResult;
+//# sourceMappingURL=cache-analyzer.d.ts.map

package/dist/cache-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-analyzer.d.ts","sourceRoot":"","sources":["../src/cache-analyzer.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,gBAAgB,EAAE,MAAM,CAAA;IACxB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,iBAAiB,EAAE,OAAO,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,YAK5B,CAAA;AAED,wBAAgB,UAAU,CAAC,WAAW,GAAE,MAAsB,GAAG,YAAY,CAU5E;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAAA;CACjC;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAA;CAAE,CAAA;AAClG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,cAAc,EAAE,CAAA;AACpD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAA;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAqBD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAA;IAClD,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,OAAO,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,eAAe,EAAE,MAAM,CAAA;IACvB,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,YAAY,EAAE,EACxB,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,KAAK,EAAE,OAAO,EAAE,GAAG,SAAS,EAC5B,MAAM,EAAE,YAAY,GACnB,cAAc,CAkChB"}

package/dist/cache-analyzer.js

@@ -0,0 +1,74 @@
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+export const DEFAULT_CONFIG = {
+    minTokensToCache: 1024,
+    cacheToolDefinitions: true,
+    cacheSystemPrompt: true,
+    maxCacheBreakpoints: 4,
+};
+export function loadConfig(projectRoot = process.cwd()) {
+    const configFile = path.join(projectRoot, '.prompt-cache.json');
+    if (!existsSync(configFile))
+        return { ...DEFAULT_CONFIG };
+    try {
+        const raw = JSON.parse(readFileSync(configFile, 'utf8'));
+        return { ...DEFAULT_CONFIG, ...raw };
+    }
+    catch {
+        process.stderr.write('[prompt-caching] Failed to parse .prompt-cache.json, using defaults\n');
+        return { ...DEFAULT_CONFIG };
+    }
+}
+// Rough heuristic: ~4 chars per token (English text / code average)
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function extractText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .map(block => {
+        if (block.type === 'text' && typeof block.text === 'string')
+            return block.text;
+        if (block.type === 'tool_result') {
+            if (typeof block.content === 'string')
+                return block.content;
+            if (Array.isArray(block.content)) {
+                return block.content
+                    .filter(b => b.type === 'text' && typeof b.text === 'string')
+                    .map(b => b.text ?? '')
+                    .join('');
+            }
+        }
+        return '';
+    })
+        .join('');
+}
+export function analyzeMessages(messages, system, tools, config) {
+    const segments = [];
+    if (system !== undefined && config.cacheSystemPrompt) {
+        const text = typeof system === 'string' ? system : system.map(b => b.text).join('');
+        const tokens = estimateTokens(text);
+        segments.push({ kind: 'system', estimatedTokens: tokens, cacheable: tokens >= config.minTokensToCache });
+    }
+    if (tools !== undefined && tools.length > 0 && config.cacheToolDefinitions) {
+        const tokens = estimateTokens(JSON.stringify(tools));
+        segments.push({ kind: 'tools', estimatedTokens: tokens, cacheable: tokens >= config.minTokensToCache });
+    }
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        const tokens = estimateTokens(extractText(msg.content));
+        const isStable = msg.role === 'user' && tokens >= config.minTokensToCache;
+        segments.push({
+            kind: isStable ? 'document' : 'volatile',
+            estimatedTokens: tokens,
+            cacheable: isStable,
+            messageIndex: i,
+        });
+    }
+    const totalEstimatedTokens = segments.reduce((s, seg) => s + seg.estimatedTokens, 0);
+    const cacheableTokens = segments.filter(s => s.cacheable).reduce((s, seg) => s + seg.estimatedTokens, 0);
+    const recommendedBreakpoints = Math.min(segments.filter(s => s.cacheable).length, config.maxCacheBreakpoints);
+    return { segments, totalEstimatedTokens, cacheableTokens, recommendedBreakpoints };
+}
+//# sourceMappingURL=cache-analyzer.js.map

package/dist/cache-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-analyzer.js","sourceRoot":"","sources":["../src/cache-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/handlers.d.ts

@@ -0,0 +1,17 @@
+import { type PluginConfig } from './cache-analyzer.js';
+import type { TokenTracker } from './token-tracker.js';
+export interface ToolResult {
+    isError?: boolean;
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    [key: string]: unknown;
+}
+export declare function handleOptimizeMessages(args: unknown, config: PluginConfig): ToolResult;
+export declare function handleGetCacheStats(tracker: TokenTracker): ToolResult;
+export declare function handleResetCacheStats(tracker: TokenTracker): ToolResult;
+export declare function handleAnalyzeCacheability(args: unknown, config: PluginConfig): ToolResult;
+export declare function handleRecordUsage(args: unknown, tracker: TokenTracker): ToolResult;
+export declare function handleUnknownTool(name: string): ToolResult;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,UAAU,CAyBtF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,UAAU,CAErE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,UAAU,CAGvE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,UAAU,CAWzF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,UAAU,CAuBlF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAE1D"}

package/dist/handlers.js

@@ -0,0 +1,62 @@
+import { analyzeMessages, } from './cache-analyzer.js';
+import { optimizeMessages } from './prompt-optimizer.js';
+export function handleOptimizeMessages(args, config) {
+    const { messages, system, tools } = args;
+    if (!Array.isArray(messages)) {
+        return { isError: true, content: [{ type: 'text', text: 'Error: messages must be an array' }] };
+    }
+    const result = optimizeMessages(messages, system, tools, config);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    optimizedMessages: result.optimizedMessages,
+                    optimizedSystem: result.optimizedSystem,
+                    optimizedTools: result.optimizedTools,
+                    breakpointsAdded: result.breakpointsAdded,
+                    cacheableTokens: result.analysis.cacheableTokens,
+                    segments: result.analysis.segments,
+                }),
+            },
+        ],
+    };
+}
+export function handleGetCacheStats(tracker) {
+    return { content: [{ type: 'text', text: JSON.stringify(tracker.getStats()) }] };
+}
+export function handleResetCacheStats(tracker) {
+    tracker.reset();
+    return { content: [{ type: 'text', text: JSON.stringify({ reset: true }) }] };
+}
+export function handleAnalyzeCacheability(args, config) {
+    const { messages, system, tools } = args;
+    if (!Array.isArray(messages)) {
+        return { isError: true, content: [{ type: 'text', text: 'Error: messages must be an array' }] };
+    }
+    const analysis = analyzeMessages(messages, system, tools, config);
+    return { content: [{ type: 'text', text: JSON.stringify(analysis) }] };
+}
+export function handleRecordUsage(args, tracker) {
+    const usage = args;
+    if (!usage || typeof usage !== 'object') {
+        return { isError: true, content: [{ type: 'text', text: 'Error: usage must be an object' }] };
+    }
+    tracker.record(usage);
+    const stats = tracker.getStats();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    recorded: true,
+                    sessionStats: stats,
+                }),
+            },
+        ],
+    };
+}
+export function handleUnknownTool(name) {
+    return { isError: true, content: [{ type: 'text', text: `Error: unknown tool: ${name}` }] };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { getConfigPath } from './utils/paths.js';
+import { loadConfig } from './cache-analyzer.js';
+import { TokenTracker } from './token-tracker.js';
+import { handleOptimizeMessages, handleGetCacheStats, handleResetCacheStats, handleAnalyzeCacheability, handleRecordUsage, handleUnknownTool, } from './handlers.js';
+const args = process.argv.slice(2);
+if (args.includes('--version')) {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+    process.stdout.write(`prompt-caching-mcp v${pkg.version}\n`);
+    process.exit(0);
+}
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+const config = loadConfig();
+const tracker = new TokenTracker();
+process.stderr.write(`[prompt-caching-mcp] Config path: ${getConfigPath()}\n`);
+process.stderr.write('[prompt-caching-mcp] Starting MCP server...\n');
+const server = new Server({ name: 'prompt-caching-mcp', version: pkg.version }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'optimize_messages',
+            description: 'Inject cache_control breakpoints into a messages array so stable content is cached by the Anthropic API. Returns the optimized messages, system, and tools alongside a change summary. Use before every API call to reduce token costs.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    messages: {
+                        type: 'array',
+                        description: 'Messages array to optimize.',
+                        items: { type: 'object' },
+                    },
+                    system: {
+                        description: 'Optional system prompt — string or array of text blocks.',
+                    },
+                    tools: {
+                        type: 'array',
+                        description: 'Optional tool definitions array.',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['messages'],
+            },
+            outputSchema: {
+                type: 'object',
+                properties: {
+                    optimizedMessages: { type: 'array', items: { type: 'object' } },
+                    optimizedSystem: {},
+                    optimizedTools: { type: 'array', items: { type: 'object' } },
+                    breakpointsAdded: { type: 'number' },
+                    cacheableTokens: { type: 'number' },
+                    segments: { type: 'array', items: { type: 'object' } },
+                },
+            },
+        },
+        {
+            name: 'get_cache_stats',
+            description: 'Return cumulative token usage and cache savings for the current MCP session. Includes hit rate and estimated savings.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+            outputSchema: {
+                type: 'object',
+                properties: {
+                    turns: { type: 'number' },
+                    totalInputTokens: { type: 'number' },
+                    totalOutputTokens: { type: 'number' },
+                    cacheCreationTokens: { type: 'number' },
+                    cacheReadTokens: { type: 'number' },
+                    estimatedSavings: { type: 'number' },
+                    hitRate: { type: 'number' },
+                },
+            },
+        },
+        {
+            name: 'reset_cache_stats',
+            description: 'Reset session token usage statistics to zero.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+            outputSchema: {
+                type: 'object',
+                properties: {
+                    reset: { type: 'boolean' },
+                },
+            },
+        },
+        {
+            name: 'analyze_cacheability',
+            description: 'Dry-run: show which segments of a messages array would receive cache_control breakpoints and the estimated token savings, without modifying anything.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    messages: {
+                        type: 'array',
+                        description: 'Messages array to analyze.',
+                        items: { type: 'object' },
+                    },
+                    system: {
+                        description: 'Optional system prompt — string or array of text blocks.',
+                    },
+                    tools: {
+                        type: 'array',
+                        description: 'Optional tool definitions array.',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['messages'],
+            },
+            outputSchema: {
+                type: 'object',
+                properties: {
+                    segments: { type: 'array', items: { type: 'object' } },
+                    totalEstimatedTokens: { type: 'number' },
+                    cacheableTokens: { type: 'number' },
+                    recommendedBreakpoints: { type: 'number' },
+                },
+            },
+        },
+        {
+            name: 'record_usage',
+            description: 'Record token usage from an Anthropic API response into the session stats. Call this after every API response to track cumulative cache savings. Pass the usage object from the response.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    input_tokens: { type: 'number', description: 'Total input tokens billed.' },
+                    output_tokens: { type: 'number', description: 'Total output tokens billed.' },
+                    cache_creation_input_tokens: { type: 'number', description: 'Tokens written to cache (costs 1.25×).' },
+                    cache_read_input_tokens: { type: 'number', description: 'Tokens read from cache (costs 0.1×).' },
+                },
+            },
+            outputSchema: {
+                type: 'object',
+                properties: {
+                    recorded: { type: 'boolean' },
+                    sessionStats: {
+                        type: 'object',
+                        properties: {
+                            turns: { type: 'number' },
+                            totalInputTokens: { type: 'number' },
+                            totalOutputTokens: { type: 'number' },
+                            cacheCreationTokens: { type: 'number' },
+                            cacheReadTokens: { type: 'number' },
+                            estimatedSavings: { type: 'number' },
+                            hitRate: { type: 'number' },
+                        },
+                    },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: toolArgs } = request.params;
+    try {
+        switch (name) {
+            case 'optimize_messages': return handleOptimizeMessages(toolArgs, config);
+            case 'get_cache_stats': return handleGetCacheStats(tracker);
+            case 'reset_cache_stats': return handleResetCacheStats(tracker);
+            case 'analyze_cacheability': return handleAnalyzeCacheability(toolArgs, config);
+            case 'record_usage': return handleRecordUsage(toolArgs, tracker);
+            default: return handleUnknownTool(name);
+        }
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write('[prompt-caching] MCP server ready\n');
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/prompt-optimizer.d.ts

@@ -0,0 +1,10 @@
+import { type PluginConfig, type AnalysisResult, type MessageParam, type SystemPrompt, type ToolDef } from './cache-analyzer.js';
+export interface OptimizeResult {
+    optimizedMessages: MessageParam[];
+    optimizedSystem: SystemPrompt | undefined;
+    optimizedTools: ToolDef[] | undefined;
+    analysis: AnalysisResult;
+    breakpointsAdded: number;
+}
+export declare function optimizeMessages(messages: MessageParam[], system: SystemPrompt | undefined, tools: ToolDef[] | undefined, config: PluginConfig): OptimizeResult;
+//# sourceMappingURL=prompt-optimizer.d.ts.map

package/dist/prompt-optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-optimizer.d.ts","sourceRoot":"","sources":["../src/prompt-optimizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,EAEjB,KAAK,YAAY,EAEjB,KAAK,OAAO,EACb,MAAM,qBAAqB,CAAA;AAI5B,MAAM,WAAW,cAAc;IAC7B,iBAAiB,EAAE,YAAY,EAAE,CAAA;IACjC,eAAe,EAAE,YAAY,GAAG,SAAS,CAAA;IACzC,cAAc,EAAE,OAAO,EAAE,GAAG,SAAS,CAAA;IACrC,QAAQ,EAAE,cAAc,CAAA;IACxB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAiBD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,KAAK,EAAE,OAAO,EAAE,GAAG,SAAS,EAC5B,MAAM,EAAE,YAAY,GACnB,cAAc,CA4DhB"}

package/dist/prompt-optimizer.js

@@ -0,0 +1,73 @@
+import { analyzeMessages, } from './cache-analyzer.js';
+function withCacheControl(block) {
+    return { ...block, cache_control: { type: 'ephemeral' } };
+}
+function addCacheControlToContent(content) {
+    const cc = { type: 'ephemeral' };
+    if (typeof content === 'string') {
+        return [{ type: 'text', text: content, cache_control: cc }];
+    }
+    if (content.length === 0)
+        return content;
+    const copy = content.map(b => ({ ...b }));
+    copy[copy.length - 1] = withCacheControl(copy[copy.length - 1]);
+    return copy;
+}
+export function optimizeMessages(messages, system, tools, config) {
+    const analysis = analyzeMessages(messages, system, tools, config);
+    let budget = config.maxCacheBreakpoints;
+    let breakpointsAdded = 0;
+    let optimizedSystem = system;
+    let optimizedTools = tools;
+    const optimizedMessages = messages.map(m => ({
+        ...m,
+        content: typeof m.content === 'string' ? m.content : m.content.map(b => ({ ...b })),
+    }));
+    // 1. Cache system prompt
+    if (system !== undefined && config.cacheSystemPrompt && budget > 0) {
+        const text = typeof system === 'string' ? system : system.map(b => b.text).join('');
+        if (text.length / 4 >= config.minTokensToCache) {
+            if (typeof system === 'string') {
+                optimizedSystem = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
+            }
+            else {
+                const arr = system.map(b => ({ ...b }));
+                if (arr.length > 0) {
+                    arr[arr.length - 1] = { ...arr[arr.length - 1], cache_control: { type: 'ephemeral' } };
+                }
+                optimizedSystem = arr;
+            }
+            breakpointsAdded++;
+            budget--;
+        }
+    }
+    // 2. Cache tool definitions (breakpoint on last tool entry)
+    if (tools !== undefined && tools.length > 0 && config.cacheToolDefinitions && budget > 0) {
+        if (JSON.stringify(tools).length / 4 >= config.minTokensToCache) {
+            const arr = tools.map(t => ({ ...t }));
+            arr[arr.length - 1] = { ...arr[arr.length - 1], cache_control: { type: 'ephemeral' } };
+            optimizedTools = arr;
+            breakpointsAdded++;
+            budget--;
+        }
+    }
+    // 3. Cache large stable user message blocks (earliest to latest)
+    for (let i = 0; i < messages.length && budget > 0; i++) {
+        const msg = messages[i];
+        if (msg.role !== 'user')
+            continue;
+        const text = typeof msg.content === 'string'
+            ? msg.content
+            : msg.content
+                .filter(b => b.type === 'text')
+                .map(b => b.text)
+                .join('');
+        if (text.length / 4 >= config.minTokensToCache) {
+            optimizedMessages[i] = { ...msg, content: addCacheControlToContent(msg.content) };
+            breakpointsAdded++;
+            budget--;
+        }
+    }
+    return { optimizedMessages, optimizedSystem, optimizedTools, analysis, breakpointsAdded };
+}
+//# sourceMappingURL=prompt-optimizer.js.map

package/dist/prompt-optimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-optimizer.js","sourceRoot":"","sources":["../src/prompt-optimizer.ts"],"names":[],"mappings":"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"}

package/dist/token-tracker.d.ts

@@ -0,0 +1,30 @@
+export interface TurnUsage {
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    timestamp: number;
+}
+export interface CacheStats {
+    turns: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    /** Tokens saved vs. no caching (cache_read costs 0.1× vs 1× normal) */
+    estimatedSavings: number;
+    /** cache_read / (cache_creation + cache_read), 0 if no cache activity */
+    hitRate: number;
+}
+export declare class TokenTracker {
+    private _turns;
+    record(usage: {
+        cache_creation_input_tokens?: number | null;
+        cache_read_input_tokens?: number | null;
+        input_tokens?: number | null;
+        output_tokens?: number | null;
+    }): void;
+    getStats(): CacheStats;
+    reset(): void;
+}
+//# sourceMappingURL=token-tracker.d.ts.map

package/dist/token-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.d.ts","sourceRoot":"","sources":["../src/token-tracker.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,wBAAwB,EAAE,MAAM,CAAA;IAChC,oBAAoB,EAAE,MAAM,CAAA;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,eAAe,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAA;IACxB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAkB;IAEhC,MAAM,CAAC,KAAK,EAAE;QACZ,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3C,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACvC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAC9B,GAAG,IAAI;IAUR,QAAQ,IAAI,UAAU;IAwBtB,KAAK,IAAI,IAAI;CAGd"}

package/dist/token-tracker.js

@@ -0,0 +1,36 @@
+export class TokenTracker {
+    _turns = [];
+    record(usage) {
+        this._turns.push({
+            cacheCreationInputTokens: usage.cache_creation_input_tokens ?? 0,
+            cacheReadInputTokens: usage.cache_read_input_tokens ?? 0,
+            inputTokens: usage.input_tokens ?? 0,
+            outputTokens: usage.output_tokens ?? 0,
+            timestamp: Date.now(),
+        });
+    }
+    getStats() {
+        const turns = this._turns.length;
+        const totalInputTokens = this._turns.reduce((s, t) => s + t.inputTokens, 0);
+        const totalOutputTokens = this._turns.reduce((s, t) => s + t.outputTokens, 0);
+        const cacheCreationTokens = this._turns.reduce((s, t) => s + t.cacheCreationInputTokens, 0);
+        const cacheReadTokens = this._turns.reduce((s, t) => s + t.cacheReadInputTokens, 0);
+        // Savings: each cache_read token costs 0.1× instead of 1×, saving 0.9× per token
+        const estimatedSavings = Math.round(cacheReadTokens * 0.9);
+        const cacheTotal = cacheCreationTokens + cacheReadTokens;
+        const hitRate = cacheTotal > 0 ? cacheReadTokens / cacheTotal : 0;
+        return {
+            turns,
+            totalInputTokens,
+            totalOutputTokens,
+            cacheCreationTokens,
+            cacheReadTokens,
+            estimatedSavings,
+            hitRate,
+        };
+    }
+    reset() {
+        this._turns = [];
+    }
+}
+//# sourceMappingURL=token-tracker.js.map

package/dist/token-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.js","sourceRoot":"","sources":["../src/token-tracker.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,YAAY;IACf,MAAM,GAAgB,EAAE,CAAA;IAEhC,MAAM,CAAC,KAKN;QACC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,wBAAwB,EAAE,KAAK,CAAC,2BAA2B,IAAI,CAAC;YAChE,oBAAoB,EAAE,KAAK,CAAC,uBAAuB,IAAI,CAAC;YACxD,WAAW,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC;YACpC,YAAY,EAAE,KAAK,CAAC,aAAa,IAAI,CAAC;YACtC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAA;IACJ,CAAC;IAED,QAAQ;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAA;QAChC,MAAM,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;QAC3E,MAAM,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;QAC7E,MAAM,mBAAmB,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,wBAAwB,EAAE,CAAC,CAAC,CAAA;QAC3F,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAA;QAEnF,iFAAiF;QACjF,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,GAAG,CAAC,CAAA;QAE1D,MAAM,UAAU,GAAG,mBAAmB,GAAG,eAAe,CAAA;QACxD,MAAM,OAAO,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;QAEjE,OAAO;YACL,KAAK;YACL,gBAAgB;YAChB,iBAAiB;YACjB,mBAAmB;YACnB,eAAe;YACf,gBAAgB;YAChB,OAAO;SACR,CAAA;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAA;IAClB,CAAC;CACF"}

package/dist/utils/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the Claude Code settings file path, cross-platform.
+ * Windows: C:\Users\<user>\.claude\settings.json
+ * Unix:    ~/.claude/settings.json
+ */
+export declare function getConfigPath(): string;
+/**
+ * Returns the project-level plugin config path.
+ * Resolves relative to cwd, rejects paths that escape the project root.
+ */
+export declare function resolveProjectPath(inputPath: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM5D"}

package/dist/utils/paths.js

@@ -0,0 +1,22 @@
+import os from 'os';
+import path from 'path';
+/**
+ * Returns the Claude Code settings file path, cross-platform.
+ * Windows: C:\Users\<user>\.claude\settings.json
+ * Unix:    ~/.claude/settings.json
+ */
+export function getConfigPath() {
+    return path.join(os.homedir(), '.claude', 'settings.json');
+}
+/**
+ * Returns the project-level plugin config path.
+ * Resolves relative to cwd, rejects paths that escape the project root.
+ */
+export function resolveProjectPath(inputPath) {
+    const resolved = path.resolve(process.cwd(), inputPath);
+    if (!resolved.startsWith(process.cwd() + path.sep) && resolved !== process.cwd()) {
+        throw new Error(`Path escapes project root: ${inputPath}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=paths.js.map

package/dist/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,IAAI,MAAM,MAAM,CAAA;AAEvB;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,eAAe,CAAC,CAAA;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,CAAA;IACvD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QACjF,MAAM,IAAI,KAAK,CAAC,8BAA8B,SAAS,EAAE,CAAC,CAAA;IAC5D,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "prompt-caching-mcp",
+  "version": "1.0.0",
+  "description": "Automatic prompt caching for Claude Code. Cuts token costs by up to 90%.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "prompt-caching-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "benchmark": "vitest run src/__tests__/benchmarks/ --passWithNoTests"
+  },
+  "keywords": [
+    "claude",
+    "anthropic",
+    "mcp",
+    "prompt-caching",
+    "claude-code",
+    "token-optimization",
+    "llm",
+    "developer-tools",
+    "cost-reduction"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@modelcontextprotocol/sdk": "^1.8.0"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.0.0",
+    "@commitlint/types": "^19.0.0",
+    "@eslint/js": "^9.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flightlesstux/prompt-caching.git"
+  },
+  "bugs": {
+    "url": "https://github.com/flightlesstux/prompt-caching/issues"
+  },
+  "homepage": "https://flightlesstux.github.io/prompt-caching/"
+}