@chrischall/mcp-utils 0.1.0

package/dist/test/index.js

@@ -0,0 +1,181 @@
+/**
+ * `@chrischall/mcp-utils/test` — the in-memory vitest harness shared by every
+ * MCP in the fleet. Devtime-only: this subpath pulls test scaffolding and is
+ * never imported by runtime server code.
+ *
+ * It consolidates four copy-pasted pieces from ~19 sibling repos:
+ *  - `createTestHarness` / `parseToolResult` — a connected `McpServer` + `Client`
+ *    pair over `InMemoryTransport`, plus the trivial JSON-body extractor.
+ *  - `versionSyncTest` — the release-please drift guard (`x-release-please-version`
+ *    annotations vs `package.json#version`).
+ *  - `mockFetchproxyBootstrap` / `setupClientMocks` — mock `@fetchproxy/bootstrap`
+ *    at the module boundary and spy an API client's request methods.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { vi } from 'vitest';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+/**
+ * Create a connected `McpServer` + `Client` pair wired over
+ * `InMemoryTransport`. The byte-identical helper every MCP's `tests/helpers.ts`
+ * defines — register your tools, then drive them through the real client RPC
+ * path (schema validation, content envelopes, isError, and all).
+ */
+export async function createTestHarness(registerFn) {
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    await registerFn(server);
+    const client = new Client({ name: 'test-client', version: '0.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    let closed = false;
+    return {
+        client,
+        server,
+        callTool: (name, args) => client.callTool({ name, arguments: args ?? {} }),
+        listTools: async () => {
+            const result = await client.listTools();
+            return result.tools.map((t) => ({ name: t.name }));
+        },
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await client.close();
+            await server.close();
+        },
+    };
+}
+/**
+ * Parse the JSON body out of a tool's `CallToolResult`. Fleet tools return a
+ * single text block of `JSON.stringify(data, null, 2)`; this is the inverse.
+ * Throws a contextual error (rather than a bare `TypeError`/`SyntaxError`) when
+ * the result is empty, non-text, or not valid JSON — those are the test
+ * failures you actually want to read.
+ */
+export function parseToolResult(result) {
+    const block = result.content?.[0];
+    if (!block || block.type !== 'text' || typeof block.text !== 'string') {
+        throw new Error(`parseToolResult: result has no text content block (got ${block ? `type='${block.type}'` : 'empty content'})`);
+    }
+    try {
+        return JSON.parse(block.text);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`parseToolResult: text block is not valid JSON (${reason}): ${block.text}`);
+    }
+}
+const SEMVER_LITERAL = /['"]([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.]+)?)['"]/;
+function walkTs(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        if (statSync(p).isDirectory())
+            out.push(...walkTs(p));
+        else if (p.endsWith('.ts'))
+            out.push(p);
+    }
+    return out;
+}
+/**
+ * The release-please drift guard. Walks `srcDir` for every line carrying an
+ * `x-release-please-version` annotation and asserts the version literal on that
+ * line matches `package.json#version`.
+ *
+ * Why this exists: a recurring footgun where a `VERSION` constant (the MCP's
+ * self-reported version + fetchproxy bridge identity) silently drifts from
+ * `package.json` because release-please's `extra-files` registration lacks the
+ * marker. resy-mcp v0.2.0 and opentable-mcp shipped this bug repeatedly.
+ *
+ * Returns the list of mismatch descriptions (`file:line → found (expected X)`).
+ * An empty array means in sync — callers assert `expect(result).toEqual([])`.
+ * Marker lines with no version literal (e.g. a docstring describing the
+ * convention) are intentionally skipped, so the test never trips on itself.
+ */
+export function versionSyncTest({ srcDir, pkgPath }) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const root = join(srcDir, '..');
+    const mismatches = [];
+    for (const f of walkTs(srcDir)) {
+        const lines = readFileSync(f, 'utf8').split('\n');
+        lines.forEach((line, i) => {
+            if (!line.includes('x-release-please-version'))
+                return;
+            const match = line.match(SEMVER_LITERAL);
+            if (!match)
+                return;
+            const ver = match[1];
+            if (ver !== pkg.version) {
+                mismatches.push(`${relative(root, f)}:${i + 1} → ${ver} (expected ${pkg.version})`);
+            }
+        });
+    }
+    return mismatches;
+}
+/**
+ * Build a fully-shaped {@link BootstrapResult}, with empty maps as defaults and
+ * `overrides` shallow-merged on top. Keeps tests from re-declaring the four
+ * empty maps every time they only care about, say, `cookies`.
+ */
+export function makeBootstrapResult(overrides = {}) {
+    return {
+        cookies: {},
+        localStorage: {},
+        sessionStorage: {},
+        capturedHeaders: {},
+        ...overrides,
+    };
+}
+/**
+ * Mock `@fetchproxy/bootstrap` at the module boundary so tests never open a
+ * real WebSocket to a browser bridge. Returns a spy that resolves a default
+ * {@link BootstrapResult} (overridable per call via `bootstrap.mockResolvedValue`).
+ *
+ * Usage:
+ * ```ts
+ * const fp = mockFetchproxyBootstrap({ cookies: { SID: 'x' } });
+ * vi.mock('@fetchproxy/bootstrap', fp.module);
+ * // ...import the SUT, then assert on fp.bootstrap
+ * ```
+ * Because `vi.mock` is hoisted, declare the mock handle and the `vi.mock` call
+ * before importing the system under test.
+ */
+export function mockFetchproxyBootstrap(defaultResult = {}) {
+    const base = makeBootstrapResult(defaultResult);
+    const bootstrap = vi.fn(async (..._args) => base);
+    return {
+        bootstrap,
+        module: () => ({ bootstrap: (...args) => bootstrap(...args) }),
+        reset: () => {
+            bootstrap.mockReset();
+            bootstrap.mockResolvedValue(base);
+        },
+    };
+}
+/**
+ * Spy on an API client's async request methods and (optionally) stub each one's
+ * resolved value. Mirrors the `vi.spyOn(client, 'request').mockResolvedValue(...)`
+ * boilerplate every tool-level test repeats.
+ *
+ * For each entry in `returns`: a spy is installed on `client[method]`. If the
+ * value is `undefined`, the spy passes through to the real implementation;
+ * otherwise it `mockResolvedValue`s the provided value. Remember to
+ * `vi.restoreAllMocks()` in `afterEach`.
+ *
+ * @returns A map of method name → installed spy, for call assertions.
+ */
+export function setupClientMocks(client, returns) {
+    const spies = {};
+    for (const method of Object.keys(returns)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const spy = vi.spyOn(client, method);
+        const value = returns[method];
+        if (value !== undefined)
+            spy.mockResolvedValue(value);
+        spies[method] = spy;
+    }
+    return spies;
+}
+//# sourceMappingURL=index.js.map

package/dist/test/index.js.map

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

package/dist/zod/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `zod` — schema atoms, pagination, and tool-annotation helpers shared across
+ * the MCP fleet. Intentionally small: atoms + annotations, not a schema
+ * framework. Built on zod v4.
+ *
+ * The raw-shape style (`inputSchema: { foo: z.string() }`) used by
+ * `server.registerTool` is preserved — these atoms are plain `ZodType`s you
+ * drop straight into a shape object.
+ */
+import { z } from 'zod';
+/** A strictly positive integer (`> 0`). */
+export declare const PositiveInt: z.ZodNumber;
+/** A non-negative integer (`>= 0`). */
+export declare const NonNegInt: z.ZodNumber;
+/** A non-empty string (after no trimming — at least one character). */
+export declare const NonEmptyString: z.ZodString;
+/**
+ * An ISO calendar date, `YYYY-MM-DD`. Rejects impossible dates (e.g.
+ * `2026-13-01`) via zod v4's `z.iso.date()`.
+ */
+export declare const IsoDate: z.ZodISODate;
+/**
+ * A 24-hour wall-clock time `HH:MM` (no seconds, no offset). This is the
+ * fleet convention (resy notify/book, slot windows) — restaurant-local times
+ * carried as bare `HH:MM`, never parsed through `Date` so they aren't shifted
+ * by the server's timezone. Accepts `9:05` and `09:05`; rejects `24:00`,
+ * `19:60`, and anything with seconds.
+ */
+export declare const IsoTime: z.ZodString;
+/**
+ * Optional portal-origin selector (e.g. `https://<vendor>.hbportal.co`).
+ * Disambiguates which signed-in session a tool routes through when more than
+ * one is active. Optional — when a single session is active it can be omitted.
+ * (honeybook / disk-session MCPs)
+ */
+export declare const schemaOrigin: z.ZodOptional<z.ZodString>;
+/**
+ * The write-confirmation gate shared by mutating tools: without
+ * `confirm: true` the tool returns a preview instead of performing the action.
+ * (honeybook pay_invoice / sign_contract)
+ */
+export declare const schemaConfirm: z.ZodOptional<z.ZodBoolean>;
+/**
+ * Offset/limit pagination shape (raw, for spreading into an `inputSchema`).
+ * `offset` defaults to 0, `limit` is bounded `1..200` and defaults to 50 —
+ * the bounds standardized across the fleet's search tools.
+ */
+export declare const paginationSchema: {
+    readonly offset: z.ZodDefault<z.ZodNumber>;
+    readonly limit: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * 1-based page pagination shape (`page_num` / `page_size`). `page_num`
+ * defaults to 1, `page_size` is bounded `1..200` and defaults to 50.
+ * Mirrors onehome-mcp's search pagination, normalized to 1-based.
+ */
+export declare const pageSchema: {
+    readonly page_num: z.ZodDefault<z.ZodNumber>;
+    readonly page_size: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Convert a 1-based page + page size into a zero-based offset.
+ *
+ * Defensive against bad callers: page and size are floored, page is clamped to
+ * `>= 1` and size to `>= 0`, so the result is always a non-negative integer.
+ *
+ * @example calculateOffset(1, 50) // 0
+ * @example calculateOffset(3, 50) // 100
+ */
+export declare function calculateOffset(page: number, size: number): number;
+/** The MCP tool-annotation block, as consumed by `server.registerTool`. */
+export interface ToolAnnotations {
+    title: string;
+    readOnlyHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/** Options for {@link toolAnnotations}. */
+export interface ToolAnnotationsInput {
+    /** Human-readable tool title (shown in clients). */
+    title: string;
+    /** Tool does not modify state. Default `true` (most fleet tools are reads). */
+    readOnly?: boolean;
+    /** Repeated identical calls have the same effect. Default `true`. */
+    idempotent?: boolean;
+    /**
+     * Tool reaches an open/unbounded external world (the live web/API) rather
+     * than a closed local computation. Default `true`.
+     */
+    openWorld?: boolean;
+}
+/**
+ * Build the `annotations` block repeated across ~15 tools per MCP. Defaults
+ * encode the fleet's common case (a read-only, idempotent, open-world fetch);
+ * mutating/local tools override the relevant hint.
+ *
+ * @example toolAnnotations({ title: 'Search properties' })
+ *   // { title, readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+ * @example toolAnnotations({ title: 'Book', readOnly: false, idempotent: false })
+ */
+export declare function toolAnnotations(opts: ToolAnnotationsInput): ToolAnnotations;
+/**
+ * Extract bare `HH:MM` from an ISO-ish datetime such as
+ * `2026-05-01T19:00:00` or a wire time `19:00:00`. Deliberately avoids
+ * `new Date()` so times aren't shifted by the server's timezone (resy returns
+ * restaurant-local times with no offset). Returns `''` when no time is found.
+ *
+ * @example extractTime('2026-05-01T19:30:00') // '19:30'
+ * @example extractTime('19:30:00')            // '19:30'
+ * @example extractTime(undefined)             // ''
+ */
+export declare function extractTime(input: string | undefined | null): string;
+/**
+ * Normalize a loose caller-supplied time to canonical 24-hour `HH:MM`.
+ *
+ * Accepts:
+ *  - `HH:MM` / `H:MM`           → zero-padded `HH:MM`
+ *  - `HH:MM:SS`                 → seconds trimmed
+ *  - `7pm`, `7:30 PM`, `12 am`  → 12h clock converted (12am→00, 12pm→12)
+ *
+ * Returns `undefined` when the input can't be understood, so callers can fall
+ * through to a default rather than book at a garbage time.
+ *
+ * @example normalizeTime('7:30 PM') // '19:30'
+ * @example normalizeTime('9:5')     // '09:05'
+ * @example normalizeTime('12am')    // '00:00'
+ * @example normalizeTime('nope')    // undefined
+ */
+export declare function normalizeTime(input: string | undefined | null): string | undefined;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/zod/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,2CAA2C;AAC3C,eAAO,MAAM,WAAW,aAA8B,CAAC;AAEvD,uCAAuC;AACvC,eAAO,MAAM,SAAS,aAAiC,CAAC;AAExD,uEAAuE;AACvE,eAAO,MAAM,cAAc,aAAoB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,OAAO,cAAe,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,aAEqD,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,4BAKtB,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,aAAa,6BAGuD,CAAC;AAMlF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;CASnB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;CASb,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlE;AAMD,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe,CAO3E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAOpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAuBlF"}

package/dist/zod/index.js

@@ -0,0 +1,184 @@
+/**
+ * `zod` — schema atoms, pagination, and tool-annotation helpers shared across
+ * the MCP fleet. Intentionally small: atoms + annotations, not a schema
+ * framework. Built on zod v4.
+ *
+ * The raw-shape style (`inputSchema: { foo: z.string() }`) used by
+ * `server.registerTool` is preserved — these atoms are plain `ZodType`s you
+ * drop straight into a shape object.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Atoms
+// ---------------------------------------------------------------------------
+/** A strictly positive integer (`> 0`). */
+export const PositiveInt = z.number().int().positive();
+/** A non-negative integer (`>= 0`). */
+export const NonNegInt = z.number().int().nonnegative();
+/** A non-empty string (after no trimming — at least one character). */
+export const NonEmptyString = z.string().min(1);
+/**
+ * An ISO calendar date, `YYYY-MM-DD`. Rejects impossible dates (e.g.
+ * `2026-13-01`) via zod v4's `z.iso.date()`.
+ */
+export const IsoDate = z.iso.date();
+/**
+ * A 24-hour wall-clock time `HH:MM` (no seconds, no offset). This is the
+ * fleet convention (resy notify/book, slot windows) — restaurant-local times
+ * carried as bare `HH:MM`, never parsed through `Date` so they aren't shifted
+ * by the server's timezone. Accepts `9:05` and `09:05`; rejects `24:00`,
+ * `19:60`, and anything with seconds.
+ */
+export const IsoTime = z
+    .string()
+    .regex(/^([01]?\d|2[0-3]):[0-5]\d$/, 'must be HH:MM (24h), e.g. 19:30');
+/**
+ * Optional portal-origin selector (e.g. `https://<vendor>.hbportal.co`).
+ * Disambiguates which signed-in session a tool routes through when more than
+ * one is active. Optional — when a single session is active it can be omitted.
+ * (honeybook / disk-session MCPs)
+ */
+export const schemaOrigin = z
+    .string()
+    .optional()
+    .describe('Portal origin (e.g. https://<vendor>.example.co) selecting which active session to use. Optional when only one session is active.');
+/**
+ * The write-confirmation gate shared by mutating tools: without
+ * `confirm: true` the tool returns a preview instead of performing the action.
+ * (honeybook pay_invoice / sign_contract)
+ */
+export const schemaConfirm = z
+    .boolean()
+    .optional()
+    .describe('Must be true to proceed. Without this, the tool returns a preview.');
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+/**
+ * Offset/limit pagination shape (raw, for spreading into an `inputSchema`).
+ * `offset` defaults to 0, `limit` is bounded `1..200` and defaults to 50 —
+ * the bounds standardized across the fleet's search tools.
+ */
+export const paginationSchema = {
+    offset: NonNegInt.default(0).describe('Number of items to skip (0-based).'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .default(50)
+        .describe('Maximum number of items to return (1-200).'),
+};
+/**
+ * 1-based page pagination shape (`page_num` / `page_size`). `page_num`
+ * defaults to 1, `page_size` is bounded `1..200` and defaults to 50.
+ * Mirrors onehome-mcp's search pagination, normalized to 1-based.
+ */
+export const pageSchema = {
+    page_num: PositiveInt.default(1).describe('1-based page number.'),
+    page_size: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .default(50)
+        .describe('Number of items per page (1-200).'),
+};
+/**
+ * Convert a 1-based page + page size into a zero-based offset.
+ *
+ * Defensive against bad callers: page and size are floored, page is clamped to
+ * `>= 1` and size to `>= 0`, so the result is always a non-negative integer.
+ *
+ * @example calculateOffset(1, 50) // 0
+ * @example calculateOffset(3, 50) // 100
+ */
+export function calculateOffset(page, size) {
+    const p = Math.max(1, Math.floor(page));
+    const s = Math.max(0, Math.floor(size));
+    return (p - 1) * s;
+}
+/**
+ * Build the `annotations` block repeated across ~15 tools per MCP. Defaults
+ * encode the fleet's common case (a read-only, idempotent, open-world fetch);
+ * mutating/local tools override the relevant hint.
+ *
+ * @example toolAnnotations({ title: 'Search properties' })
+ *   // { title, readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+ * @example toolAnnotations({ title: 'Book', readOnly: false, idempotent: false })
+ */
+export function toolAnnotations(opts) {
+    return {
+        title: opts.title,
+        readOnlyHint: opts.readOnly ?? true,
+        idempotentHint: opts.idempotent ?? true,
+        openWorldHint: opts.openWorld ?? true,
+    };
+}
+// ---------------------------------------------------------------------------
+// Time normalization (resy)
+// ---------------------------------------------------------------------------
+/**
+ * Extract bare `HH:MM` from an ISO-ish datetime such as
+ * `2026-05-01T19:00:00` or a wire time `19:00:00`. Deliberately avoids
+ * `new Date()` so times aren't shifted by the server's timezone (resy returns
+ * restaurant-local times with no offset). Returns `''` when no time is found.
+ *
+ * @example extractTime('2026-05-01T19:30:00') // '19:30'
+ * @example extractTime('19:30:00')            // '19:30'
+ * @example extractTime(undefined)             // ''
+ */
+export function extractTime(input) {
+    if (!input)
+        return '';
+    // Prefer the time component after a `T`; fall back to a leading HH:MM[:SS].
+    const afterT = /T(\d{2}):(\d{2})/.exec(input);
+    if (afterT)
+        return `${afterT[1]}:${afterT[2]}`;
+    const leading = /^(\d{2}):(\d{2})/.exec(input);
+    return leading ? `${leading[1]}:${leading[2]}` : '';
+}
+/**
+ * Normalize a loose caller-supplied time to canonical 24-hour `HH:MM`.
+ *
+ * Accepts:
+ *  - `HH:MM` / `H:MM`           → zero-padded `HH:MM`
+ *  - `HH:MM:SS`                 → seconds trimmed
+ *  - `7pm`, `7:30 PM`, `12 am`  → 12h clock converted (12am→00, 12pm→12)
+ *
+ * Returns `undefined` when the input can't be understood, so callers can fall
+ * through to a default rather than book at a garbage time.
+ *
+ * @example normalizeTime('7:30 PM') // '19:30'
+ * @example normalizeTime('9:5')     // '09:05'
+ * @example normalizeTime('12am')    // '00:00'
+ * @example normalizeTime('nope')    // undefined
+ */
+export function normalizeTime(input) {
+    if (!input)
+        return undefined;
+    const s = input.trim().toLowerCase();
+    if (!s)
+        return undefined;
+    const m = /^(\d{1,2})(?::(\d{1,2}))?(?::\d{1,2})?\s*(am|pm)?$/.exec(s);
+    if (!m)
+        return undefined;
+    let hour = Number(m[1]);
+    const minute = m[2] === undefined ? 0 : Number(m[2]);
+    const meridiem = m[3];
+    if (minute > 59)
+        return undefined;
+    if (meridiem) {
+        if (hour < 1 || hour > 12)
+            return undefined;
+        if (meridiem === 'am')
+            hour = hour === 12 ? 0 : hour;
+        else
+            hour = hour === 12 ? 12 : hour + 12;
+    }
+    else if (hour > 23) {
+        return undefined;
+    }
+    return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/zod/index.js.map

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

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@chrischall/mcp-utils",
+  "version": "0.1.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",
+  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischall/mcp-utils.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./test": {
+      "import": "./dist/test/index.js",
+      "types": "./dist/test/index.d.ts"
+    },
+    "./fetchproxy": {
+      "import": "./dist/fetchproxy/index.js",
+      "types": "./dist/fetchproxy/index.d.ts"
+    },
+    "./session": {
+      "import": "./dist/session/index.js",
+      "types": "./dist/session/index.d.ts"
+    },
+    "./html": {
+      "import": "./dist/html/index.js",
+      "types": "./dist/html/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --noEmit false",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.0",
+    "@fetchproxy/server": "*",
+    "node-html-parser": "*",
+    "vitest": "*"
+  },
+  "peerDependenciesMeta": {
+    "@fetchproxy/server": {
+      "optional": true
+    },
+    "node-html-parser": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fetchproxy/server": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "node-html-parser": "^7.1.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0",
+    "zod": "^4.4.0"
+  }
+}