@chrischall/mcp-utils 0.20.0 → 0.21.0

package/README.md

@@ -105,6 +105,48 @@ return textResult(flattenJsonApi(payload));   // collapse JSON:API envelopes
 deepMapStringField(payload, 'eventDate', dmyToIso);
 ```
 
+#### The `view` vocabulary — read tools answer in the cheap shape by default
+
+`VIEWS`, `DEFAULT_VIEW`, `View`, `viewParam`, `resolveView`, `viewResult`,
+`minifiedResult`, `projectOrRaw`. See `docs/fleet-conventions.md`
+("Response shape") for the convention these implement.
+
+`view: 'compact' | 'full' | 'raw'`, defaulting to **`compact`** — a projection
+that has to be requested is one that usually is not.
+
+```ts
+import { viewParam, resolveView, viewResult, projectOrRaw } from '@chrischall/mcp-utils';
+
+const VIEWS_HERE = ['compact', 'full'] as const;   // only the rungs you honour
+
+server.registerTool('svc_list_things', {
+  inputSchema: {
+    view: viewParam(VIEWS_HERE, { note: 'compact omits the upstream `meta` echo.' }),
+  },
+}, async (args) => {
+  const view = resolveView(args.view, VIEWS_HERE);
+  const rows = await client.list();
+  // Project the ARRAY, so one odd record cannot half-answer, and fall back to
+  // the whole payload (warning to stderr) if the upstream shape has drifted.
+  const items = view === 'compact'
+    ? projectOrRaw(rows, (rs) => rs.map(compactThing), { label: 'svc-mcp', context: 'GET /things' })
+    : rows;
+  return viewResult(view, { count: rows.length, items });
+});
+```
+
+`viewParam` refuses a rung list without `compact` (a tool with no cheap answer
+has nothing to default to) and refuses a single-rung list (a parameter that
+decides nothing). Register only the rungs you honour: `raw` is meaningless
+where a record is *assembled* from several endpoints rather than passed through
+from one, and a value that silently aliases to another is a lie in the schema.
+`raw` means "no projection" — never "no normalisation".
+
+`viewResult` minifies `compact` and `full` and leaves `raw` indented (that rung
+exists to be read by a person); `minifiedResult` is the same rule with no view
+to hand. Formatting whitespace only — whitespace *inside* a value is content
+and is never touched.
+
 ### `errors` — helpful errors
 
 `McpToolError` and its subclasses (`SessionNotAuthenticatedError`,

package/dist/response/index.d.ts

@@ -48,4 +48,5 @@ export declare function pruneUndefined<T extends Record<string, unknown>>(obj: T
  * rather than a 1-element array.
  */
 export declare function toArray<T>(value: T | T[] | null | undefined): T[];
+export * from './view.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/response/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAIzE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAIxD;AAED,sEAAsE;AACtE,eAAO,MAAM,UAAU,mBAAa,CAAC;AAErC,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAI5E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAoBxD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,CAAC,CAY5F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,EAAE,CAGjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAIzE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAIxD;AAED,sEAAsE;AACtE,eAAO,MAAM,UAAU,mBAAa,CAAC;AAErC,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAI5E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAoBxD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,CAAC,CAY5F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,EAAE,CAGjE;AACD,cAAc,WAAW,CAAC"}

package/dist/response/index.js

@@ -115,4 +115,5 @@ export function toArray(value) {
         return [];
     return Array.isArray(value) ? value : [value];
 }
+export * from './view.js';
 //# sourceMappingURL=index.js.map

package/dist/response/index.js.map

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

package/dist/response/view.d.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * The fleet's response-shape vocabulary (`docs/fleet-conventions.md`,
+ * "Response shape").
+ *
+ * Every tool that reads an upstream API answers in one of three shapes, and
+ * the CHEAP one is the default. That inversion is the whole point: five repos
+ * had already grown a projection by the time this was written, and four of
+ * them made it opt-in — `compact: false` in the schema, with the tool's own
+ * description asking the model to please pass `compact=true`. An efficiency
+ * that has to be requested is one that is usually not, and the caller paying
+ * for it is the one least able to know it was available.
+ *
+ * The rungs, in ascending order of size:
+ *
+ * - **compact** — the projection: the fields a caller acts on, with anything
+ *   the response already carries elsewhere removed. The default.
+ * - **full** — every field this MCP understands, nothing dropped.
+ * - **raw** — the upstream payload, unprojected.
+ *
+ * `raw` means "no projection". It NEVER means "no normalisation": a repo that
+ * rewrites values on the way out — timestamps into a single zone, ids into a
+ * stable shape — keeps doing so on every rung. Handing back the untouched wire
+ * format would reintroduce exactly the inconsistencies that normalisation
+ * exists to remove, on the one rung a caller reaches for when something
+ * already looks wrong.
+ *
+ * A tool registers only the rungs it can honour, so a schema never advertises
+ * a value that would silently alias to another: `raw` is meaningless where a
+ * record is ASSEMBLED from several endpoints rather than passed through from
+ * one, and those tools offer `compact` and `full` alone.
+ */
+export declare const VIEWS: readonly ["compact", "full", "raw"];
+/** One of {@link VIEWS}: the shape a read tool answers in. */
+export type View = (typeof VIEWS)[number];
+/** Efficiency is not something a caller should have to ask for. */
+export declare const DEFAULT_VIEW: View;
+/** Per-tool tuning for {@link viewParam}. */
+export interface ViewParamOptions {
+    /**
+     * What THIS tool's compact rung leaves out, in the tool's own words.
+     *
+     * Worth writing. The generic blurb says a projection happened; only the tool
+     * can say which field a caller who needs it should ask for `full` to get.
+     */
+    note?: string;
+}
+/**
+ * The `view` parameter, built from the rungs a tool actually honours.
+ *
+ * `view` rather than `detail`, `mode` or `compact`: `detail` is already an
+ * UPSTREAM passthrough in alltrails-mcp (`basic|medium|offline` goes into the
+ * URL), `mode` and `format` are taken elsewhere in the fleet, and `compact` as
+ * a boolean cannot express three rungs — nor say whether `compact: false`
+ * meant "everything you understand" or "everything you received".
+ */
+export declare function viewParam(honoured: readonly View[], opts?: ViewParamOptions): z.ZodOptional<z.ZodEnum<Record<string, string>>>;
+/**
+ * The rung to answer in. Absent means `compact`.
+ *
+ * The schema has already rejected anything this tool does not honour, so this
+ * is the second line — and it fails toward the CHEAP answer rather than
+ * throwing, because a caller that somehow named an unavailable rung is better
+ * served by a small correct response than by an error.
+ */
+export declare function resolveView(value: string | undefined, honoured: readonly View[]): View;
+/**
+ * A tool result with no formatting whitespace.
+ *
+ * `JSON.stringify(data, null, 2)` — the fleet's most duplicated line — spends
+ * roughly a fifth of a large response on indentation that carries no
+ * information and that nothing downstream reads: measured at 23% of a
+ * 135 KB ofw-mcp message page, or about 8,000 tokens per call.
+ *
+ * Only FORMATTING whitespace goes. Whitespace inside a value is content — the
+ * blank line between paragraphs of a message body, the indentation of a quoted
+ * block — and `JSON.stringify` leaves every byte of it alone, because it drops
+ * only the indent and the runs after `:` and `,`. Any hand-rolled alternative
+ * (a regex over the serialised text, a collapse of `\s+`) corrupts exactly the
+ * payloads this is meant to shrink. There are tests on that; do not replace
+ * this with something cleverer.
+ *
+ * Key ORDER is untouched too, which several repos depend on (ofw-mcp emits its
+ * paging state before its data array precisely so a truncated read still sees
+ * it).
+ */
+export declare function minifiedResult(data: unknown): CallToolResult;
+/**
+ * A tool result whose whitespace matches its rung: `compact` and `full` are
+ * minified, `raw` stays indented.
+ *
+ * The asymmetry is deliberate rather than an oversight. `compact` and `full`
+ * are consumed by a model, which reads the parse and not the layout. `raw` is
+ * the rung a person reaches for when a payload is not what they expected, and
+ * indentation is most of what makes an unfamiliar shape legible.
+ */
+export declare function viewResult(view: View, data: unknown): CallToolResult;
+/** Who is projecting what, for the stderr line {@link projectOrRaw} writes on a fallback. */
+export interface ProjectOptions {
+    /** The MCP's own name, for the stderr line. */
+    label: string;
+    /** Which call produced the value — the endpoint, usually. */
+    context: string;
+}
+/**
+ * Project a value, falling back to the RAW value if the projection fails.
+ *
+ * This is what makes compact-by-default survivable on a reverse-engineered
+ * API, and it is not optional. A projector names fields; upstream changes
+ * them; and the two failure modes that follow are an exception (loud, but it
+ * takes the whole tool call down) and an empty or half-filled record (silent,
+ * and indistinguishable from "there was nothing there") — which is the same
+ * false negative every absence-reporting guard in this fleet exists to
+ * prevent. So a projector that throws, or that returns nothing, hands back
+ * everything instead and says why on stderr.
+ *
+ * `undefined` counts as a failure. A projection legitimately has nothing to
+ * say only about a value that was already absent, and a caller cannot tell
+ * that from a projector that lost its footing.
+ */
+export declare function projectOrRaw<T, R>(value: T, project: (value: T) => R, opts: ProjectOptions): T | R;
+//# sourceMappingURL=view.d.ts.map

package/dist/response/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/response/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,KAAK,qCAAsC,CAAC;AAEzD,8DAA8D;AAC9D,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C,mEAAmE;AACnE,eAAO,MAAM,YAAY,EAAE,IAAgB,CAAC;AAQ5C,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,EAAE,IAAI,GAAE,gBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAmBlI;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,EAAE,GAAG,IAAI,CAEtF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,GAAG,cAAc,CAEpE;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,CAAC,GAAG,CAAC,CAYlG"}

package/dist/response/view.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+/**
+ * The fleet's response-shape vocabulary (`docs/fleet-conventions.md`,
+ * "Response shape").
+ *
+ * Every tool that reads an upstream API answers in one of three shapes, and
+ * the CHEAP one is the default. That inversion is the whole point: five repos
+ * had already grown a projection by the time this was written, and four of
+ * them made it opt-in — `compact: false` in the schema, with the tool's own
+ * description asking the model to please pass `compact=true`. An efficiency
+ * that has to be requested is one that is usually not, and the caller paying
+ * for it is the one least able to know it was available.
+ *
+ * The rungs, in ascending order of size:
+ *
+ * - **compact** — the projection: the fields a caller acts on, with anything
+ *   the response already carries elsewhere removed. The default.
+ * - **full** — every field this MCP understands, nothing dropped.
+ * - **raw** — the upstream payload, unprojected.
+ *
+ * `raw` means "no projection". It NEVER means "no normalisation": a repo that
+ * rewrites values on the way out — timestamps into a single zone, ids into a
+ * stable shape — keeps doing so on every rung. Handing back the untouched wire
+ * format would reintroduce exactly the inconsistencies that normalisation
+ * exists to remove, on the one rung a caller reaches for when something
+ * already looks wrong.
+ *
+ * A tool registers only the rungs it can honour, so a schema never advertises
+ * a value that would silently alias to another: `raw` is meaningless where a
+ * record is ASSEMBLED from several endpoints rather than passed through from
+ * one, and those tools offer `compact` and `full` alone.
+ */
+export const VIEWS = ['compact', 'full', 'raw'];
+/** Efficiency is not something a caller should have to ask for. */
+export const DEFAULT_VIEW = 'compact';
+const BLURB = {
+    compact: '"compact" (default) drops fields the response already carries elsewhere',
+    full: '"full" returns every field this server understands',
+    raw: '"raw" returns the upstream payload unprojected',
+};
+/**
+ * The `view` parameter, built from the rungs a tool actually honours.
+ *
+ * `view` rather than `detail`, `mode` or `compact`: `detail` is already an
+ * UPSTREAM passthrough in alltrails-mcp (`basic|medium|offline` goes into the
+ * URL), `mode` and `format` are taken elsewhere in the fleet, and `compact` as
+ * a boolean cannot express three rungs — nor say whether `compact: false`
+ * meant "everything you understand" or "everything you received".
+ */
+export function viewParam(honoured, opts = {}) {
+    if (honoured.length < 2) {
+        throw new Error('viewParam needs at least two rungs: a parameter offering one value decides nothing');
+    }
+    if (!honoured.includes('compact')) {
+        // A tool whose rungs are `full` and `raw` has no cheap answer at all,
+        // which is the shape this vocabulary exists to remove — not one it should
+        // help express.
+        throw new Error('viewParam must offer "compact": a tool with no cheap rung has nothing to default to');
+    }
+    const ordered = VIEWS.filter((v) => honoured.includes(v));
+    const sentence = `Response shape: ${ordered.map((v) => BLURB[v]).join('; ')}.`;
+    // `.describe()` LAST, after `.optional()`. Applied to the enum it lands on
+    // the inner type, and the wrapper an MCP host actually reads its description
+    // off comes back blank — a parameter documented to nobody.
+    return z
+        .enum(Object.fromEntries(ordered.map((v) => [v, v])))
+        .optional()
+        .describe(opts.note ? `${sentence} ${opts.note}` : sentence);
+}
+/**
+ * The rung to answer in. Absent means `compact`.
+ *
+ * The schema has already rejected anything this tool does not honour, so this
+ * is the second line — and it fails toward the CHEAP answer rather than
+ * throwing, because a caller that somehow named an unavailable rung is better
+ * served by a small correct response than by an error.
+ */
+export function resolveView(value, honoured) {
+    return value !== undefined && honoured.includes(value) ? value : DEFAULT_VIEW;
+}
+/**
+ * A tool result with no formatting whitespace.
+ *
+ * `JSON.stringify(data, null, 2)` — the fleet's most duplicated line — spends
+ * roughly a fifth of a large response on indentation that carries no
+ * information and that nothing downstream reads: measured at 23% of a
+ * 135 KB ofw-mcp message page, or about 8,000 tokens per call.
+ *
+ * Only FORMATTING whitespace goes. Whitespace inside a value is content — the
+ * blank line between paragraphs of a message body, the indentation of a quoted
+ * block — and `JSON.stringify` leaves every byte of it alone, because it drops
+ * only the indent and the runs after `:` and `,`. Any hand-rolled alternative
+ * (a regex over the serialised text, a collapse of `\s+`) corrupts exactly the
+ * payloads this is meant to shrink. There are tests on that; do not replace
+ * this with something cleverer.
+ *
+ * Key ORDER is untouched too, which several repos depend on (ofw-mcp emits its
+ * paging state before its data array precisely so a truncated read still sees
+ * it).
+ */
+export function minifiedResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+}
+/**
+ * A tool result whose whitespace matches its rung: `compact` and `full` are
+ * minified, `raw` stays indented.
+ *
+ * The asymmetry is deliberate rather than an oversight. `compact` and `full`
+ * are consumed by a model, which reads the parse and not the layout. `raw` is
+ * the rung a person reaches for when a payload is not what they expected, and
+ * indentation is most of what makes an unfamiliar shape legible.
+ */
+export function viewResult(view, data) {
+    return view === 'raw' ? { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] } : minifiedResult(data);
+}
+/**
+ * Project a value, falling back to the RAW value if the projection fails.
+ *
+ * This is what makes compact-by-default survivable on a reverse-engineered
+ * API, and it is not optional. A projector names fields; upstream changes
+ * them; and the two failure modes that follow are an exception (loud, but it
+ * takes the whole tool call down) and an empty or half-filled record (silent,
+ * and indistinguishable from "there was nothing there") — which is the same
+ * false negative every absence-reporting guard in this fleet exists to
+ * prevent. So a projector that throws, or that returns nothing, hands back
+ * everything instead and says why on stderr.
+ *
+ * `undefined` counts as a failure. A projection legitimately has nothing to
+ * say only about a value that was already absent, and a caller cannot tell
+ * that from a projector that lost its footing.
+ */
+export function projectOrRaw(value, project, opts) {
+    try {
+        const projected = project(value);
+        if (projected === undefined) {
+            warn(opts, 'the projection produced nothing');
+            return value;
+        }
+        return projected;
+    }
+    catch (error) {
+        warn(opts, error instanceof Error ? error.message : String(error));
+        return value;
+    }
+}
+function warn(opts, why) {
+    console.error(`[${opts.label}] WARNING: could not project ${opts.context} (${why}); returning the unprojected payload. ` +
+        'The upstream shape has probably changed — the projection needs updating.');
+}
+//# sourceMappingURL=view.js.map

package/dist/response/view.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-utils",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
   "type": "module",
   "license": "MIT",