@trazum/mcp 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Muñoz Rey
+
+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,80 @@
+# @trazum/mcp
+
+Trazum as an [MCP](https://modelcontextprotocol.io) server, so an agent can price
+and budget a prompt **before** it sends it.
+
+Every other Trazum surface answers that question for a human after the fact — a CLI
+you run, a page you paste into, a check that fails a build. This answers it for the
+thing actually composing the prompt.
+
+## It runs on your machine and costs nothing to host
+
+One process over stdio, spawned by whatever client wants it, exactly like the CLI.
+No service, nothing to keep up, and **no prompt leaves the machine**. Worth stating
+because "MCP server" reads like infrastructure and this is not.
+
+```jsonc
+// Claude Code: .mcp.json — or the equivalent in any MCP client
+{
+  "mcpServers": {
+    "trazum": { "command": "npx", "args": ["-y", "@trazum/mcp"] }
+  }
+}
+```
+
+## The tools
+
+| Tool | Answers |
+| --- | --- |
+| `check_prompt` | Does this prompt fit `maxTokens`? And if not, would optimising it fit? |
+| `optimize_prompt` | The shorter text, the token counts either side, what the difference is worth per month, and any advisories. |
+| `list_models` | Prices, context windows and cacheable minimums, with the date the table was reviewed. |
+
+`check_prompt` is the one worth wiring up. It has **three** outcomes rather than
+two, and the third is the point:
+
+```
+OVER BUDGET — 2,140 tokens against 2,000, but the safe rules bring it to 1,870,
+which fits. Optimise rather than cut.
+```
+
+"Over budget" and "over budget but the rules would fix it" are different
+instructions. A boolean throws away the actionable half.
+
+## What it cannot do, which is the design
+
+**No paths.** Every tool takes prompt text. A tool that accepted a filename would
+be a file-read primitive reachable by whatever the model decided to ask for. This
+package imports `@trazum/core`, the browser-safe entry point, and never
+`@trazum/core/node` — the capability is *absent* rather than unused, and a test
+enforces it.
+
+**No network.** Nothing here calls a model. `--suggest` and `eval` exist in the CLI
+and are deliberately not exposed: they spend your money, and a tool an agent can
+invoke in a loop must not be able to do that.
+
+**No writes.** The tools return figures. Applying them is the agent's job, in its
+own context, where you can see the diff.
+
+**Zero runtime dependencies outside this repository**, which is why the JSON-RPC
+layer is written by hand rather than taken from the official SDK. That is not
+preference. An MCP server reads prompts handed to it by a model, in a process you
+did not start yourself, and every dependency is somebody else's code on that path.
+The invariant applies here with more force than anywhere else in Trazum, so
+relaxing it here would have been backwards.
+
+## Limits, stated
+
+The protocol implementation covers what a tools-only server needs — `initialize`,
+`notifications/initialized`, `tools/list`, `tools/call`, `ping` — and answers
+anything else with `-32601 Method not found`. No resources, no prompts, no
+sampling. It is driven by a raw newline-delimited client in the tests; it has not
+been driven by every MCP client in existence.
+
+Token counts are estimates (±15% on prose, calibrated against Claude's tokenizer),
+and every tool says so in its own output. A prompt within a few percent of its
+budget should be treated as uncertain rather than as passing.
+
+## Licence
+
+MIT. Part of [Trazum](https://github.com/Davmunrey/Trazum).

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,26 @@
+#!/usr/bin/env node
+import { PROTOCOL_VERSION, serve } from './rpc.js';
+import { TOOLS } from './tools.js';
+/**
+ * Trazum as an MCP server.
+ *
+ * The point is narrow: an agent about to spend money on a prompt can ask what it
+ * will cost, and whether it busts a budget, *before* sending it. Every other
+ * surface here answers that for a human after the fact — a CLI you run, a page you
+ * paste into, a check that fails a build. This answers it for the thing actually
+ * composing the prompt.
+ *
+ * **It runs on the caller's machine and costs this project nothing.** One process
+ * over stdio, spawned by whatever client wants it, exactly like the CLI. There is
+ * no service to host, nothing to keep up, and no prompt leaves the machine. Worth
+ * saying because "MCP server" reads like infrastructure and this is not.
+ */
+serve(process.stdin, process.stdout, TOOLS, {
+    name: 'trazum',
+    version: '1.8.0',
+    instructions: 'Price and budget a prompt before sending it. Every tool takes prompt text and returns '
+        + 'figures; none of them read files, reach the network or call a model. Token counts are '
+        + `estimates, so treat a prompt within a few percent of its budget as uncertain. `
+        + `Protocol ${PROTOCOL_VERSION}, tools only.`,
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AAEH,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE;IAC1C,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,OAAO;IAChB,YAAY,EACV,wFAAwF;UACtF,wFAAwF;UACxF,gFAAgF;UAChF,YAAY,gBAAgB,eAAe;CAChD,CAAC,CAAC"}

package/dist/rpc.d.ts

@@ -0,0 +1,79 @@
+/**
+ * JSON-RPC 2.0 over stdio, by hand, because of what this package is.
+ *
+ * The obvious implementation imports `@modelcontextprotocol/sdk`. It was written
+ * that way first, and thirteen tests passed against a real process. Then
+ * `publish.test.js` refused it: *every* publishable package in this repository
+ * carries no runtime dependencies, and the reason `security.test.js` gives is
+ * "the core and the CLI process untrusted text; every runtime dependency is code
+ * that would run on that text with no review from this project."
+ *
+ * That argument applies here with **more** force than anywhere else in the
+ * repository, not less. An MCP server reads prompts handed to it by a model, in a
+ * process the user did not start by hand, and the SDK plus its own dependency
+ * tree is a large amount of somebody else's code sitting on that path. Relaxing
+ * the invariant at the exact point it matters most would have been the wrong
+ * trade, so the invariant won and this file exists.
+ *
+ * **What that costs, stated plainly.** A hand-written protocol is where subtle
+ * incompatibility lives. This implements the parts a tools-only server needs —
+ * `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, and
+ * `ping` — and nothing else. No resources, no prompts, no sampling, no
+ * completion, no server-initiated requests. A client asking for any of those gets
+ * a proper `-32601 Method not found` rather than silence. It has been driven by a
+ * raw newline-delimited client in the tests; it has not been driven by every real
+ * MCP client in existence, and that is the honest limit of the claim.
+ */
+/** The version this server implements. Echoed back when the client asks for it. */
+export declare const PROTOCOL_VERSION = "2025-06-18";
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+/** Standard JSON-RPC codes, plus the one MCP adds for bad tool arguments. */
+export declare const ERROR: {
+    readonly parse: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+};
+export interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    /** JSON Schema, written out, since there is no schema library to build one. */
+    inputSchema: Record<string, unknown>;
+    /**
+     * Validates and coerces the arguments, or throws with a message the model can
+     * act on. Returns the text to send back.
+     */
+    run: (args: Record<string, unknown>) => string;
+}
+/** Thrown by a tool when its arguments are wrong. Distinguished from a crash. */
+export declare class InvalidArguments extends Error {
+}
+export interface ServerInfo {
+    name: string;
+    version: string;
+    instructions: string;
+}
+/**
+ * Handles one decoded message and returns the response, or `null` for a
+ * notification.
+ *
+ * Pure: takes a message, returns a message. The transport below is what touches
+ * streams, so every dispatch rule here is testable without a process.
+ */
+export declare function handle(message: unknown, tools: readonly ToolDefinition[], info: ServerInfo): object | null;
+/**
+ * Reads newline-delimited JSON from a stream and writes replies to another.
+ *
+ * Line-delimited rather than the Content-Length framing LSP uses, because that is
+ * what MCP's stdio transport specifies. A message may not contain a raw newline,
+ * which `JSON.stringify` guarantees.
+ */
+export declare function serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, tools: readonly ToolDefinition[], info: ServerInfo): void;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,6EAA6E;AAC7E,eAAO,MAAM,KAAK;aAChB,KAAK,EAAE,CAAC,KAAK;aACb,cAAc,EAAE,CAAC,KAAK;aACtB,cAAc,EAAE,CAAC,KAAK;aACtB,aAAa,EAAE,CAAC,KAAK;aACrB,QAAQ,EAAE,CAAC,KAAK;CACR,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;OAGG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;CAChD;AAED,iFAAiF;AACjF,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,IAAI,EAAE,UAAU,GACf,MAAM,GAAG,IAAI,CAuHf;AAUD;;;;;;GAMG;AACH,wBAAgB,KAAK,CACnB,KAAK,EAAE,MAAM,CAAC,cAAc,EAC5B,MAAM,EAAE,MAAM,CAAC,cAAc,EAC7B,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,IAAI,EAAE,UAAU,GACf,IAAI,CAwCN"}

package/dist/rpc.js

@@ -0,0 +1,205 @@
+/**
+ * JSON-RPC 2.0 over stdio, by hand, because of what this package is.
+ *
+ * The obvious implementation imports `@modelcontextprotocol/sdk`. It was written
+ * that way first, and thirteen tests passed against a real process. Then
+ * `publish.test.js` refused it: *every* publishable package in this repository
+ * carries no runtime dependencies, and the reason `security.test.js` gives is
+ * "the core and the CLI process untrusted text; every runtime dependency is code
+ * that would run on that text with no review from this project."
+ *
+ * That argument applies here with **more** force than anywhere else in the
+ * repository, not less. An MCP server reads prompts handed to it by a model, in a
+ * process the user did not start by hand, and the SDK plus its own dependency
+ * tree is a large amount of somebody else's code sitting on that path. Relaxing
+ * the invariant at the exact point it matters most would have been the wrong
+ * trade, so the invariant won and this file exists.
+ *
+ * **What that costs, stated plainly.** A hand-written protocol is where subtle
+ * incompatibility lives. This implements the parts a tools-only server needs —
+ * `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, and
+ * `ping` — and nothing else. No resources, no prompts, no sampling, no
+ * completion, no server-initiated requests. A client asking for any of those gets
+ * a proper `-32601 Method not found` rather than silence. It has been driven by a
+ * raw newline-delimited client in the tests; it has not been driven by every real
+ * MCP client in existence, and that is the honest limit of the claim.
+ */
+/** The version this server implements. Echoed back when the client asks for it. */
+export const PROTOCOL_VERSION = '2025-06-18';
+/** Standard JSON-RPC codes, plus the one MCP adds for bad tool arguments. */
+export const ERROR = {
+    parse: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internal: -32603,
+};
+/** Thrown by a tool when its arguments are wrong. Distinguished from a crash. */
+export class InvalidArguments extends Error {
+}
+/**
+ * Handles one decoded message and returns the response, or `null` for a
+ * notification.
+ *
+ * Pure: takes a message, returns a message. The transport below is what touches
+ * streams, so every dispatch rule here is testable without a process.
+ */
+export function handle(message, tools, info) {
+    if (typeof message !== 'object' || message === null) {
+        return errorFor(null, ERROR.invalidRequest, 'a message must be an object');
+    }
+    const request = message;
+    const id = request.id ?? null;
+    const isNotification = request.id === undefined;
+    if (request.jsonrpc !== '2.0') {
+        return isNotification ? null : errorFor(id, ERROR.invalidRequest, 'jsonrpc must be "2.0"');
+    }
+    if (typeof request.method !== 'string') {
+        return isNotification ? null : errorFor(id, ERROR.invalidRequest, 'method must be a string');
+    }
+    /**
+     * Notifications get no reply, ever — and this check belongs *before* the switch.
+     *
+     * It was inside it at first, listing the two `notifications/*` methods by name,
+     * which is the wrong rule: a notification is defined by the **absence of an
+     * id**, not by its method. `{"jsonrpc":"2.0","method":"initialize"}` with no id
+     * is a notification, and that version answered it. Replying to a notification
+     * is a protocol violation some clients tolerate and others hang on, which is
+     * the worst kind to have because it works in testing. Found by a test that
+     * asked for the rule rather than for the two names.
+     */
+    if (isNotification)
+        return null;
+    switch (request.method) {
+        case 'initialize': {
+            const params = (request.params ?? {});
+            /**
+             * Echo the client's version when it is a string, otherwise offer ours.
+             *
+             * A client that speaks a version this server has never heard of is still
+             * better served by being told what it asked for than by a hard refusal:
+             * every method below is version-independent, and the alternative is
+             * refusing to start over a string.
+             */
+            const version = typeof params.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION;
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    protocolVersion: version,
+                    // Tools only. Declaring capabilities this server does not implement is
+                    // how a client comes to ask for one and get an error it did not expect.
+                    capabilities: { tools: {} },
+                    serverInfo: { name: info.name, version: info.version },
+                    instructions: info.instructions,
+                },
+            };
+        }
+        case 'ping':
+            return { jsonrpc: '2.0', id, result: {} };
+        case 'tools/list':
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    tools: tools.map((tool) => ({
+                        name: tool.name,
+                        title: tool.title,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                    })),
+                },
+            };
+        case 'tools/call': {
+            const params = (request.params ?? {});
+            if (typeof params.name !== 'string') {
+                return errorFor(id, ERROR.invalidParams, 'name must be a string');
+            }
+            const tool = tools.find((candidate) => candidate.name === params.name);
+            if (!tool) {
+                return errorFor(id, ERROR.invalidParams, `unknown tool: ${params.name}`);
+            }
+            const args = typeof params.arguments === 'object' && params.arguments !== null
+                ? params.arguments
+                : {};
+            try {
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: { content: [{ type: 'text', text: tool.run(args) }] },
+                };
+            }
+            catch (error) {
+                /**
+                 * A tool failure is a *result* with `isError`, not a JSON-RPC error.
+                 *
+                 * The distinction is the whole point of that flag: a protocol error means
+                 * the client is broken, while `isError` means the model asked for
+                 * something it should ask differently, and the model is the one that
+                 * needs to read the message. Sending a protocol error here would hide the
+                 * explanation from the only party able to act on it.
+                 */
+                const text = error instanceof InvalidArguments
+                    ? error.message
+                    : `the tool failed: ${error instanceof Error ? error.message : String(error)}`;
+                return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }], isError: true } };
+            }
+        }
+        default:
+            return errorFor(id, ERROR.methodNotFound, `this server implements tools only: ${request.method}`);
+    }
+}
+function errorFor(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+/**
+ * Reads newline-delimited JSON from a stream and writes replies to another.
+ *
+ * Line-delimited rather than the Content-Length framing LSP uses, because that is
+ * what MCP's stdio transport specifies. A message may not contain a raw newline,
+ * which `JSON.stringify` guarantees.
+ */
+export function serve(input, output, tools, info) {
+    let buffer = '';
+    /**
+     * A cap, because the peer is not necessarily well behaved.
+     *
+     * Without one, a stream that never sends a newline grows this string until the
+     * process dies of memory exhaustion — a denial of service that needs no
+     * malice, just a client with a bug.
+     */
+    const MAX_LINE = 8 * 1024 * 1024;
+    input.setEncoding('utf8');
+    input.on('data', (chunk) => {
+        buffer += chunk;
+        if (buffer.length > MAX_LINE) {
+            buffer = '';
+            write(output, errorFor(null, ERROR.invalidRequest, 'message exceeded 8 MiB'));
+            return;
+        }
+        let newline = buffer.indexOf('\n');
+        while (newline !== -1) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            if (line !== '') {
+                let decoded;
+                try {
+                    decoded = JSON.parse(line);
+                }
+                catch {
+                    write(output, errorFor(null, ERROR.parse, 'not valid JSON'));
+                    newline = buffer.indexOf('\n');
+                    continue;
+                }
+                const response = handle(decoded, tools, info);
+                if (response !== null)
+                    write(output, response);
+            }
+            newline = buffer.indexOf('\n');
+        }
+    });
+}
+function write(output, message) {
+    output.write(`${JSON.stringify(message)}\n`);
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,32 @@
+import type { ToolDefinition } from './rpc.js';
+/**
+ * The tools, kept in one file so the whole surface an agent can reach reads in one
+ * pass.
+ *
+ * **Three deliberate absences, and they are the security design.**
+ *
+ * *No paths.* Every tool takes prompt text. A tool that accepted a filename would
+ * be a file-read primitive reachable by whatever the model decided to ask for, and
+ * "we reviewed it" is not a durable defence against one being added later. This
+ * package imports `@trazum/core`, the browser-safe entry point, and never
+ * `@trazum/core/node` — so the capability is *absent* rather than unused, and a
+ * test enforces that.
+ *
+ * *No network.* Nothing here calls a model. `--suggest` and `eval` exist in the
+ * CLI and are deliberately not exposed: they spend the caller's money, and a tool
+ * an agent can invoke in a loop must not be able to do that. Everything below is
+ * arithmetic on text.
+ *
+ * *No writes.* The tools return figures. Applying them is the agent's job, in its
+ * own context, where a human can see the diff.
+ */
+/**
+ * The same cap the web API uses, for the same reason.
+ *
+ * An agent in a loop is exactly the caller that hands you a 40 MB string by
+ * accident. Refusing early with a number beats an unbounded pass over it.
+ */
+export declare const MAX_PROMPT_CHARS = 400000;
+/** The whole surface. An exact list, asserted as one by the tests. */
+export declare const TOOLS: readonly ToolDefinition[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,SAAU,CAAC;AA+MxC,sEAAsE;AACtE,eAAO,MAAM,KAAK,EAAE,SAAS,cAAc,EAA8B,CAAC"}

package/dist/tools.js

@@ -0,0 +1,213 @@
+import { BUNDLED_CATALOGUE, PRICING_LAST_REVIEWED, formatUsd, listModels, optimize, } from '@trazum/core';
+import { InvalidArguments } from './rpc.js';
+/**
+ * The tools, kept in one file so the whole surface an agent can reach reads in one
+ * pass.
+ *
+ * **Three deliberate absences, and they are the security design.**
+ *
+ * *No paths.* Every tool takes prompt text. A tool that accepted a filename would
+ * be a file-read primitive reachable by whatever the model decided to ask for, and
+ * "we reviewed it" is not a durable defence against one being added later. This
+ * package imports `@trazum/core`, the browser-safe entry point, and never
+ * `@trazum/core/node` — so the capability is *absent* rather than unused, and a
+ * test enforces that.
+ *
+ * *No network.* Nothing here calls a model. `--suggest` and `eval` exist in the
+ * CLI and are deliberately not exposed: they spend the caller's money, and a tool
+ * an agent can invoke in a loop must not be able to do that. Everything below is
+ * arithmetic on text.
+ *
+ * *No writes.* The tools return figures. Applying them is the agent's job, in its
+ * own context, where a human can see the diff.
+ */
+/**
+ * The same cap the web API uses, for the same reason.
+ *
+ * An agent in a loop is exactly the caller that hands you a 40 MB string by
+ * accident. Refusing early with a number beats an unbounded pass over it.
+ */
+export const MAX_PROMPT_CHARS = 400_000;
+/** Every figure this server prints descends from the estimator, so it says so. */
+const BAND_NOTE = 'token counts are estimates (±15% on prose, calibrated on Claude); prices reviewed '
+    + PRICING_LAST_REVIEWED;
+function promptFrom(args) {
+    const prompt = args.prompt;
+    if (typeof prompt !== 'string')
+        throw new InvalidArguments('prompt must be a string');
+    if (prompt.length === 0)
+        throw new InvalidArguments('prompt is empty');
+    if (prompt.length > MAX_PROMPT_CHARS) {
+        throw new InvalidArguments(`prompt is ${prompt.length} characters, over the ${MAX_PROMPT_CHARS} limit`);
+    }
+    return prompt;
+}
+function levelFrom(args) {
+    const level = args.level ?? 'safe';
+    if (level !== 'safe' && level !== 'aggressive') {
+        throw new InvalidArguments('level must be "safe" or "aggressive"');
+    }
+    return level;
+}
+/**
+ * A positive integer, or the default.
+ *
+ * Written out rather than reached for from a validation library, and bounded on
+ * both ends: `callsPerMonth: 1e308` would otherwise produce an Infinity in
+ * somebody's budget, which is worse than a refusal because it looks like an
+ * answer.
+ */
+function intFrom(args, key, fallback, { min, max }) {
+    const raw = args[key];
+    if (raw === undefined)
+        return fallback;
+    if (typeof raw !== 'number' || !Number.isInteger(raw)) {
+        throw new InvalidArguments(`${key} must be an integer`);
+    }
+    if (raw < min || raw > max) {
+        throw new InvalidArguments(`${key} must be between ${min} and ${max}`);
+    }
+    return raw;
+}
+const PROMPT_PROPERTY = {
+    type: 'string',
+    minLength: 1,
+    maxLength: MAX_PROMPT_CHARS,
+    description: 'The prompt text itself. This server never reads files.',
+};
+const LEVEL_PROPERTY = {
+    type: 'string',
+    enum: ['safe', 'aggressive'],
+    default: 'safe',
+    description: 'safe leaves meaning untouched; aggressive also rewords, and wants reading',
+};
+const OPTIMIZE = {
+    name: 'optimize_prompt',
+    title: 'Optimise a prompt and price the difference',
+    description: "Applies Trazum's deterministic rules to a prompt and returns the shorter text, the "
+        + 'token counts either side, what the difference is worth per month, and any advisories. '
+        + 'Offline and free: no model is called.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            prompt: PROMPT_PROPERTY,
+            level: LEVEL_PROPERTY,
+            model: {
+                type: 'string',
+                default: 'claude-opus-5',
+                description: 'Model id used for pricing. Call list_models for what is known.',
+            },
+            callsPerMonth: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 1_000_000_000,
+                default: 1000,
+                description: 'Used only to scale the figures',
+            },
+            avgOutputTokens: { type: 'integer', minimum: 0, maximum: 1_000_000, default: 500 },
+        },
+        required: ['prompt'],
+        additionalProperties: false,
+    },
+    run: (args) => {
+        const model = args.model ?? 'claude-opus-5';
+        if (typeof model !== 'string')
+            throw new InvalidArguments('model must be a string');
+        const callsPerMonth = intFrom(args, 'callsPerMonth', 1000, { min: 1, max: 1_000_000_000 });
+        const avgOutputTokens = intFrom(args, 'avgOutputTokens', 500, { min: 0, max: 1_000_000 });
+        const result = optimize(promptFrom(args), {
+            level: levelFrom(args),
+            usage: { model, callsPerMonth, avgOutputTokens },
+        });
+        const lines = [
+            `tokens: ${result.tokensBefore} → ${result.tokensAfter}`
+                + ` (${result.tokensBefore - result.tokensAfter} fewer)`,
+            `monthly saving at ${callsPerMonth.toLocaleString('en-US')} calls:`
+                + ` ${formatUsd(result.savings.monthlySavingsUsd)}`,
+            BAND_NOTE,
+            '',
+            '--- optimised prompt ---',
+            result.optimized,
+        ];
+        if (result.advisories.length > 0) {
+            lines.push('', '--- advisories ---');
+            for (const advisory of result.advisories) {
+                const money = advisory.estimatedMonthlyUsd === null
+                    ? ''
+                    : ` (~${formatUsd(advisory.estimatedMonthlyUsd)}/month)`;
+                lines.push(`[${advisory.id}] ${advisory.title}${money}`);
+            }
+        }
+        return lines.join('\n');
+    },
+};
+const CHECK = {
+    name: 'check_prompt',
+    title: 'Check a prompt against a token budget',
+    description: 'Answers whether a prompt fits a maximum, and if not, whether optimising it would. '
+        + 'This is the one to call before sending a prompt you are unsure about.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            prompt: PROMPT_PROPERTY,
+            maxTokens: {
+                type: 'integer',
+                minimum: 1,
+                description: 'The budget. Required: a check with no maximum is not a check.',
+            },
+            level: LEVEL_PROPERTY,
+        },
+        required: ['prompt', 'maxTokens'],
+        additionalProperties: false,
+    },
+    run: (args) => {
+        if (args.maxTokens === undefined)
+            throw new InvalidArguments('maxTokens is required');
+        const maxTokens = intFrom(args, 'maxTokens', 0, { min: 1, max: Number.MAX_SAFE_INTEGER });
+        const level = levelFrom(args);
+        const result = optimize(promptFrom(args), { level });
+        /**
+         * Three outcomes, not two, and the third is why this tool exists.
+         *
+         * "Over budget" and "over budget but the rules would fix it" are different
+         * instructions to whoever asked: one means cut content, the other means run
+         * the rules. A boolean throws away the actionable half.
+         */
+        const verdict = result.tokensBefore <= maxTokens
+            ? `PASS — ${result.tokensBefore} tokens, budget ${maxTokens}`
+            : result.tokensAfter <= maxTokens
+                ? `OVER BUDGET — ${result.tokensBefore} tokens against ${maxTokens}, but the ${level}`
+                    + ` rules bring it to ${result.tokensAfter}, which fits. Optimise rather than cut.`
+                : `OVER BUDGET — ${result.tokensBefore} tokens against ${maxTokens}. Even optimised it`
+                    + ` is ${result.tokensAfter}: content has to be cut.`;
+        return [
+            verdict,
+            'token counts are estimates (±15% on prose, calibrated on Claude), so a prompt within'
+                + ' a few percent of its budget should be treated as uncertain',
+        ].join('\n');
+    },
+};
+const MODELS = {
+    name: 'list_models',
+    title: 'Models Trazum can price, and their rates',
+    description: 'Input and output price per million tokens, context window and cacheable minimum, for '
+        + 'every model in the bundled catalogue.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    run: () => {
+        const rows = listModels().map((model) => {
+            const cache = model.caching === 'none' || model.cacheMinTokens === null
+                ? 'no caching'
+                : `cache min ${model.cacheMinTokens}`;
+            return `${model.id}  in $${model.inputPerMTok}/Mtok  out $${model.outputPerMTok}/Mtok`
+                + `  context ${model.contextWindow.toLocaleString('en-US')}  ${cache}`;
+        });
+        return [
+            `prices reviewed ${BUNDLED_CATALOGUE.lastReviewed} — verify before budgeting`,
+            '',
+            ...rows,
+        ].join('\n');
+    },
+};
+/** The whole surface. An exact list, asserted as one by the tests. */
+export const TOOLS = [OPTIMIZE, CHECK, MODELS];
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@trazum/mcp",
+  "version": "1.8.0",
+  "description": "Trazum as an MCP server: let an agent price and budget its own prompts before it sends them.",
+  "license": "MIT",
+  "author": "David Mu\u00f1oz Rey",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Davmunrey/Trazum.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "prompt",
+    "llm",
+    "tokens",
+    "cost"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "trazum-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@trazum/core": "1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { PROTOCOL_VERSION, serve } from './rpc.js';
+import { TOOLS } from './tools.js';
+
+/**
+ * Trazum as an MCP server.
+ *
+ * The point is narrow: an agent about to spend money on a prompt can ask what it
+ * will cost, and whether it busts a budget, *before* sending it. Every other
+ * surface here answers that for a human after the fact — a CLI you run, a page you
+ * paste into, a check that fails a build. This answers it for the thing actually
+ * composing the prompt.
+ *
+ * **It runs on the caller's machine and costs this project nothing.** One process
+ * over stdio, spawned by whatever client wants it, exactly like the CLI. There is
+ * no service to host, nothing to keep up, and no prompt leaves the machine. Worth
+ * saying because "MCP server" reads like infrastructure and this is not.
+ */
+
+serve(process.stdin, process.stdout, TOOLS, {
+  name: 'trazum',
+  version: '1.8.0',
+  instructions:
+    'Price and budget a prompt before sending it. Every tool takes prompt text and returns '
+    + 'figures; none of them read files, reach the network or call a model. Token counts are '
+    + `estimates, so treat a prompt within a few percent of its budget as uncertain. `
+    + `Protocol ${PROTOCOL_VERSION}, tools only.`,
+});

package/src/rpc.ts

@@ -0,0 +1,265 @@
+/**
+ * JSON-RPC 2.0 over stdio, by hand, because of what this package is.
+ *
+ * The obvious implementation imports `@modelcontextprotocol/sdk`. It was written
+ * that way first, and thirteen tests passed against a real process. Then
+ * `publish.test.js` refused it: *every* publishable package in this repository
+ * carries no runtime dependencies, and the reason `security.test.js` gives is
+ * "the core and the CLI process untrusted text; every runtime dependency is code
+ * that would run on that text with no review from this project."
+ *
+ * That argument applies here with **more** force than anywhere else in the
+ * repository, not less. An MCP server reads prompts handed to it by a model, in a
+ * process the user did not start by hand, and the SDK plus its own dependency
+ * tree is a large amount of somebody else's code sitting on that path. Relaxing
+ * the invariant at the exact point it matters most would have been the wrong
+ * trade, so the invariant won and this file exists.
+ *
+ * **What that costs, stated plainly.** A hand-written protocol is where subtle
+ * incompatibility lives. This implements the parts a tools-only server needs —
+ * `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, and
+ * `ping` — and nothing else. No resources, no prompts, no sampling, no
+ * completion, no server-initiated requests. A client asking for any of those gets
+ * a proper `-32601 Method not found` rather than silence. It has been driven by a
+ * raw newline-delimited client in the tests; it has not been driven by every real
+ * MCP client in existence, and that is the honest limit of the claim.
+ */
+
+/** The version this server implements. Echoed back when the client asks for it. */
+export const PROTOCOL_VERSION = '2025-06-18';
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+/** Standard JSON-RPC codes, plus the one MCP adds for bad tool arguments. */
+export const ERROR = {
+  parse: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32603,
+} as const;
+
+export interface ToolDefinition {
+  name: string;
+  title: string;
+  description: string;
+  /** JSON Schema, written out, since there is no schema library to build one. */
+  inputSchema: Record<string, unknown>;
+  /**
+   * Validates and coerces the arguments, or throws with a message the model can
+   * act on. Returns the text to send back.
+   */
+  run: (args: Record<string, unknown>) => string;
+}
+
+/** Thrown by a tool when its arguments are wrong. Distinguished from a crash. */
+export class InvalidArguments extends Error {}
+
+export interface ServerInfo {
+  name: string;
+  version: string;
+  instructions: string;
+}
+
+/**
+ * Handles one decoded message and returns the response, or `null` for a
+ * notification.
+ *
+ * Pure: takes a message, returns a message. The transport below is what touches
+ * streams, so every dispatch rule here is testable without a process.
+ */
+export function handle(
+  message: unknown,
+  tools: readonly ToolDefinition[],
+  info: ServerInfo,
+): object | null {
+  if (typeof message !== 'object' || message === null) {
+    return errorFor(null, ERROR.invalidRequest, 'a message must be an object');
+  }
+
+  const request = message as JsonRpcRequest;
+  const id = request.id ?? null;
+  const isNotification = request.id === undefined;
+
+  if (request.jsonrpc !== '2.0') {
+    return isNotification ? null : errorFor(id, ERROR.invalidRequest, 'jsonrpc must be "2.0"');
+  }
+  if (typeof request.method !== 'string') {
+    return isNotification ? null : errorFor(id, ERROR.invalidRequest, 'method must be a string');
+  }
+
+  /**
+   * Notifications get no reply, ever — and this check belongs *before* the switch.
+   *
+   * It was inside it at first, listing the two `notifications/*` methods by name,
+   * which is the wrong rule: a notification is defined by the **absence of an
+   * id**, not by its method. `{"jsonrpc":"2.0","method":"initialize"}` with no id
+   * is a notification, and that version answered it. Replying to a notification
+   * is a protocol violation some clients tolerate and others hang on, which is
+   * the worst kind to have because it works in testing. Found by a test that
+   * asked for the rule rather than for the two names.
+   */
+  if (isNotification) return null;
+
+  switch (request.method) {
+    case 'initialize': {
+      const params = (request.params ?? {}) as { protocolVersion?: unknown };
+      /**
+       * Echo the client's version when it is a string, otherwise offer ours.
+       *
+       * A client that speaks a version this server has never heard of is still
+       * better served by being told what it asked for than by a hard refusal:
+       * every method below is version-independent, and the alternative is
+       * refusing to start over a string.
+       */
+      const version =
+        typeof params.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION;
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: version,
+          // Tools only. Declaring capabilities this server does not implement is
+          // how a client comes to ask for one and get an error it did not expect.
+          capabilities: { tools: {} },
+          serverInfo: { name: info.name, version: info.version },
+          instructions: info.instructions,
+        },
+      };
+    }
+
+    case 'ping':
+      return { jsonrpc: '2.0', id, result: {} };
+
+    case 'tools/list':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          tools: tools.map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+          })),
+        },
+      };
+
+    case 'tools/call': {
+      const params = (request.params ?? {}) as { name?: unknown; arguments?: unknown };
+      if (typeof params.name !== 'string') {
+        return errorFor(id, ERROR.invalidParams, 'name must be a string');
+      }
+      const tool = tools.find((candidate) => candidate.name === params.name);
+      if (!tool) {
+        return errorFor(id, ERROR.invalidParams, `unknown tool: ${params.name}`);
+      }
+
+      const args =
+        typeof params.arguments === 'object' && params.arguments !== null
+          ? (params.arguments as Record<string, unknown>)
+          : {};
+
+      try {
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: { content: [{ type: 'text', text: tool.run(args) }] },
+        };
+      } catch (error) {
+        /**
+         * A tool failure is a *result* with `isError`, not a JSON-RPC error.
+         *
+         * The distinction is the whole point of that flag: a protocol error means
+         * the client is broken, while `isError` means the model asked for
+         * something it should ask differently, and the model is the one that
+         * needs to read the message. Sending a protocol error here would hide the
+         * explanation from the only party able to act on it.
+         */
+        const text =
+          error instanceof InvalidArguments
+            ? error.message
+            : `the tool failed: ${error instanceof Error ? error.message : String(error)}`;
+        return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }], isError: true } };
+      }
+    }
+
+    default:
+      return errorFor(
+        id,
+        ERROR.methodNotFound,
+        `this server implements tools only: ${request.method}`,
+      );
+  }
+}
+
+function errorFor(
+  id: string | number | null,
+  code: number,
+  message: string,
+): object {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+/**
+ * Reads newline-delimited JSON from a stream and writes replies to another.
+ *
+ * Line-delimited rather than the Content-Length framing LSP uses, because that is
+ * what MCP's stdio transport specifies. A message may not contain a raw newline,
+ * which `JSON.stringify` guarantees.
+ */
+export function serve(
+  input: NodeJS.ReadableStream,
+  output: NodeJS.WritableStream,
+  tools: readonly ToolDefinition[],
+  info: ServerInfo,
+): void {
+  let buffer = '';
+
+  /**
+   * A cap, because the peer is not necessarily well behaved.
+   *
+   * Without one, a stream that never sends a newline grows this string until the
+   * process dies of memory exhaustion — a denial of service that needs no
+   * malice, just a client with a bug.
+   */
+  const MAX_LINE = 8 * 1024 * 1024;
+
+  input.setEncoding('utf8');
+  input.on('data', (chunk: string) => {
+    buffer += chunk;
+    if (buffer.length > MAX_LINE) {
+      buffer = '';
+      write(output, errorFor(null, ERROR.invalidRequest, 'message exceeded 8 MiB'));
+      return;
+    }
+
+    let newline = buffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line !== '') {
+        let decoded: unknown;
+        try {
+          decoded = JSON.parse(line);
+        } catch {
+          write(output, errorFor(null, ERROR.parse, 'not valid JSON'));
+          newline = buffer.indexOf('\n');
+          continue;
+        }
+        const response = handle(decoded, tools, info);
+        if (response !== null) write(output, response);
+      }
+      newline = buffer.indexOf('\n');
+    }
+  });
+}
+
+function write(output: NodeJS.WritableStream, message: object): void {
+  output.write(`${JSON.stringify(message)}\n`);
+}

package/src/tools.ts

@@ -0,0 +1,249 @@
+import {
+  BUNDLED_CATALOGUE,
+  PRICING_LAST_REVIEWED,
+  formatUsd,
+  listModels,
+  optimize,
+} from '@trazum/core';
+import type { RuleLevel } from '@trazum/core';
+
+import { InvalidArguments } from './rpc.js';
+import type { ToolDefinition } from './rpc.js';
+
+/**
+ * The tools, kept in one file so the whole surface an agent can reach reads in one
+ * pass.
+ *
+ * **Three deliberate absences, and they are the security design.**
+ *
+ * *No paths.* Every tool takes prompt text. A tool that accepted a filename would
+ * be a file-read primitive reachable by whatever the model decided to ask for, and
+ * "we reviewed it" is not a durable defence against one being added later. This
+ * package imports `@trazum/core`, the browser-safe entry point, and never
+ * `@trazum/core/node` — so the capability is *absent* rather than unused, and a
+ * test enforces that.
+ *
+ * *No network.* Nothing here calls a model. `--suggest` and `eval` exist in the
+ * CLI and are deliberately not exposed: they spend the caller's money, and a tool
+ * an agent can invoke in a loop must not be able to do that. Everything below is
+ * arithmetic on text.
+ *
+ * *No writes.* The tools return figures. Applying them is the agent's job, in its
+ * own context, where a human can see the diff.
+ */
+
+/**
+ * The same cap the web API uses, for the same reason.
+ *
+ * An agent in a loop is exactly the caller that hands you a 40 MB string by
+ * accident. Refusing early with a number beats an unbounded pass over it.
+ */
+export const MAX_PROMPT_CHARS = 400_000;
+
+/** Every figure this server prints descends from the estimator, so it says so. */
+const BAND_NOTE =
+  'token counts are estimates (±15% on prose, calibrated on Claude); prices reviewed '
+  + PRICING_LAST_REVIEWED;
+
+function promptFrom(args: Record<string, unknown>): string {
+  const prompt = args.prompt;
+  if (typeof prompt !== 'string') throw new InvalidArguments('prompt must be a string');
+  if (prompt.length === 0) throw new InvalidArguments('prompt is empty');
+  if (prompt.length > MAX_PROMPT_CHARS) {
+    throw new InvalidArguments(
+      `prompt is ${prompt.length} characters, over the ${MAX_PROMPT_CHARS} limit`,
+    );
+  }
+  return prompt;
+}
+
+function levelFrom(args: Record<string, unknown>): RuleLevel {
+  const level = args.level ?? 'safe';
+  if (level !== 'safe' && level !== 'aggressive') {
+    throw new InvalidArguments('level must be "safe" or "aggressive"');
+  }
+  return level;
+}
+
+/**
+ * A positive integer, or the default.
+ *
+ * Written out rather than reached for from a validation library, and bounded on
+ * both ends: `callsPerMonth: 1e308` would otherwise produce an Infinity in
+ * somebody's budget, which is worse than a refusal because it looks like an
+ * answer.
+ */
+function intFrom(
+  args: Record<string, unknown>,
+  key: string,
+  fallback: number,
+  { min, max }: { min: number; max: number },
+): number {
+  const raw = args[key];
+  if (raw === undefined) return fallback;
+  if (typeof raw !== 'number' || !Number.isInteger(raw)) {
+    throw new InvalidArguments(`${key} must be an integer`);
+  }
+  if (raw < min || raw > max) {
+    throw new InvalidArguments(`${key} must be between ${min} and ${max}`);
+  }
+  return raw;
+}
+
+const PROMPT_PROPERTY = {
+  type: 'string',
+  minLength: 1,
+  maxLength: MAX_PROMPT_CHARS,
+  description: 'The prompt text itself. This server never reads files.',
+};
+
+const LEVEL_PROPERTY = {
+  type: 'string',
+  enum: ['safe', 'aggressive'],
+  default: 'safe',
+  description: 'safe leaves meaning untouched; aggressive also rewords, and wants reading',
+};
+
+const OPTIMIZE: ToolDefinition = {
+  name: 'optimize_prompt',
+  title: 'Optimise a prompt and price the difference',
+  description:
+    "Applies Trazum's deterministic rules to a prompt and returns the shorter text, the "
+    + 'token counts either side, what the difference is worth per month, and any advisories. '
+    + 'Offline and free: no model is called.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      prompt: PROMPT_PROPERTY,
+      level: LEVEL_PROPERTY,
+      model: {
+        type: 'string',
+        default: 'claude-opus-5',
+        description: 'Model id used for pricing. Call list_models for what is known.',
+      },
+      callsPerMonth: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 1_000_000_000,
+        default: 1000,
+        description: 'Used only to scale the figures',
+      },
+      avgOutputTokens: { type: 'integer', minimum: 0, maximum: 1_000_000, default: 500 },
+    },
+    required: ['prompt'],
+    additionalProperties: false,
+  },
+  run: (args) => {
+    const model = args.model ?? 'claude-opus-5';
+    if (typeof model !== 'string') throw new InvalidArguments('model must be a string');
+    const callsPerMonth = intFrom(args, 'callsPerMonth', 1000, { min: 1, max: 1_000_000_000 });
+    const avgOutputTokens = intFrom(args, 'avgOutputTokens', 500, { min: 0, max: 1_000_000 });
+
+    const result = optimize(promptFrom(args), {
+      level: levelFrom(args),
+      usage: { model, callsPerMonth, avgOutputTokens },
+    });
+
+    const lines = [
+      `tokens: ${result.tokensBefore} → ${result.tokensAfter}`
+        + ` (${result.tokensBefore - result.tokensAfter} fewer)`,
+      `monthly saving at ${callsPerMonth.toLocaleString('en-US')} calls:`
+        + ` ${formatUsd(result.savings.monthlySavingsUsd)}`,
+      BAND_NOTE,
+      '',
+      '--- optimised prompt ---',
+      result.optimized,
+    ];
+
+    if (result.advisories.length > 0) {
+      lines.push('', '--- advisories ---');
+      for (const advisory of result.advisories) {
+        const money =
+          advisory.estimatedMonthlyUsd === null
+            ? ''
+            : ` (~${formatUsd(advisory.estimatedMonthlyUsd)}/month)`;
+        lines.push(`[${advisory.id}] ${advisory.title}${money}`);
+      }
+    }
+
+    return lines.join('\n');
+  },
+};
+
+const CHECK: ToolDefinition = {
+  name: 'check_prompt',
+  title: 'Check a prompt against a token budget',
+  description:
+    'Answers whether a prompt fits a maximum, and if not, whether optimising it would. '
+    + 'This is the one to call before sending a prompt you are unsure about.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      prompt: PROMPT_PROPERTY,
+      maxTokens: {
+        type: 'integer',
+        minimum: 1,
+        description: 'The budget. Required: a check with no maximum is not a check.',
+      },
+      level: LEVEL_PROPERTY,
+    },
+    required: ['prompt', 'maxTokens'],
+    additionalProperties: false,
+  },
+  run: (args) => {
+    if (args.maxTokens === undefined) throw new InvalidArguments('maxTokens is required');
+    const maxTokens = intFrom(args, 'maxTokens', 0, { min: 1, max: Number.MAX_SAFE_INTEGER });
+    const level = levelFrom(args);
+    const result = optimize(promptFrom(args), { level });
+
+    /**
+     * Three outcomes, not two, and the third is why this tool exists.
+     *
+     * "Over budget" and "over budget but the rules would fix it" are different
+     * instructions to whoever asked: one means cut content, the other means run
+     * the rules. A boolean throws away the actionable half.
+     */
+    const verdict =
+      result.tokensBefore <= maxTokens
+        ? `PASS — ${result.tokensBefore} tokens, budget ${maxTokens}`
+        : result.tokensAfter <= maxTokens
+          ? `OVER BUDGET — ${result.tokensBefore} tokens against ${maxTokens}, but the ${level}`
+            + ` rules bring it to ${result.tokensAfter}, which fits. Optimise rather than cut.`
+          : `OVER BUDGET — ${result.tokensBefore} tokens against ${maxTokens}. Even optimised it`
+            + ` is ${result.tokensAfter}: content has to be cut.`;
+
+    return [
+      verdict,
+      'token counts are estimates (±15% on prose, calibrated on Claude), so a prompt within'
+        + ' a few percent of its budget should be treated as uncertain',
+    ].join('\n');
+  },
+};
+
+const MODELS: ToolDefinition = {
+  name: 'list_models',
+  title: 'Models Trazum can price, and their rates',
+  description:
+    'Input and output price per million tokens, context window and cacheable minimum, for '
+    + 'every model in the bundled catalogue.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  run: () => {
+    const rows = listModels().map((model) => {
+      const cache =
+        model.caching === 'none' || model.cacheMinTokens === null
+          ? 'no caching'
+          : `cache min ${model.cacheMinTokens}`;
+      return `${model.id}  in $${model.inputPerMTok}/Mtok  out $${model.outputPerMTok}/Mtok`
+        + `  context ${model.contextWindow.toLocaleString('en-US')}  ${cache}`;
+    });
+
+    return [
+      `prices reviewed ${BUNDLED_CATALOGUE.lastReviewed} — verify before budgeting`,
+      '',
+      ...rows,
+    ].join('\n');
+  },
+};
+
+/** The whole surface. An exact list, asserted as one by the tests. */
+export const TOOLS: readonly ToolDefinition[] = [OPTIMIZE, CHECK, MODELS];