@chrischall/mcp-utils 0.1.0

package/dist/response/index.js

@@ -0,0 +1,61 @@
+/**
+ * Wrap any JSON-serialisable value as an MCP tool result. This is the single
+ * most duplicated snippet across the fleet:
+ *   `{ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }`
+ */
+export function textResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** Alias for {@link textResult} — pretty-printed JSON tool result. */
+export const jsonResult = textResult;
+/** Return a raw string as a text tool result (no JSON stringify). */
+export function rawTextResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/** Return a base64 image as an MCP image tool result. */
+export function imageResult(base64, mimeType) {
+    return {
+        content: [{ type: 'image', data: base64, mimeType }],
+    };
+}
+/** Return an error tool result (`isError: true`) carrying a message. */
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+/**
+ * Collapse a JSON:API-shaped payload (`{ data: { id, type, attributes } }` or an
+ * array thereof) into plain objects with `id`/`type` merged into attributes.
+ * Used by skylight-mcp; opt-in (callers pass payloads they know are JSON:API).
+ */
+export function flattenJsonApi(payload) {
+    const flattenOne = (node) => {
+        if (node === null || typeof node !== 'object')
+            return node;
+        const obj = node;
+        const attrs = obj.attributes;
+        if (attrs !== null && typeof attrs === 'object') {
+            const merged = { ...attrs };
+            if ('id' in obj)
+                merged.id = obj.id;
+            if ('type' in obj)
+                merged.type = obj.type;
+            return merged;
+        }
+        return node;
+    };
+    if (payload === null || typeof payload !== 'object')
+        return payload;
+    const root = payload;
+    if (!('data' in root))
+        return payload;
+    const data = root.data;
+    if (Array.isArray(data))
+        return data.map(flattenOne);
+    return flattenOne(data);
+}
+//# sourceMappingURL=index.js.map

package/dist/response/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AAErC,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAgB;IAC1D,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,MAAM,UAAU,GAAG,CAAC,IAAa,EAAW,EAAE;QAC5C,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3D,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;QAC7B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,MAAM,GAA4B,EAAE,GAAI,KAAiC,EAAE,CAAC;YAClF,IAAI,IAAI,IAAI,GAAG;gBAAE,MAAM,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC;YACpC,IAAI,MAAM,IAAI,GAAG;gBAAE,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YAC1C,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IACpE,MAAM,IAAI,GAAG,OAAkC,CAAC;IAChD,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACrD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/server/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `server` — MCP bootstrap & lifecycle.
+ *
+ * The single biggest dedup win in the fleet: every `src/index.ts` is described
+ * as "byte-identical" — construct an {@link McpServer}, run a fixed list of
+ * `registerXTools(server, client)` calls, print a stderr banner, wire
+ * SIGINT/SIGTERM to tear the transport down, then connect over stdio.
+ *
+ * This module collapses that 30–120 lines/MCP into three calls:
+ *  - {@link createMcpServer} — build the server and apply the registrars.
+ *  - {@link withGracefulShutdown} — SIGINT/SIGTERM → cleanup → exit.
+ *  - {@link runMcp} — bootstrap + banner + connect + shutdown, the whole boot.
+ *
+ * It is deliberately transport- and domain-agnostic. The
+ * deferred-config-error pattern (server boots before creds exist, so the host's
+ * initial `tools/list` always succeeds and the first tool call surfaces the auth
+ * error) is preserved by keeping client/transport construction in the caller's
+ * `deps`: both Pattern-A (fetchproxy bridge) and Pattern-B (direct/bearer) MCPs
+ * build their client themselves and pass it through, so neither is coupled in.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+/**
+ * Registers one or more tools onto a fresh {@link McpServer}. `deps` is whatever
+ * the caller threaded through {@link createMcpServer} / {@link runMcp} — an API
+ * client, a session registry, an app context, or `undefined` for tools (like
+ * pure mortgage/affordability calculators) that need no shared state.
+ *
+ * May be async; {@link createMcpServer} awaits each registrar in order.
+ */
+export type ToolRegistrar<TDeps = unknown> = (server: McpServer, deps: TDeps) => void | Promise<void>;
+/** Either the literal `'stdio'` (the default) or any SDK {@link Transport}. */
+export type TransportSpec = 'stdio' | Transport;
+/** Options for {@link createMcpServer}. */
+export interface CreateMcpServerOptions<TDeps = unknown> {
+    /** Server name advertised to the host (e.g. `'splitwise-mcp'`). */
+    name: string;
+    /** Server version advertised to the host (the `x-release-please-version`). */
+    version: string;
+    /** The tool registrars to apply, in order. */
+    tools: ToolRegistrar<TDeps>[];
+    /**
+     * Shared state passed as the second argument to every registrar — the API
+     * client, app context, session registry, etc. Build it before calling so the
+     * deferred-config-error pattern is preserved. Omit for registrar lists that
+     * take no deps.
+     */
+    deps?: TDeps;
+    /** A one-line startup banner written to stderr (never stdout — stdout is the JSON-RPC channel). */
+    banner?: string;
+    /**
+     * Transport hint. Carried for API symmetry with {@link runMcp}; this function
+     * never connects, so it only matters that the value is accepted. Defaults to
+     * `'stdio'`.
+     */
+    transport?: TransportSpec;
+}
+/**
+ * Build an {@link McpServer}, print the optional stderr banner, and apply every
+ * tool registrar (awaiting async ones) — but do **not** connect a transport.
+ * Connecting is {@link runMcp}'s job (or the caller's), which keeps this usable
+ * from tests and from custom boot sequences.
+ */
+export declare function createMcpServer<TDeps = unknown>(opts: CreateMcpServerOptions<TDeps>): Promise<McpServer>;
+/** Signals {@link withGracefulShutdown} listens for. */
+export type ShutdownSignal = 'SIGINT' | 'SIGTERM';
+/** Options for {@link withGracefulShutdown}. */
+export interface GracefulShutdownOptions {
+    /**
+     * Extra cleanup to run on shutdown, before the server is closed — typically
+     * `() => client.close()` to release the fetchproxy WebSocket bridge / direct
+     * sockets so ports don't leak between host restarts. Receives the signal that
+     * triggered shutdown. Errors are logged, never fatal.
+     */
+    onSignal?: (signal: ShutdownSignal) => void | Promise<void>;
+    /**
+     * Call `process.exit(0)` after cleanup completes. Default `true` (matches the
+     * fleet's `process.exit(0)`). Set `false` in tests so the process survives.
+     */
+    exit?: boolean;
+}
+/**
+ * Wire SIGINT/SIGTERM to a one-shot graceful shutdown: run `onSignal` (e.g.
+ * close the client/transport), close the server, then `process.exit(0)` (unless
+ * `exit: false`). Idempotent — a second signal mid-shutdown is ignored, and a
+ * throwing `onSignal`/`close` is logged but still exits cleanly so a wedged
+ * cleanup can't hang the host.
+ */
+export declare function withGracefulShutdown(server: Pick<McpServer, 'close'>, opts?: GracefulShutdownOptions): void;
+/** Options for {@link runMcp} — {@link createMcpServer}'s plus lifecycle wiring. */
+export interface RunMcpOptions<TDeps = unknown> extends CreateMcpServerOptions<TDeps> {
+    /**
+     * Graceful-shutdown wiring. `true` (default) installs SIGINT/SIGTERM handlers
+     * that close the server. `false` skips them. An object is passed straight to
+     * {@link withGracefulShutdown} (e.g. `{ onSignal: () => client.close() }`).
+     */
+    shutdown?: boolean | GracefulShutdownOptions;
+}
+/**
+ * The whole boot in one call: build the server, apply registrars, print the
+ * banner, install graceful-shutdown handlers, and connect the transport
+ * (defaulting to a {@link StdioServerTransport}). Returns the connected server.
+ *
+ * Pattern-A and Pattern-B MCPs both build their client/transport in `deps` and
+ * pass `onSignal: () => client.close()` via `shutdown`, so this stays agnostic
+ * to how creds are resolved.
+ */
+export declare function runMcp<TDeps = unknown>(opts: RunMcpOptions<TDeps>): Promise<McpServer>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,GAAG,OAAO,IAAI,CAC3C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,KAAK,KACR,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB,CAAC,KAAK,GAAG,OAAO;IACrD,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,GAAG,OAAO,EACnD,IAAI,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAClC,OAAO,CAAC,SAAS,CAAC,CAgBpB;AAED,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAChC,IAAI,GAAE,uBAA4B,GACjC,IAAI,CAyBN;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,sBAAsB,CAAC,KAAK,CAAC;IACnF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1C,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,GACzB,OAAO,CAAC,SAAS,CAAC,CAapB"}

package/dist/server/index.js

@@ -0,0 +1,95 @@
+/**
+ * `server` — MCP bootstrap & lifecycle.
+ *
+ * The single biggest dedup win in the fleet: every `src/index.ts` is described
+ * as "byte-identical" — construct an {@link McpServer}, run a fixed list of
+ * `registerXTools(server, client)` calls, print a stderr banner, wire
+ * SIGINT/SIGTERM to tear the transport down, then connect over stdio.
+ *
+ * This module collapses that 30–120 lines/MCP into three calls:
+ *  - {@link createMcpServer} — build the server and apply the registrars.
+ *  - {@link withGracefulShutdown} — SIGINT/SIGTERM → cleanup → exit.
+ *  - {@link runMcp} — bootstrap + banner + connect + shutdown, the whole boot.
+ *
+ * It is deliberately transport- and domain-agnostic. The
+ * deferred-config-error pattern (server boots before creds exist, so the host's
+ * initial `tools/list` always succeeds and the first tool call surfaces the auth
+ * error) is preserved by keeping client/transport construction in the caller's
+ * `deps`: both Pattern-A (fetchproxy bridge) and Pattern-B (direct/bearer) MCPs
+ * build their client themselves and pass it through, so neither is coupled in.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+/**
+ * Build an {@link McpServer}, print the optional stderr banner, and apply every
+ * tool registrar (awaiting async ones) — but do **not** connect a transport.
+ * Connecting is {@link runMcp}'s job (or the caller's), which keeps this usable
+ * from tests and from custom boot sequences.
+ */
+export async function createMcpServer(opts) {
+    const server = new McpServer({ name: opts.name, version: opts.version });
+    if (opts.banner !== undefined) {
+        // stderr only: stdout carries the JSON-RPC frames over stdio transport.
+        console.error(opts.banner);
+    }
+    // `deps` is intentionally cast: when omitted, registrars that declare a deps
+    // type are the caller's responsibility (they passed deps if they need it).
+    const deps = opts.deps;
+    for (const register of opts.tools) {
+        await register(server, deps);
+    }
+    return server;
+}
+/**
+ * Wire SIGINT/SIGTERM to a one-shot graceful shutdown: run `onSignal` (e.g.
+ * close the client/transport), close the server, then `process.exit(0)` (unless
+ * `exit: false`). Idempotent — a second signal mid-shutdown is ignored, and a
+ * throwing `onSignal`/`close` is logged but still exits cleanly so a wedged
+ * cleanup can't hang the host.
+ */
+export function withGracefulShutdown(server, opts = {}) {
+    const shouldExit = opts.exit ?? true;
+    let shuttingDown = false;
+    const handler = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        void (async () => {
+            try {
+                if (opts.onSignal)
+                    await opts.onSignal(signal);
+                await server.close();
+            }
+            catch (err) {
+                console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                if (shouldExit)
+                    process.exit(0);
+            }
+        })();
+    };
+    process.on('SIGINT', () => handler('SIGINT'));
+    process.on('SIGTERM', () => handler('SIGTERM'));
+}
+/**
+ * The whole boot in one call: build the server, apply registrars, print the
+ * banner, install graceful-shutdown handlers, and connect the transport
+ * (defaulting to a {@link StdioServerTransport}). Returns the connected server.
+ *
+ * Pattern-A and Pattern-B MCPs both build their client/transport in `deps` and
+ * pass `onSignal: () => client.close()` via `shutdown`, so this stays agnostic
+ * to how creds are resolved.
+ */
+export async function runMcp(opts) {
+    const server = await createMcpServer(opts);
+    const shutdown = opts.shutdown ?? true;
+    if (shutdown !== false) {
+        withGracefulShutdown(server, shutdown === true ? {} : shutdown);
+    }
+    const spec = opts.transport ?? 'stdio';
+    const transport = spec === 'stdio' ? new StdioServerTransport() : spec;
+    await server.connect(transport);
+    return server;
+}
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

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

package/dist/session/index.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Session scaffolding for the MCP fleet — three related-but-distinct surfaces
+ * consolidated behind one subpath (`@chrischall/mcp-utils/session`):
+ *
+ *  1. {@link SessionRegistry} — an *ephemeral, in-memory* registry of signed-in
+ *     sessions keyed by account identity, plus {@link registerSessionTools} for
+ *     the structurally-identical `*_register_session` / `*_set_active_session` /
+ *     `*_get_session_context` MCP tool trio. Used by the realty MCPs
+ *     (zillow/redfin/compass/homes/onehome).
+ *
+ *  2. {@link SessionStore} — a *disk-persisted* store with hardened file perms
+ *     (0600 file / 0700 dir), normalized keys, and a most-recently-used "active"
+ *     pointer. Used by ofw/creditkarma/honeybook.
+ *
+ *  3. {@link TokenManager} — a bearer-token lifecycle manager: proactive refresh
+ *     inside a 5-minute skew window, reactive 401-replay, and a single-flight
+ *     semaphore so concurrent callers coalesce into ONE refresh. Used by
+ *     skylight/canvas/creditkarma/honeybook/zola.
+ *
+ * Security-sensitive by design (file perms + token-refresh races), so this is
+ * the one audited implementation the fleet shares.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** How a session was authenticated. Open-ended so per-MCP modes slot in. */
+export type AuthMode = 'browser_session' | 'unknown' | (string & {});
+/** A registered, signed-in session as surfaced to tools and clients. */
+export interface SessionToken {
+    /** Opaque label id (`Date.now().toString(36)` + random). Stable across re-registration. */
+    session_id: string;
+    /**
+     * Caller-supplied identity for the signed-in account (usually the saved
+     * email). Re-registering the same identity updates the existing entry in
+     * place rather than creating a duplicate.
+     */
+    account_identity: string;
+    auth_mode: AuthMode;
+    /** Whether the session is currently usable for tool calls. */
+    auth_ready: boolean;
+    /** ISO timestamp of when the session was last registered/refreshed. */
+    registered_at: string;
+    /** ISO expiry, or `null` for "no known expiry". */
+    auth_expires_at: string | null;
+}
+/** Snapshot returned by {@link SessionRegistry.getContext}. */
+export interface SessionContext {
+    active_session_id: string | null;
+    sessions: SessionToken[];
+}
+/** Arguments to {@link SessionRegistry.register}. */
+export interface RegisterArgs {
+    account_identity: string;
+    auth_mode?: AuthMode;
+    /**
+     * `undefined` keeps any existing expiry on re-registration; an explicit
+     * value (including `null`) replaces it. This distinction matters — coercing
+     * with `?? null` would silently wipe a previously-set expiry.
+     */
+    auth_expires_at?: string | null;
+}
+/**
+ * Per-process, in-memory registry of signed-in sessions. The constructor takes
+ * no arguments, so it's safe to instantiate per test. Sessions are keyed by
+ * `session_id` but de-duplicated by `account_identity`.
+ */
+export declare class SessionRegistry {
+    private readonly sessions;
+    private activeId;
+    /**
+     * Register a new session, or refresh the existing one keyed by
+     * `account_identity`. The first session registered becomes the active one.
+     */
+    register(args: RegisterArgs): SessionToken;
+    /** Switch the active session. Returns `false` if the id is unknown. */
+    setActive(sessionId: string): boolean;
+    /** Look up a session by id (returns a copy, or `null`). */
+    get(sessionId: string): SessionToken | null;
+    /** Snapshot of the full registry plus the active id. */
+    getContext(): SessionContext;
+    /** The active session id, if any. */
+    activeSessionId(): string | null;
+    /** Number of registered sessions. */
+    size(): number;
+    /**
+     * Resolve which session a tool call should route through:
+     * - `requested` set and known → it;
+     * - `requested` set but unknown → throws;
+     * - `requested` undefined → the active session;
+     * - no sessions registered → `null` (caller uses the default transport).
+     */
+    resolve(requested: string | undefined): string | null;
+    /** Clear all state. Test helper. */
+    reset(): void;
+}
+/** Construct a fresh in-memory {@link SessionRegistry}. */
+export declare function createSessionRegistry(): SessionRegistry;
+/** Options for {@link registerSessionTools}. */
+export interface RegisterSessionToolsOptions {
+    /**
+     * Tool-name prefix, e.g. `'zillow'` → `zillow_register_session`. This is the
+     * one per-MCP knob; everything else is identical across the fleet.
+     */
+    prefix: string;
+    /** Human label for the service (defaults to the prefix). */
+    serviceLabel?: string;
+}
+/**
+ * Register the structurally-identical session tool trio against `server`,
+ * backed by `registry`. Replaces every MCP's hand-rolled `src/tools/sessions.ts`.
+ */
+export declare function registerSessionTools(server: McpServer, registry: SessionRegistry, opts: RegisterSessionToolsOptions): void;
+/**
+ * Given a full URL or just an origin, return the origin without a trailing
+ * slash. Falls back to trimming a trailing slash for non-URL input.
+ */
+export declare function normalizeOrigin(input: string): string;
+/** Options for {@link SessionStore}. `T` is the persisted record shape. */
+export interface SessionStoreOptions<T> {
+    /** Absolute path to the JSON file. Parent dirs are created as needed. */
+    filePath: string;
+    /** Extract the unique key (e.g. origin / account id) from a record. */
+    keyOf: (session: T) => string;
+    /**
+     * Normalize a key before storing/looking up. Defaults to
+     * {@link normalizeOrigin}. The stored record's key field is also normalized.
+     */
+    normalizeKey?: (key: string) => string;
+}
+/**
+ * Disk-persisted session store with hardened file permissions. Records are kept
+ * in a `Map` keyed by their normalized key, persisted as a JSON array (insertion
+ * order). The file is written with mode `0600` and its directory `0700` so other
+ * users on the machine cannot read captured credentials.
+ *
+ * `add` marks the record most-recently-used; {@link SessionStore.getActiveSession}
+ * (and `get()` with no argument) returns it, so a tool call that omits an explicit
+ * key picks up the latest session automatically.
+ */
+export declare class SessionStore<T extends Record<string, unknown>> {
+    private sessions;
+    private mostRecentKey;
+    private readonly filePath;
+    private readonly keyOf;
+    private readonly normalizeKey;
+    constructor(opts: SessionStoreOptions<T>);
+    private loadFromDisk;
+    /** Serialize the store to its on-disk JSON form (array, insertion order). */
+    serialize(): string;
+    /** Parse on-disk JSON back into a keyed `Map`; empty map on invalid input. */
+    private deserialize;
+    private saveToDisk;
+    /** Insert or replace a record, normalizing its key and marking it active. */
+    add(session: T): void;
+    /** Look up by key; with no key, returns the active (most-recent) session. */
+    get(key?: string): T | null;
+    /** The most-recently-added session, or `null`. */
+    getActiveSession(): T | null;
+    /** All sessions in insertion order. */
+    list(): T[];
+    /** Remove a session; fixes up the active pointer. Returns whether it existed. */
+    remove(key: string): boolean;
+    /** Clear in-memory state without touching disk. Test helper. */
+    resetForTest(): void;
+}
+/** Refresh proactively this many ms before the access token expires. */
+export declare const TOKEN_REFRESH_SKEW_MS: number;
+/** A bearer access token + (optional) refresh token + absolute expiry. */
+export interface BearerTokens {
+    accessToken: string;
+    /** Refresh token, if the flow uses one. */
+    refreshToken?: string;
+    /** Absolute expiry in epoch milliseconds. */
+    expiresAt: number;
+}
+/** Result a {@link TokenManagerOptions.refresh} call must return. */
+export interface RefreshedTokens {
+    accessToken: string;
+    /** Omit to keep the current refresh token (rotation is optional). */
+    refreshToken?: string;
+    expiresAt: number;
+}
+/** Options for {@link TokenManager}. */
+export interface TokenManagerOptions {
+    /** Initial tokens (typically from env or a one-shot bootstrap). */
+    initial: BearerTokens;
+    /**
+     * Exchange the current refresh token for fresh tokens. Called at most once
+     * per concurrent burst (the in-flight promise is shared).
+     */
+    refresh: (refreshToken: string) => Promise<RefreshedTokens>;
+    /**
+     * Override the skew window (ms before expiry that triggers a proactive
+     * refresh). Defaults to {@link TOKEN_REFRESH_SKEW_MS} (5 minutes).
+     */
+    skewMs?: number;
+}
+/**
+ * Manages a bearer access token's lifecycle:
+ *
+ * - **Proactive:** {@link TokenManager.getAccessToken} refreshes when the token
+ *   is within `skewMs` (default 5 min) of expiry, returning a still-valid token.
+ * - **Reactive:** {@link TokenManager.withAuth} runs a request, and on a `401`
+ *   refreshes once and replays exactly once (no infinite loop).
+ * - **Race-safe:** concurrent refreshes coalesce onto a single in-flight promise
+ *   (semaphore), so a burst of callers triggers exactly ONE token exchange. The
+ *   in-flight promise is cleared on settle so a later refresh can run again.
+ */
+export declare class TokenManager {
+    private accessToken;
+    private refreshToken;
+    private expiresAt;
+    private readonly refreshFn;
+    private readonly skewMs;
+    private inFlight;
+    constructor(opts: TokenManagerOptions);
+    /** Whether the token is within the skew window of (or past) expiry. */
+    private needsRefresh;
+    /**
+     * Single-flight refresh. Concurrent callers share one in-flight promise; it is
+     * cleared on settle (success or failure) so a subsequent refresh can proceed.
+     */
+    refreshNow(): Promise<void>;
+    /** Get a valid access token, refreshing proactively inside the skew window. */
+    getAccessToken(): Promise<string>;
+    /** Current absolute expiry (epoch ms). */
+    getExpiresAt(): number;
+    /**
+     * Run an authenticated request with reactive 401-replay. `call` receives a
+     * valid access token and returns a `Response`. On `401`, the token is
+     * refreshed once and `call` is invoked again exactly once.
+     */
+    withAuth(call: (accessToken: string) => Promise<Response>): Promise<Response>;
+}
+//# sourceMappingURL=index.d.ts.map

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

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