@lobstack-ai/mcp 0.1.0

package/dist/tools/chat.js

@@ -0,0 +1,177 @@
+/**
+ * lobstack_chat — one completion, and what it cost.
+ *
+ * WHY THIS STREAMS WHEN NOTHING IS STREAMED TO
+ *
+ * An MCP tool result is a single message; there is no partial delivery to an
+ * agent mid-call. So the whole answer is accumulated here before it is
+ * returned, and `stream: true` looks pointless.
+ *
+ * It is not. On the buffered path the Gateway reports the price in response
+ * HEADERS, and on the streamed path it reports it in the trailing SSE frame as
+ * `x_lobstack`. The frame is the better source: the streaming path meters
+ * *before* emitting that frame, so the figure is the ledger's, not an estimate,
+ * and it arrives as one structured object rather than eight headers, three of
+ * which encode "unpriced" as an empty string. Requesting SSE and reading it to
+ * the end is how this tool returns a receipt it did not compute itself.
+ *
+ * `stream_options.include_usage` is not optional: without it the Gateway has no
+ * trailing frame to attach `x_lobstack` to, and the price never arrives.
+ */
+import { z } from "zod";
+import { gatewayUrl } from "../config.js";
+import { gwFetch, errorFrom, quotaFromHeaders, describeQuota } from "../gateway.js";
+import { consume } from "../sse.js";
+import { describeReceipt, money, parseReceipt, savingsLabel } from "../receipt.js";
+import { baseNote, droppedParams, failure, fromThrown, ok, requireKey } from "./shared.js";
+const Message = z.object({
+    role: z.enum(["system", "user", "assistant"]),
+    content: z.string(),
+});
+export const chatInput = {
+    prompt: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A single user message. Use this or `messages`, not both."),
+    messages: z
+        .array(Message)
+        .min(1)
+        .optional()
+        .describe("A full conversation, OpenAI-shaped. Use this or `prompt`, not both."),
+    model: z
+        .string()
+        .optional()
+        .describe('Lobstack model key, e.g. "claude-sonnet-5". Defaults to "auto", which lets Token Intelligence pick the cheapest model that can handle the prompt. lobstack_models lists the keys.'),
+    system: z.string().optional().describe("System prompt, prepended to the conversation."),
+    max_tokens: z.number().int().positive().max(200_000).optional().describe("Cap on the reply length."),
+    temperature: z
+        .number()
+        .min(0)
+        .max(2)
+        .optional()
+        .describe("Sampling temperature. Some served models do not accept it; the receipt says when it was dropped."),
+};
+export const chatOutput = {
+    text: z.string().describe("The assistant's reply."),
+    model: z.object({
+        requested: z.string().nullable(),
+        served: z.string().nullable().describe("The model that actually answered."),
+        routed: z.boolean().nullable().describe("True when the served model differs from the one requested."),
+    }),
+    usage: z
+        .object({ prompt_tokens: z.number(), completion_tokens: z.number(), total_tokens: z.number() })
+        .nullable(),
+    receipt: z
+        .object({
+        request_id: z.string().nullable(),
+        cost_usd: z
+            .number()
+            .nullable()
+            .describe("USD the caller owes. NULL — never 0 — when the gateway could not price the call."),
+        cost_display: z.string().describe('Human form. "unpriced" when cost_usd is null.'),
+        priced: z.boolean(),
+        savings: z
+            .object({
+            amount_usd: z.number(),
+            label: z.string().describe('"saved" for a like-for-like comparison, "vs ceiling" otherwise.'),
+            named: z
+                .boolean()
+                .describe("True only when the caller asked for baseline_model and got something cheaper."),
+            baseline_model: z.string().nullable(),
+            baseline_reason: z.string().nullable(),
+        })
+            .nullable(),
+    })
+        .nullable()
+        .describe("Null when the endpoint sent no receipt at all."),
+    quota: z.record(z.unknown()).nullable().describe("Allowance remaining, as the gateway reported it."),
+    dropped_params: z.array(z.string()),
+};
+export async function runChat(cfg, args) {
+    const missing = requireKey(cfg);
+    if (missing)
+        return missing;
+    if (!args.prompt && !args.messages?.length) {
+        return failure(cfg, "Give either `prompt` (a single message) or `messages` (a conversation).");
+    }
+    if (args.prompt && args.messages?.length) {
+        return failure(cfg, "Give either `prompt` or `messages`, not both — it is ambiguous which one to send.");
+    }
+    const messages = [
+        ...(args.system ? [{ role: "system", content: args.system }] : []),
+        ...(args.messages ?? [{ role: "user", content: args.prompt }]),
+    ];
+    const requestedModel = args.model?.trim() || "auto";
+    try {
+        const res = await gwFetch(cfg, gatewayUrl(cfg.base.origin, "/chat/completions"), {
+            method: "POST",
+            body: JSON.stringify({
+                model: requestedModel,
+                messages,
+                stream: true,
+                // Without this there is no trailing frame, and so no price.
+                stream_options: { include_usage: true },
+                ...(args.max_tokens !== undefined ? { max_tokens: args.max_tokens } : {}),
+                ...(args.temperature !== undefined ? { temperature: args.temperature } : {}),
+            }),
+        });
+        if (!res.ok || !res.body) {
+            throw await errorFrom(cfg, res, res.status === 402
+                ? "The allowance on this key is exhausted. Top up or wait for the reset in Console → Billing."
+                : res.status === 403
+                    ? 'This key needs the "inference" scope. Mint one in Console → API keys.'
+                    : undefined);
+        }
+        const quota = quotaFromHeaders(res.headers);
+        const dropped = droppedParams(res.headers);
+        const stream = await consume(res.body);
+        const receipt = parseReceipt(stream.receipt);
+        const saving = savingsLabel(receipt);
+        const structured = {
+            text: stream.text,
+            model: {
+                requested: receipt?.requested_model ?? requestedModel,
+                served: receipt?.served_model ?? stream.model,
+                routed: receipt?.routed ?? null,
+            },
+            usage: stream.usage,
+            receipt: receipt
+                ? {
+                    request_id: receipt.request_id,
+                    // Null stays null all the way out. A consumer that wants a number
+                    // has to decide for itself what "we could not price this" means.
+                    cost_usd: receipt.cost_usd,
+                    cost_display: money(receipt.cost_usd),
+                    priced: receipt.priced,
+                    savings: saving
+                        ? {
+                            amount_usd: saving.amount,
+                            label: saving.label,
+                            named: saving.named,
+                            baseline_model: saving.baseline_model,
+                            baseline_reason: saving.baseline_reason,
+                        }
+                        : null,
+                }
+                : null,
+            quota: quota ? quota : null,
+            dropped_params: dropped,
+        };
+        // Two blocks, not one. The answer is the thing that was asked for; the
+        // receipt is a fact about the call. Concatenating them puts a price line
+        // into whatever consumes the answer — the same reason the CLI puts the
+        // receipt on stderr.
+        const receiptBlock = [
+            describeReceipt({ receipt, usage: stream.usage, model: stream.model, droppedParams: dropped }),
+            describeQuota(quota),
+            baseNote(cfg),
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return ok([stream.text, receiptBlock], structured);
+    }
+    catch (e) {
+        return fromThrown(cfg, e);
+    }
+}

package/dist/tools/models.d.ts

@@ -0,0 +1,56 @@
+/**
+ * lobstack_models — the catalogue, with prices.
+ *
+ * `GET /api/gateway/v1/models` is OpenAI-shaped with Lobstack extensions on
+ * each row: `tier`, `context_window`, `price_per_mtok` and `managed`. It takes
+ * no credential on lobstack.ai, and this tool sends one only if the server was
+ * given one — a self-hosted deployment is entitled to put auth in front of it.
+ *
+ * A model whose price the registry does not know arrives with an empty or
+ * partial `price_per_mtok`. It is rendered as "—", never as "$0": a catalogue
+ * that shows an unpriced model as free teaches the reader that some of our
+ * routing is free, which is the same lie as a $0.00 receipt one layer up.
+ */
+import { z } from "zod";
+import type { Config } from "../config.js";
+import { type ToolResult } from "./shared.js";
+export declare const modelsInput: {
+    tier: z.ZodOptional<z.ZodEnum<["nano", "small", "standard", "premium", "flagship"]>>;
+    provider: z.ZodOptional<z.ZodString>;
+};
+export declare const modelsOutput: {
+    count: z.ZodNumber;
+    unpriced_count: z.ZodNumber;
+    models: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        tier: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        context_window: z.ZodNullable<z.ZodNumber>;
+        input_usd_per_mtok: z.ZodNullable<z.ZodNumber>;
+        output_usd_per_mtok: z.ZodNullable<z.ZodNumber>;
+        managed: z.ZodNullable<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        label: string | null;
+        id: string;
+        tier: string | null;
+        provider: string | null;
+        context_window: number | null;
+        input_usd_per_mtok: number | null;
+        output_usd_per_mtok: number | null;
+        managed: boolean | null;
+    }, {
+        label: string | null;
+        id: string;
+        tier: string | null;
+        provider: string | null;
+        context_window: number | null;
+        input_usd_per_mtok: number | null;
+        output_usd_per_mtok: number | null;
+        managed: boolean | null;
+    }>, "many">;
+};
+export declare function runModels(cfg: Config, args: {
+    tier?: string;
+    provider?: string;
+}): Promise<ToolResult>;

package/dist/tools/models.js

@@ -0,0 +1,90 @@
+/**
+ * lobstack_models — the catalogue, with prices.
+ *
+ * `GET /api/gateway/v1/models` is OpenAI-shaped with Lobstack extensions on
+ * each row: `tier`, `context_window`, `price_per_mtok` and `managed`. It takes
+ * no credential on lobstack.ai, and this tool sends one only if the server was
+ * given one — a self-hosted deployment is entitled to put auth in front of it.
+ *
+ * A model whose price the registry does not know arrives with an empty or
+ * partial `price_per_mtok`. It is rendered as "—", never as "$0": a catalogue
+ * that shows an unpriced model as free teaches the reader that some of our
+ * routing is free, which is the same lie as a $0.00 receipt one layer up.
+ */
+import { z } from "zod";
+import { gatewayUrl } from "../config.js";
+import { errorFrom, gwFetch } from "../gateway.js";
+import { asMoney } from "../receipt.js";
+import { baseNote, fromThrown, ok } from "./shared.js";
+const TIERS = ["nano", "small", "standard", "premium", "flagship"];
+export const modelsInput = {
+    tier: z
+        .enum(TIERS)
+        .optional()
+        .describe("Only models in this capability tier. Token Intelligence walks these from cheapest upward."),
+    provider: z
+        .string()
+        .optional()
+        .describe('Only models from this provider, e.g. "anthropic", "openai", "google".'),
+};
+const ModelRow = z.object({
+    id: z.string(),
+    label: z.string().nullable(),
+    tier: z.string().nullable(),
+    provider: z.string().nullable(),
+    context_window: z.number().nullable(),
+    input_usd_per_mtok: z.number().nullable().describe("Null when the registry cannot price this model."),
+    output_usd_per_mtok: z.number().nullable(),
+    managed: z.boolean().nullable(),
+});
+export const modelsOutput = {
+    count: z.number(),
+    unpriced_count: z.number().describe("Models the registry could not price. Their prices are null, not zero."),
+    models: z.array(ModelRow),
+};
+const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
+const priceCell = (v) => (v === null ? "—" : `$${v}`);
+export async function runModels(cfg, args) {
+    try {
+        const res = await gwFetch(cfg, gatewayUrl(cfg.base.origin, "/models"));
+        if (!res.ok)
+            throw await errorFrom(cfg, res);
+        const body = (await res.json());
+        const all = (body.data ?? []).map((m) => ({
+            id: String(m.id ?? ""),
+            label: m.label ?? null,
+            tier: m.tier ?? null,
+            provider: m.owned_by ?? null,
+            context_window: typeof m.context_window === "number" ? m.context_window : null,
+            input_usd_per_mtok: asMoney(m.price_per_mtok?.input),
+            output_usd_per_mtok: asMoney(m.price_per_mtok?.output),
+            managed: typeof m.managed === "boolean" ? m.managed : null,
+        }));
+        const rows = all.filter((m) => (!args.tier || m.tier === args.tier) &&
+            (!args.provider || (m.provider ?? "").toLowerCase() === args.provider.toLowerCase()));
+        const unpriced = rows.filter((m) => m.input_usd_per_mtok === null || m.output_usd_per_mtok === null).length;
+        const w = Math.max(5, ...rows.map((m) => m.id.length));
+        const lines = [
+            `${pad("MODEL", w)}  ${pad("TIER", 9)}  ${pad("PROVIDER", 10)}  ${pad("IN/Mtok", 9)}  OUT/Mtok`,
+            ...rows.map((m) => `${pad(m.id, w)}  ${pad(m.tier ?? "—", 9)}  ${pad(m.provider ?? "—", 10)}  ` +
+                `${pad(priceCell(m.input_usd_per_mtok), 9)}  ${priceCell(m.output_usd_per_mtok)}`),
+        ];
+        const footer = [
+            "",
+            `${rows.length} model${rows.length === 1 ? "" : "s"}${rows.length !== all.length ? ` of ${all.length}` : ""}. ` +
+                'Send model "auto" to lobstack_chat and the router picks one, then tells you which.',
+            unpriced ? `${unpriced} of them carry no price in the registry; they are shown as — and are not free.` : null,
+            baseNote(cfg),
+        ]
+            .filter((l) => l !== null)
+            .join("\n");
+        return ok([lines.join("\n") + "\n" + footer], {
+            count: rows.length,
+            unpriced_count: unpriced,
+            models: rows,
+        });
+    }
+    catch (e) {
+        return fromThrown(cfg, e);
+    }
+}

package/dist/tools/route-preview.d.ts

@@ -0,0 +1,75 @@
+/**
+ * lobstack_route_preview — where a prompt would go, and what it would cost,
+ * without spending a token and without a key.
+ *
+ * `POST /api/gateway/v1/route-preview` is unauthenticated on purpose: it runs
+ * no inference, calls no provider, writes nothing and reads no per-user state.
+ * It runs the same `selectModel()` and the same price registry the paid path
+ * uses, so the answer is the decision rather than a simulation of it.
+ *
+ * This tool therefore sends NO Authorization header — `anonymous: true` below.
+ * That is not an oversight, it is the point: an MCP client with this server
+ * installed and no key at all can still answer "which model would this go to
+ * and what would it cost", which is the whole product visible before anybody
+ * signs up.
+ *
+ * Two honesty constraints carried over from the endpoint.
+ *
+ * Token counts are ESTIMATES — roughly four characters per token, with output
+ * assumed at half the prompt unless the caller says otherwise. The response
+ * says so in `token_estimate.estimated` and so does the text here. The billed
+ * figure always comes from the provider's own usage block on the real call.
+ *
+ * `baseline` exists only when the caller named a model and the router went
+ * somewhere else. On "auto" it is null, because there is no model anybody asked
+ * for to compare against, and inventing one — against the flagship, say — is
+ * how every savings claim in this category gets manufactured.
+ */
+import { z } from "zod";
+import type { Config } from "../config.js";
+import { type ToolResult } from "./shared.js";
+export declare const routePreviewInput: {
+    prompt: z.ZodString;
+    requested_model: z.ZodOptional<z.ZodString>;
+    plan_tier: z.ZodOptional<z.ZodString>;
+    expected_output_tokens: z.ZodOptional<z.ZodNumber>;
+    conversation_length: z.ZodOptional<z.ZodNumber>;
+};
+export declare const routePreviewOutput: {
+    requested_model: z.ZodString;
+    served_model: z.ZodString;
+    served_label: z.ZodNullable<z.ZodString>;
+    provider: z.ZodNullable<z.ZodString>;
+    tier: z.ZodNullable<z.ZodString>;
+    complexity: z.ZodNullable<z.ZodNumber>;
+    routed: z.ZodNullable<z.ZodBoolean>;
+    reason: z.ZodNullable<z.ZodString>;
+    estimated_cost_usd: z.ZodNullable<z.ZodNumber>;
+    estimated_cost_display: z.ZodString;
+    token_estimate: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    baseline: z.ZodNullable<z.ZodObject<{
+        model: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        cost_usd: z.ZodNullable<z.ZodNumber>;
+        saving_usd: z.ZodNullable<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        cost_usd: number | null;
+        label: string | null;
+        saving_usd: number | null;
+    }, {
+        model: string;
+        cost_usd: number | null;
+        label: string | null;
+        saving_usd: number | null;
+    }>>;
+    managed_key_configured: z.ZodNullable<z.ZodBoolean>;
+    estimated: z.ZodLiteral<true>;
+};
+export declare function runRoutePreview(cfg: Config, args: {
+    prompt: string;
+    requested_model?: string;
+    plan_tier?: string;
+    expected_output_tokens?: number;
+    conversation_length?: number;
+}): Promise<ToolResult>;

package/dist/tools/route-preview.js

@@ -0,0 +1,155 @@
+/**
+ * lobstack_route_preview — where a prompt would go, and what it would cost,
+ * without spending a token and without a key.
+ *
+ * `POST /api/gateway/v1/route-preview` is unauthenticated on purpose: it runs
+ * no inference, calls no provider, writes nothing and reads no per-user state.
+ * It runs the same `selectModel()` and the same price registry the paid path
+ * uses, so the answer is the decision rather than a simulation of it.
+ *
+ * This tool therefore sends NO Authorization header — `anonymous: true` below.
+ * That is not an oversight, it is the point: an MCP client with this server
+ * installed and no key at all can still answer "which model would this go to
+ * and what would it cost", which is the whole product visible before anybody
+ * signs up.
+ *
+ * Two honesty constraints carried over from the endpoint.
+ *
+ * Token counts are ESTIMATES — roughly four characters per token, with output
+ * assumed at half the prompt unless the caller says otherwise. The response
+ * says so in `token_estimate.estimated` and so does the text here. The billed
+ * figure always comes from the provider's own usage block on the real call.
+ *
+ * `baseline` exists only when the caller named a model and the router went
+ * somewhere else. On "auto" it is null, because there is no model anybody asked
+ * for to compare against, and inventing one — against the flagship, say — is
+ * how every savings claim in this category gets manufactured.
+ */
+import { z } from "zod";
+import { gatewayUrl } from "../config.js";
+import { errorFrom, gwFetch } from "../gateway.js";
+import { asMoney, money } from "../receipt.js";
+import { baseNote, fromThrown, ok } from "./shared.js";
+export const routePreviewInput = {
+    prompt: z.string().min(1).max(8000).describe("The prompt to score. Scored, never sent to a model."),
+    requested_model: z
+        .string()
+        .optional()
+        .describe('A model key to compare against, e.g. "claude-opus-5". Defaults to "auto".'),
+    plan_tier: z
+        .string()
+        .optional()
+        .describe("Plan id, which sets the ceiling the router may reach. Defaults to the pro ceiling."),
+    expected_output_tokens: z
+        .number()
+        .int()
+        .positive()
+        .max(200_000)
+        .optional()
+        .describe("How long the reply is expected to be. Defaults to half the prompt, which is the common chat ratio."),
+    conversation_length: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Messages already in the conversation; it feeds the complexity score."),
+};
+export const routePreviewOutput = {
+    requested_model: z.string(),
+    served_model: z.string().describe("The model this prompt would actually be routed to."),
+    served_label: z.string().nullable(),
+    provider: z.string().nullable(),
+    tier: z.string().nullable(),
+    complexity: z.number().nullable(),
+    routed: z.boolean().nullable().describe("True when the router would serve something other than what was requested."),
+    reason: z.string().nullable(),
+    estimated_cost_usd: z.number().nullable().describe("Null when the registry cannot price the model."),
+    estimated_cost_display: z.string(),
+    token_estimate: z.record(z.unknown()).nullable(),
+    baseline: z
+        .object({
+        model: z.string(),
+        label: z.string().nullable(),
+        cost_usd: z.number().nullable(),
+        saving_usd: z.number().nullable(),
+    })
+        .nullable()
+        .describe('Only present when a model was named and the router moved away from it — the "named" case.'),
+    managed_key_configured: z.boolean().nullable(),
+    estimated: z.literal(true).describe("Always true. These are estimates, not a bill."),
+};
+export async function runRoutePreview(cfg, args) {
+    try {
+        const res = await gwFetch(cfg, gatewayUrl(cfg.base.origin, "/route-preview"), {
+            method: "POST",
+            // No credential. This endpoint needs none, and sending one anyway would
+            // turn a public demonstration into an authenticated call for no reason.
+            anonymous: true,
+            body: JSON.stringify({
+                prompt: args.prompt,
+                ...(args.requested_model ? { requested_model: args.requested_model } : {}),
+                ...(args.plan_tier ? { plan_tier: args.plan_tier } : {}),
+                ...(args.expected_output_tokens ? { expected_output_tokens: args.expected_output_tokens } : {}),
+                ...(args.conversation_length !== undefined ? { conversation_length: args.conversation_length } : {}),
+            }),
+        });
+        if (!res.ok)
+            throw await errorFrom(cfg, res);
+        const b = (await res.json());
+        const cost = asMoney(b.cost_usd);
+        const served = b.model?.key ?? "unknown";
+        const baselineCost = asMoney(b.baseline?.cost_usd);
+        const baselineSaving = asMoney(b.baseline?.saving_usd);
+        const structured = {
+            requested_model: b.requested_model ?? args.requested_model ?? "auto",
+            served_model: served,
+            served_label: b.model?.label ?? null,
+            provider: b.model?.provider ?? null,
+            tier: b.tier ?? null,
+            complexity: typeof b.complexity === "number" ? b.complexity : null,
+            routed: typeof b.routed === "boolean" ? b.routed : null,
+            reason: b.reason ?? null,
+            estimated_cost_usd: cost,
+            estimated_cost_display: money(cost),
+            token_estimate: b.token_estimate ?? null,
+            baseline: b.baseline?.model
+                ? {
+                    model: b.baseline.model,
+                    label: b.baseline.label ?? null,
+                    cost_usd: baselineCost,
+                    saving_usd: baselineSaving,
+                }
+                : null,
+            managed_key_configured: b.model?.managed_key_configured ?? null,
+            estimated: true,
+        };
+        const est = b.token_estimate;
+        const lines = [
+            `This prompt would be served by ${served}${b.model?.label ? ` (${b.model.label})` : ""}` +
+                `${b.tier ? `, ${b.tier} tier` : ""}${b.model?.provider ? `, via ${b.model.provider}` : ""}.`,
+            b.reason ? `  why: ${b.reason}${typeof b.complexity === "number" ? ` (complexity ${b.complexity})` : ""}` : null,
+            `  estimated cost ${money(cost)}` +
+                (est?.input !== undefined ? ` on ~${est.input} in / ~${est.output} out tokens` : ""),
+            // A saving is only ever quoted here for a model the caller named. The
+            // endpoint returns null on "auto" for exactly that reason.
+            structured.baseline && baselineSaving !== null && baselineSaving > 0
+                ? `  ${money(baselineSaving)} cheaper than ${structured.baseline.model}, which you named` +
+                    (baselineCost !== null ? ` and which would have cost ${money(baselineCost)}` : "")
+                : null,
+            b.model?.managed_key_configured === false
+                ? `  note: no managed provider key for ${b.model?.provider ?? "this provider"} is configured on this deployment, so a real call may route elsewhere`
+                : null,
+            "",
+            `  Estimated, not billed. ${est?.method ? `Tokens: ${est.method}. ` : ""}` +
+                "The charged figure comes from the provider's own usage block on the real request.",
+            "  This preview needs no API key.",
+            baseNote(cfg),
+        ]
+            .filter((l) => l !== null)
+            .join("\n");
+        return ok([lines], structured);
+    }
+    catch (e) {
+        return fromThrown(cfg, e);
+    }
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turning a failure into something an agent can act on.
+ *
+ * Every tool in this repo answers a failure the same way: `isError: true` with
+ * a sentence and, where there is one, a next step. Not a thrown McpError —
+ * a protocol-level error tells the client the call was malformed, which is a
+ * different claim from "your key lacks a scope", and clients surface the two
+ * very differently.
+ *
+ * Everything that goes through here is scrubbed. The key is in this process's
+ * environment and nowhere else; it must not turn up in a tool result, which is
+ * transcript, which is context, which is somewhere it will be read.
+ */
+import { type Config } from "../config.js";
+export interface ToolResult {
+    /** The SDK's CallToolResult is open-ended; this keeps us assignable to it. */
+    [x: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export declare const text: (...blocks: Array<string | null | undefined>) => Array<{
+    type: "text";
+    text: string;
+}>;
+export declare function ok(blocks: Array<string | null | undefined>, structured: Record<string, unknown>): ToolResult;
+export declare function failure(cfg: Config, message: string, hint?: string): ToolResult;
+/** The message for a tool that needs a credential and has not been given one. */
+export declare function requireKey(cfg: Config): ToolResult | null;
+/** Turn any thrown thing into a tool result, with the key removed. */
+export declare function fromThrown(cfg: Config, e: unknown): ToolResult;
+/** `x-lobstack-dropped-params`, split. Empty when the header is absent. */
+export declare function droppedParams(h: Headers): string[];
+/** A note about the apex rewrite, wherever a base URL was used. */
+export declare function baseNote(cfg: Config): string | null;

package/dist/tools/shared.js

@@ -0,0 +1,64 @@
+/**
+ * Turning a failure into something an agent can act on.
+ *
+ * Every tool in this repo answers a failure the same way: `isError: true` with
+ * a sentence and, where there is one, a next step. Not a thrown McpError —
+ * a protocol-level error tells the client the call was malformed, which is a
+ * different claim from "your key lacks a scope", and clients surface the two
+ * very differently.
+ *
+ * Everything that goes through here is scrubbed. The key is in this process's
+ * environment and nowhere else; it must not turn up in a tool result, which is
+ * transcript, which is context, which is somewhere it will be read.
+ */
+import { ConfigError, scrub } from "../config.js";
+import { GatewayError } from "../gateway.js";
+import { StreamError } from "../sse.js";
+export const text = (...blocks) => blocks.filter((b) => typeof b === "string" && b.length > 0).map((t) => ({ type: "text", text: t }));
+export function ok(blocks, structured) {
+    return { content: text(...blocks), structuredContent: structured };
+}
+export function failure(cfg, message, hint) {
+    const body = hint ? `${scrub(message, cfg.apiKey)}\n\n${scrub(hint, cfg.apiKey)}` : scrub(message, cfg.apiKey);
+    return { content: text(body), isError: true };
+}
+/** The message for a tool that needs a credential and has not been given one. */
+export function requireKey(cfg) {
+    if (cfg.apiKey)
+        return null;
+    return failure(cfg, "No Lobstack API key is configured, so this call cannot be made.", "Set LOBSTACK_API_KEY in this server's environment (mint a key in Console → API keys) and restart the MCP client. " +
+        "lobstack_route_preview needs no key and works right now.");
+}
+/** Turn any thrown thing into a tool result, with the key removed. */
+export function fromThrown(cfg, e) {
+    if (e instanceof GatewayError) {
+        const hints = [];
+        if (e.hint)
+            hints.push(e.hint);
+        if (e.status === 401) {
+            hints.push(cfg.keyShapeUnrecognised
+                ? "LOBSTACK_API_KEY is set but is not shaped like a Lobstack API key (lsk_live_… or lsk_test_…). Check it was copied whole."
+                : "The key was rejected. It may have been revoked or have expired; mint a new one in Console → API keys.");
+        }
+        if (e.requestId)
+            hints.push(`Gateway request id: ${e.requestId}`);
+        return failure(cfg, e.message, hints.join("\n"));
+    }
+    if (e instanceof ConfigError)
+        return failure(cfg, e.message, e.hint);
+    if (e instanceof StreamError) {
+        return failure(cfg, `the gateway failed part-way through the answer: ${e.message}`);
+    }
+    return failure(cfg, e instanceof Error ? e.message : String(e));
+}
+/** `x-lobstack-dropped-params`, split. Empty when the header is absent. */
+export function droppedParams(h) {
+    const raw = h.get("x-lobstack-dropped-params");
+    return raw ? raw.split(",").map((s) => s.trim()).filter(Boolean) : [];
+}
+/** A note about the apex rewrite, wherever a base URL was used. */
+export function baseNote(cfg) {
+    return cfg.base.corrected
+        ? `  note: the bare apex lobstack.ai redirects and would strip your key; ${cfg.base.origin} was used instead`
+        : null;
+}