@voyantjs/catalog-mcp 0.19.0

package/README.md

@@ -0,0 +1,79 @@
+# @voyantjs/catalog-mcp
+
+Phase 2.x — MCP (Model Context Protocol) server scaffolding for the catalog
+plane. Wraps the catalog plane's APIs as agent-callable tools so AI assistants
+(Claude, ChatGPT plugins, custom agents) connect with tenant-scoped credentials
+and call tools rather than crafting REST calls.
+
+See [`docs/architecture/catalog-rag-architecture.md`](../../docs/architecture/catalog-rag-architecture.md)
+§3 + §12 (Open question 1).
+
+## Architectural commitment
+
+> AI agents query the API, not the vector database directly.
+
+The MCP tools wrap `getResolvedXById`, `executeSemanticSearch`,
+`federateAudienceSearch`, and the source adapter live-resolve / quote paths —
+**never the vector DB**. Visibility filtering, overlay resolution, audit, and
+rate limiting all happen at the API layer where they normally do. The MCP
+server is a thin transport.
+
+## Install
+
+```bash
+pnpm add @voyantjs/catalog-mcp
+```
+
+## What's in the box
+
+- **`./contract`** — `McpToolDefinition`, `McpToolHandler`, `McpToolContext`
+  types. Transport-agnostic: define the tool surface here, wire it into your
+  MCP transport of choice (the `@modelcontextprotocol/sdk`, your own HTTP
+  layer, an SSE handler, etc.).
+- **`./registry`** — `createMcpToolRegistry` + `dispatchTool` helpers.
+  Templates register all tools at startup and the registry exposes a
+  unified dispatch entry point for the transport layer.
+- **`./tools/*`** — Five canonical tools per the architecture doc:
+  - `search_catalog` — keyword / hybrid / semantic search across a vertical
+  - `get_entity` — fetch a single resolved CatalogEntry view
+  - `suggest_alternatives` — semantic similarity for "more like this"
+  - `check_availability` — calls the source adapter's volatile-live path
+  - `get_quote` — calls the source adapter to lock a price proposition
+
+## Tool isolation guarantees
+
+- All tools enforce visibility filtering through the catalog plane's resolver.
+  A `customer`-actor agent never receives staff-only fields, regardless of
+  how cleverly the agent crafts the search query.
+- `search_catalog` uses `executeSemanticSearch` — the agent's audience pool
+  is enforced server-side; cross-audience federation requires a `staff`-actor
+  context.
+- `check_availability` and `get_quote` route through the source adapter —
+  volatile-live values are always live, never cached, never embedded.
+
+## Wiring into an MCP transport
+
+Templates wire the registry into their MCP SDK transport of choice:
+
+```typescript
+import { createMcpToolRegistry } from "@voyantjs/catalog-mcp/registry"
+import { searchCatalogTool } from "@voyantjs/catalog-mcp/tools/search-catalog"
+import { getEntityTool } from "@voyantjs/catalog-mcp/tools/get-entity"
+// ... and so on
+
+const registry = createMcpToolRegistry({
+  context: {
+    actor: "staff",
+    tenantId: "operator_xyz",
+    catalog: { /* injected services */ },
+  },
+})
+
+registry.register(searchCatalogTool)
+registry.register(getEntityTool)
+// ... wire registry.dispatchTool into your MCP server's CallTool handler.
+```
+
+The `@modelcontextprotocol/sdk` is **not** a dependency of this package — the
+catalog-mcp surface is the tool definitions; the transport is the operator's
+choice (stdio for local dev, HTTP+SSE for hosted, custom for templates).

package/dist/contract.d.ts

@@ -0,0 +1,158 @@
+/**
+ * MCP tool contract — transport-agnostic shapes for catalog tools.
+ *
+ * Every catalog tool is defined as a `McpToolDefinition`: a name, a
+ * description (shown to the LLM), an input zod schema, and a handler that
+ * takes the parsed args + the per-request context and returns a structured
+ * result.
+ *
+ * Templates wire the registry into the actual MCP transport of their
+ * choice (the `@modelcontextprotocol/sdk` for stdio/HTTP+SSE, a custom
+ * Hono route, etc.). This package's surface ends at the tool definitions.
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §3 + §12.
+ */
+import type { IndexerAdapter, IndexerSlice, ResolverScope, Visibility } from "@voyantjs/catalog";
+import type { EmbeddingProvider } from "@voyantjs/catalog-rag";
+import type { z } from "zod";
+/**
+ * Per-request context passed to every tool handler.
+ *
+ * Templates construct this once per agent connection (typically derived
+ * from the agent's API key / OAuth token / session). The MCP transport
+ * passes the same context to every tool dispatch in that session.
+ */
+export interface McpToolContext {
+    /** The actor identity. Drives visibility filtering at every layer. */
+    actor: Visibility;
+    /** Tenant / operator identifier — usually synthesized into provenance. */
+    tenantId: string;
+    /** Default scope for tools that need locale / audience / market. */
+    defaultScope: ResolverScope;
+    /** Catalog services / adapters injected by the template. */
+    catalog: McpCatalogServices;
+}
+/**
+ * The catalog plane services tools call into. Templates inject the
+ * concrete instances (e.g. the IndexerAdapter, the EmbeddingProvider, the
+ * per-vertical resolved-fetch helpers) at registry construction time.
+ *
+ * Each service is optional — tools that need a service it isn't given
+ * fail with a clear error rather than producing wrong results silently.
+ */
+export interface McpCatalogServices {
+    /** Indexer for keyword / hybrid / semantic search. */
+    indexer?: IndexerAdapter;
+    /** Embedding provider — required for semantic / hybrid search. */
+    embeddings?: EmbeddingProvider;
+    /**
+     * Per-vertical resolved-fetch functions, keyed by vertical name. Each
+     * takes (entityId, scope) and returns the resolved view or null. Used
+     * by `get_entity` and `suggest_alternatives`.
+     */
+    resolveEntity?: (vertical: string, entityId: string, scope: ResolverScope) => Promise<McpResolvedEntity | null>;
+    /**
+     * Per-vertical live-availability function — calls the source adapter
+     * for volatile-live availability fields. Used by `check_availability`.
+     */
+    checkAvailability?: (vertical: string, entityId: string, parameters: Record<string, unknown>) => Promise<McpAvailabilityResult>;
+    /**
+     * Per-vertical live-quote function — calls the source adapter to lock
+     * a priced quote. Used by `get_quote`.
+     */
+    getQuote?: (vertical: string, entityId: string, parameters: Record<string, unknown>) => Promise<McpQuoteResult>;
+    /**
+     * Default slice resolver. Given a vertical + the context's defaultScope,
+     * returns the IndexerSlice the tool should query. Templates may override
+     * this to map their own audience taxonomy to slices.
+     */
+    defaultSliceFor?: (vertical: string, scope: ResolverScope) => IndexerSlice;
+}
+/** Resolved-view shape returned by `get_entity` and similar. */
+export interface McpResolvedEntity {
+    vertical: string;
+    entityId: string;
+    /** Resolved field values (visibility-filtered for the actor). */
+    fields: Record<string, unknown>;
+    /** Sources / provenance — which slice satisfied each overlayed field. */
+    provenance?: Record<string, {
+        locale: string;
+        audience: string;
+        market: string;
+    } | null>;
+}
+/** Live-availability response shape — exact shape is vertical-dependent. */
+export interface McpAvailabilityResult {
+    available: boolean;
+    /** Optional structured details (room counts, departure capacity, etc.). */
+    details?: Record<string, unknown>;
+    /** When the availability was checked — useful for UX timestamps. */
+    checkedAt: string;
+}
+/** Live-quote response shape. */
+export interface McpQuoteResult {
+    quoteId: string;
+    totalPrice: {
+        amount: string;
+        currency: string;
+    };
+    /** When the quote expires — agents should warn users about this. */
+    expiresAt?: string;
+    /** Optional structured breakdown — base / taxes / fees / surcharges. */
+    breakdown?: Record<string, unknown>;
+}
+/**
+ * MCP tool definition. The name + description are surfaced to the LLM;
+ * `inputSchema` validates and types the args; `handler` is the actual
+ * implementation.
+ *
+ * MCP standardly uses JSON Schema for inputSchema; we use Zod here and
+ * the registry helper exports a `toJsonSchema` adapter consumers wire
+ * into their MCP transport.
+ */
+export interface McpToolDefinition<TArgs = unknown, TResult = McpToolResult> {
+    /** Tool name, surfaced to the LLM. Convention: snake_case. */
+    name: string;
+    /** Human-readable description shown to the LLM. */
+    description: string;
+    /** Zod schema for the args; the dispatcher parses + validates. */
+    inputSchema: z.ZodType<TArgs>;
+    /** Handler — receives parsed args + context, returns the result. */
+    handler: McpToolHandler<TArgs, TResult>;
+}
+export type McpToolHandler<TArgs, TResult> = (args: TArgs, context: McpToolContext) => Promise<TResult>;
+/**
+ * Standard MCP tool result envelope. Mirrors MCP's `CallToolResult` shape:
+ * a `content` array of typed items (text, structured data) plus an optional
+ * `isError` flag for soft errors that the LLM should see.
+ */
+export interface McpToolResult {
+    content: McpToolContent[];
+    isError?: boolean;
+    /**
+     * Optional structured data the LLM can act on programmatically. Mirrors
+     * the MCP SDK's `structuredContent` field.
+     */
+    structuredContent?: Record<string, unknown>;
+}
+export type McpToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+    };
+};
+/**
+ * Standard error class for tool failures. The dispatcher catches these
+ * and translates them into MCP's standard error envelope.
+ */
+export declare class McpToolError extends Error {
+    readonly code: McpToolErrorCode;
+    readonly meta?: Record<string, unknown> | undefined;
+    constructor(message: string, code: McpToolErrorCode, meta?: Record<string, unknown> | undefined);
+}
+export type McpToolErrorCode = "MISSING_SERVICE" | "AUTHORIZATION_DENIED" | "NOT_FOUND" | "INVALID_INPUT" | "PROVIDER_ERROR";
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -0,0 +1,28 @@
+/**
+ * MCP tool contract — transport-agnostic shapes for catalog tools.
+ *
+ * Every catalog tool is defined as a `McpToolDefinition`: a name, a
+ * description (shown to the LLM), an input zod schema, and a handler that
+ * takes the parsed args + the per-request context and returns a structured
+ * result.
+ *
+ * Templates wire the registry into the actual MCP transport of their
+ * choice (the `@modelcontextprotocol/sdk` for stdio/HTTP+SSE, a custom
+ * Hono route, etc.). This package's surface ends at the tool definitions.
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §3 + §12.
+ */
+/**
+ * Standard error class for tool failures. The dispatcher catches these
+ * and translates them into MCP's standard error envelope.
+ */
+export class McpToolError extends Error {
+    code;
+    meta;
+    constructor(message, code, meta) {
+        super(message);
+        this.code = code;
+        this.meta = meta;
+        this.name = "McpToolError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type McpAvailabilityResult, type McpCatalogServices, type McpQuoteResult, type McpResolvedEntity, type McpToolContent, type McpToolContext, type McpToolDefinition, McpToolError, type McpToolErrorCode, type McpToolHandler, type McpToolResult, } from "./contract.js";
+export { type CreateMcpToolRegistryOptions, createMcpToolRegistry, enforceAudienceAuthorization, type McpToolListEntry, type McpToolRegistry, requireService, } from "./registry.js";
+export { type CheckAvailabilityArgs, checkAvailabilityTool, } from "./tools/check-availability.js";
+export { type GetEntityArgs, getEntityTool } from "./tools/get-entity.js";
+export { type GetQuoteArgs, getQuoteTool } from "./tools/get-quote.js";
+export { type SearchCatalogArgs, searchCatalogTool, } from "./tools/search-catalog.js";
+export { type SuggestAlternativesArgs, suggestAlternativesTool, } from "./tools/suggest-alternatives.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,4BAA4B,EAC5B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,KAAK,qBAAqB,EAC1B,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EACL,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,KAAK,uBAAuB,EAC5B,uBAAuB,GACxB,MAAM,iCAAiC,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// Contract types — McpToolDefinition, McpToolHandler, McpToolContext, results.
+export { McpToolError, } from "./contract.js";
+// Registry — register tools, dispatch by name, list, lookup.
+export { createMcpToolRegistry, enforceAudienceAuthorization, requireService, } from "./registry.js";
+// The five canonical catalog tools.
+export { checkAvailabilityTool, } from "./tools/check-availability.js";
+export { getEntityTool } from "./tools/get-entity.js";
+export { getQuoteTool } from "./tools/get-quote.js";
+export { searchCatalogTool, } from "./tools/search-catalog.js";
+export { suggestAlternativesTool, } from "./tools/suggest-alternatives.js";

package/dist/registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * MCP tool registry — register tool definitions, dispatch by name with
+ * args validation + context injection.
+ *
+ * The registry is transport-agnostic. Templates wire `dispatchTool` into
+ * their MCP transport's `CallTool` handler — typically the
+ * `@modelcontextprotocol/sdk` server, but anything that follows the MCP
+ * tool-call shape works.
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §3.
+ */
+import type { z } from "zod";
+import type { McpToolContext, McpToolDefinition, McpToolResult } from "./contract.js";
+export interface McpToolRegistry {
+    /** The context used for all tool dispatches in this registry. */
+    readonly context: McpToolContext;
+    /** Register a tool definition. Throws on duplicate name. */
+    register<TArgs>(tool: McpToolDefinition<TArgs, McpToolResult>): void;
+    /** List registered tool names — useful for the MCP `ListTools` request. */
+    list(): McpToolListEntry[];
+    /** Dispatch a tool call by name. Validates args with the tool's zod schema. */
+    dispatchTool(name: string, args: unknown): Promise<McpToolResult>;
+    /** Look up a registered tool. Returns `undefined` if not registered. */
+    get(name: string): McpToolDefinition<any, McpToolResult> | undefined;
+}
+export interface McpToolListEntry {
+    name: string;
+    description: string;
+    /**
+     * Zod schema serialized as a placeholder JSON Schema. Templates that
+     * need actual JSON Schema for the MCP SDK should call `zod-to-json-schema`
+     * (or equivalent) on the tool's `inputSchema` before publishing.
+     */
+    inputSchemaPreview: {
+        type: "object";
+        description: string;
+    };
+}
+export interface CreateMcpToolRegistryOptions {
+    context: McpToolContext;
+}
+export declare function createMcpToolRegistry(options: CreateMcpToolRegistryOptions): McpToolRegistry;
+/**
+ * Helper for tools to assert that a required catalog service was injected
+ * into the context. Throws `MISSING_SERVICE` if not, which the dispatcher
+ * translates into a structured error.
+ */
+export declare function requireService<T>(service: T | undefined, name: string): T;
+/**
+ * Helper for tools that need to enforce per-actor authorization. Customer/
+ * partner/supplier actors are pinned to their own audience pool — staff
+ * actors may federate across pools.
+ */
+export declare function enforceAudienceAuthorization(actor: McpToolContext["actor"], requestedAudiences?: string[]): void;
+export type { z };
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAGrF,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,iBAAiB,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,IAAI,CAAA;IACpE,2EAA2E;IAC3E,IAAI,IAAI,gBAAgB,EAAE,CAAA;IAC1B,+EAA+E;IAC/E,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IACjE,wEAAwE;IAExE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAC,GAAG,EAAE,aAAa,CAAC,GAAG,SAAS,CAAA;CACrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,kBAAkB,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5D;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,cAAc,CAAA;CACxB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,eAAe,CAuD5F;AAUD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CASzE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAC5B,IAAI,CASN;AAID,YAAY,EAAE,CAAC,EAAE,CAAA"}

package/dist/registry.js

@@ -0,0 +1,96 @@
+/**
+ * MCP tool registry — register tool definitions, dispatch by name with
+ * args validation + context injection.
+ *
+ * The registry is transport-agnostic. Templates wire `dispatchTool` into
+ * their MCP transport's `CallTool` handler — typically the
+ * `@modelcontextprotocol/sdk` server, but anything that follows the MCP
+ * tool-call shape works.
+ *
+ * See `docs/architecture/catalog-rag-architecture.md` §3.
+ */
+import { McpToolError } from "./contract.js";
+export function createMcpToolRegistry(options) {
+    // biome-ignore lint/suspicious/noExplicitAny: heterogeneous tool args
+    const tools = new Map();
+    return {
+        get context() {
+            return options.context;
+        },
+        register(tool) {
+            if (tools.has(tool.name)) {
+                throw new Error(`MCP tool "${tool.name}" is already registered`);
+            }
+            tools.set(tool.name, tool);
+        },
+        list() {
+            return Array.from(tools.values()).map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchemaPreview: {
+                    type: "object",
+                    description: "Use the package's zod-to-json-schema adapter to serialize for the MCP SDK.",
+                },
+            }));
+        },
+        get(name) {
+            return tools.get(name);
+        },
+        async dispatchTool(name, args) {
+            const tool = tools.get(name);
+            if (!tool) {
+                return errorResult(`MCP tool "${name}" is not registered. Known tools: ${Array.from(tools.keys()).join(", ") || "(none)"}`, "NOT_FOUND");
+            }
+            let parsed;
+            try {
+                parsed = tool.inputSchema.parse(args);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return errorResult(`Invalid input for tool "${name}": ${message}`, "INVALID_INPUT");
+            }
+            try {
+                return await tool.handler(parsed, options.context);
+            }
+            catch (err) {
+                if (err instanceof McpToolError) {
+                    return errorResult(err.message, err.code, err.meta);
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                return errorResult(`Tool "${name}" failed: ${message}`, "PROVIDER_ERROR");
+            }
+        },
+    };
+}
+function errorResult(message, code, meta) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `[${code}] ${message}` }],
+        structuredContent: { error: { code, message, ...(meta ?? {}) } },
+    };
+}
+/**
+ * Helper for tools to assert that a required catalog service was injected
+ * into the context. Throws `MISSING_SERVICE` if not, which the dispatcher
+ * translates into a structured error.
+ */
+export function requireService(service, name) {
+    if (!service) {
+        throw new McpToolError(`MCP tool requires the "${name}" service to be wired into the context, but it was not provided. Configure the registry's catalog services or omit tools that depend on it.`, "MISSING_SERVICE", { service: name });
+    }
+    return service;
+}
+/**
+ * Helper for tools that need to enforce per-actor authorization. Customer/
+ * partner/supplier actors are pinned to their own audience pool — staff
+ * actors may federate across pools.
+ */
+export function enforceAudienceAuthorization(actor, requestedAudiences) {
+    if (!requestedAudiences || requestedAudiences.length === 0)
+        return;
+    if (actor === "staff")
+        return;
+    if (requestedAudiences.length === 1 && requestedAudiences[0] === actor)
+        return;
+    throw new McpToolError(`Actor "${actor}" is not authorized to query audiences ${JSON.stringify(requestedAudiences)}. Non-staff actors may only query their own audience pool.`, "AUTHORIZATION_DENIED", { actor, requestedAudiences });
+}

package/dist/registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registry.test.d.ts.map

package/dist/registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.test.d.ts","sourceRoot":"","sources":["../src/registry.test.ts"],"names":[],"mappings":""}

package/dist/registry.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { McpToolError } from "./contract.js";
+import { createMcpToolRegistry, enforceAudienceAuthorization, requireService } from "./registry.js";
+const baseContext = {
+    actor: "staff",
+    tenantId: "op_test",
+    defaultScope: {
+        locale: "en-GB",
+        audience: "staff",
+        market: "default",
+        actor: "staff",
+    },
+    catalog: {},
+};
+const echoTool = {
+    name: "echo",
+    description: "Echo a message back.",
+    inputSchema: z.object({ message: z.string() }),
+    async handler(args) {
+        return { content: [{ type: "text", text: args.message }] };
+    },
+};
+describe("createMcpToolRegistry", () => {
+    it("registers and dispatches a tool", async () => {
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(echoTool);
+        const result = await registry.dispatchTool("echo", { message: "hello" });
+        expect(result.content[0]).toEqual({ type: "text", text: "hello" });
+    });
+    it("throws on duplicate registration", () => {
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(echoTool);
+        expect(() => registry.register(echoTool)).toThrow(/already registered/);
+    });
+    it("returns NOT_FOUND for unknown tool names", async () => {
+        const registry = createMcpToolRegistry({ context: baseContext });
+        const result = await registry.dispatchTool("phantom", {});
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "NOT_FOUND" });
+    });
+    it("returns INVALID_INPUT when args fail schema validation", async () => {
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(echoTool);
+        const result = await registry.dispatchTool("echo", { message: 123 });
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "INVALID_INPUT" });
+    });
+    it("translates McpToolError thrown by the handler to its code", async () => {
+        const failingTool = {
+            name: "fail",
+            description: "Always fails.",
+            inputSchema: z.object({}),
+            async handler() {
+                throw new McpToolError("nope", "AUTHORIZATION_DENIED", { reason: "test" });
+            },
+        };
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(failingTool);
+        const result = await registry.dispatchTool("fail", {});
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({
+            code: "AUTHORIZATION_DENIED",
+            message: "nope",
+            reason: "test",
+        });
+    });
+    it("translates other thrown errors to PROVIDER_ERROR", async () => {
+        const failingTool = {
+            name: "boom",
+            description: "Throws plain Error.",
+            inputSchema: z.object({}),
+            async handler() {
+                throw new Error("network down");
+            },
+        };
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(failingTool);
+        const result = await registry.dispatchTool("boom", {});
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "PROVIDER_ERROR" });
+    });
+    it("list() exposes registered tool metadata", () => {
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(echoTool);
+        const list = registry.list();
+        expect(list).toHaveLength(1);
+        expect(list[0]?.name).toBe("echo");
+        expect(list[0]?.description).toBe("Echo a message back.");
+    });
+    it("get() returns the registered tool by name", () => {
+        const registry = createMcpToolRegistry({ context: baseContext });
+        registry.register(echoTool);
+        expect(registry.get("echo")?.name).toBe("echo");
+        expect(registry.get("phantom")).toBeUndefined();
+    });
+});
+describe("requireService", () => {
+    it("returns the service when present", () => {
+        const indexer = { mock: true };
+        expect(requireService(indexer, "indexer")).toBe(indexer);
+    });
+    it("throws MISSING_SERVICE when undefined", () => {
+        expect(() => requireService(undefined, "indexer")).toThrow(McpToolError);
+        try {
+            requireService(undefined, "indexer");
+        }
+        catch (err) {
+            expect(err.code).toBe("MISSING_SERVICE");
+        }
+    });
+});
+describe("enforceAudienceAuthorization", () => {
+    it("staff actors may query any audience", () => {
+        expect(() => enforceAudienceAuthorization("staff", ["customer", "partner"])).not.toThrow();
+    });
+    it("non-staff actors may query only their own audience", () => {
+        expect(() => enforceAudienceAuthorization("customer", ["customer"])).not.toThrow();
+    });
+    it("non-staff actors trying to query another audience throws", () => {
+        expect(() => enforceAudienceAuthorization("customer", ["partner"])).toThrow(/not authorized/);
+    });
+    it("non-staff actors trying to federate throws", () => {
+        expect(() => enforceAudienceAuthorization("customer", ["customer", "partner"])).toThrow(/not authorized/);
+    });
+    it("empty audience list short-circuits without checks", () => {
+        expect(() => enforceAudienceAuthorization("customer", [])).not.toThrow();
+        expect(() => enforceAudienceAuthorization("customer", undefined)).not.toThrow();
+    });
+});

package/dist/tools/check-availability.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `check_availability` tool — calls the source adapter's volatile-live
+ * availability path. Per architecture, volatile-live values are always
+ * fetched live, never indexed, never embedded.
+ */
+import { z } from "zod";
+import type { McpToolDefinition, McpToolResult } from "../contract.js";
+declare const checkAvailabilityArgs: z.ZodObject<{
+    vertical: z.ZodString;
+    entityId: z.ZodString;
+    parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CheckAvailabilityArgs = z.infer<typeof checkAvailabilityArgs>;
+export declare const checkAvailabilityTool: McpToolDefinition<CheckAvailabilityArgs, McpToolResult>;
+export {};
+//# sourceMappingURL=check-availability.d.ts.map

package/dist/tools/check-availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-availability.d.ts","sourceRoot":"","sources":["../../src/tools/check-availability.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGtE,QAAA,MAAM,qBAAqB;;;;iBASzB,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,eAAO,MAAM,qBAAqB,EAAE,iBAAiB,CAAC,qBAAqB,EAAE,aAAa,CAyBzF,CAAA"}

package/dist/tools/check-availability.js

@@ -0,0 +1,38 @@
+/**
+ * `check_availability` tool — calls the source adapter's volatile-live
+ * availability path. Per architecture, volatile-live values are always
+ * fetched live, never indexed, never embedded.
+ */
+import { z } from "zod";
+import { requireService } from "../registry.js";
+const checkAvailabilityArgs = z.object({
+    vertical: z.string().describe("The catalog vertical."),
+    entityId: z.string().describe("Entity id."),
+    parameters: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe("Vertical-specific parameters: dates, occupancy, currency, market — whatever the live-availability call needs."),
+});
+export const checkAvailabilityTool = {
+    name: "check_availability",
+    description: "Check live availability for a catalog entry. Routes through the configured source adapter — " +
+        "values are always fresh, never cached at the catalog plane. Use this before suggesting a quote.",
+    inputSchema: checkAvailabilityArgs,
+    async handler(args, context) {
+        const checkAvailability = requireService(context.catalog.checkAvailability, "checkAvailability");
+        const result = await checkAvailability(args.vertical, args.entityId, args.parameters);
+        const summary = result.available
+            ? `${args.vertical}/${args.entityId} is AVAILABLE (checked at ${result.checkedAt}).`
+            : `${args.vertical}/${args.entityId} is NOT AVAILABLE (checked at ${result.checkedAt}).`;
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: {
+                vertical: args.vertical,
+                entityId: args.entityId,
+                available: result.available,
+                checkedAt: result.checkedAt,
+                details: result.details,
+            },
+        };
+    },
+};