@voyantjs/catalog-mcp 0.19.0

package/dist/tools/get-entity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `get_entity` tool — fetch a single resolved CatalogEntry view by id.
+ * Wraps the per-vertical `resolveEntity` helper injected via context.
+ */
+import { z } from "zod";
+import type { McpToolDefinition, McpToolResult } from "../contract.js";
+declare const getEntityArgs: z.ZodObject<{
+    vertical: z.ZodString;
+    entityId: z.ZodString;
+}, z.core.$strip>;
+export type GetEntityArgs = z.infer<typeof getEntityArgs>;
+export declare const getEntityTool: McpToolDefinition<GetEntityArgs, McpToolResult>;
+export {};
+//# sourceMappingURL=get-entity.d.ts.map

package/dist/tools/get-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-entity.d.ts","sourceRoot":"","sources":["../../src/tools/get-entity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGtE,QAAA,MAAM,aAAa;;;iBAKjB,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD,eAAO,MAAM,aAAa,EAAE,iBAAiB,CAAC,aAAa,EAAE,aAAa,CAoDzE,CAAA"}

package/dist/tools/get-entity.js

@@ -0,0 +1,60 @@
+/**
+ * `get_entity` tool — fetch a single resolved CatalogEntry view by id.
+ * Wraps the per-vertical `resolveEntity` helper injected via context.
+ */
+import { z } from "zod";
+import { requireService } from "../registry.js";
+const getEntityArgs = z.object({
+    vertical: z
+        .string()
+        .describe('The catalog vertical (e.g. "products", "cruises", "hospitality").'),
+    entityId: z.string().describe("Entity id."),
+});
+export const getEntityTool = {
+    name: "get_entity",
+    description: "Fetch a single resolved CatalogEntry by vertical + id. Returns the visibility-filtered view " +
+        "for the calling actor (overlays applied, internal-only fields hidden when applicable).",
+    inputSchema: getEntityArgs,
+    async handler(args, context) {
+        const resolveEntity = requireService(context.catalog.resolveEntity, "resolveEntity");
+        const view = await resolveEntity(args.vertical, args.entityId, context.defaultScope);
+        if (!view) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `[NOT_FOUND] No ${args.vertical} entity with id "${args.entityId}".`,
+                    },
+                ],
+                structuredContent: {
+                    error: { code: "NOT_FOUND", vertical: args.vertical, entityId: args.entityId },
+                },
+            };
+        }
+        const title = view.fields.title ??
+            view.fields.name ??
+            view.entityId;
+        const description = view.fields.description ??
+            view.fields.shortDescription ??
+            "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# ${title}`,
+                        description ? `\n${description}` : "",
+                        `\n_id: ${view.entityId} • vertical: ${view.vertical}_`,
+                    ].join("\n"),
+                },
+            ],
+            structuredContent: {
+                vertical: view.vertical,
+                entityId: view.entityId,
+                fields: view.fields,
+                provenance: view.provenance,
+            },
+        };
+    },
+};

package/dist/tools/get-quote.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `get_quote` tool — calls the source adapter to lock a priced quote.
+ * Live-pricing path; never cached, never embedded.
+ *
+ * The returned `quoteId` can be passed to a downstream booking flow. The
+ * `expiresAt` field tells agents when to warn users that the price may
+ * change.
+ */
+import { z } from "zod";
+import type { McpToolDefinition, McpToolResult } from "../contract.js";
+declare const getQuoteArgs: z.ZodObject<{
+    vertical: z.ZodString;
+    entityId: z.ZodString;
+    parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type GetQuoteArgs = z.infer<typeof getQuoteArgs>;
+export declare const getQuoteTool: McpToolDefinition<GetQuoteArgs, McpToolResult>;
+export {};
+//# sourceMappingURL=get-quote.d.ts.map

package/dist/tools/get-quote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-quote.d.ts","sourceRoot":"","sources":["../../src/tools/get-quote.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGtE,QAAA,MAAM,YAAY;;;;iBAOhB,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEvD,eAAO,MAAM,YAAY,EAAE,iBAAiB,CAAC,YAAY,EAAE,aAAa,CA0BvE,CAAA"}

package/dist/tools/get-quote.js

@@ -0,0 +1,42 @@
+/**
+ * `get_quote` tool — calls the source adapter to lock a priced quote.
+ * Live-pricing path; never cached, never embedded.
+ *
+ * The returned `quoteId` can be passed to a downstream booking flow. The
+ * `expiresAt` field tells agents when to warn users that the price may
+ * change.
+ */
+import { z } from "zod";
+import { requireService } from "../registry.js";
+const getQuoteArgs = 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 quote parameters: dates, pax, currency, fare class, etc."),
+});
+export const getQuoteTool = {
+    name: "get_quote",
+    description: "Lock a live priced quote for a catalog entry. Returns a quoteId that can be passed to a " +
+        "booking flow plus the locked total price and an optional expiry timestamp. " +
+        "Always live; never cached at the catalog plane.",
+    inputSchema: getQuoteArgs,
+    async handler(args, context) {
+        const getQuote = requireService(context.catalog.getQuote, "getQuote");
+        const result = await getQuote(args.vertical, args.entityId, args.parameters);
+        const expiry = result.expiresAt ? ` (expires ${result.expiresAt})` : "";
+        const summary = `Quote ${result.quoteId} for ${args.vertical}/${args.entityId}: ${result.totalPrice.amount} ${result.totalPrice.currency}${expiry}.`;
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: {
+                vertical: args.vertical,
+                entityId: args.entityId,
+                quoteId: result.quoteId,
+                totalPrice: result.totalPrice,
+                expiresAt: result.expiresAt,
+                breakdown: result.breakdown,
+            },
+        };
+    },
+};

package/dist/tools/search-catalog.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `search_catalog` tool — keyword / hybrid / semantic search across a
+ * vertical. Wraps `executeSemanticSearch` from `@voyantjs/catalog-rag`.
+ *
+ * Visibility filtering and audience-pool enforcement happen at the
+ * underlying API layer; the tool just wires args through.
+ */
+import { z } from "zod";
+import type { McpToolDefinition, McpToolResult } from "../contract.js";
+declare const searchCatalogArgs: z.ZodObject<{
+    vertical: z.ZodString;
+    query: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<{
+        keyword: "keyword";
+        semantic: "semantic";
+        hybrid: "hybrid";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            in: "in";
+            range: "range";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type SearchCatalogArgs = z.infer<typeof searchCatalogArgs>;
+export declare const searchCatalogTool: McpToolDefinition<SearchCatalogArgs, McpToolResult>;
+export {};
+//# sourceMappingURL=search-catalog.d.ts.map

package/dist/tools/search-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-catalog.d.ts","sourceRoot":"","sources":["../../src/tools/search-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGtE,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;iBAkBrB,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE,eAAO,MAAM,iBAAiB,EAAE,iBAAiB,CAAC,iBAAiB,EAAE,aAAa,CA+DjF,CAAA"}

package/dist/tools/search-catalog.js

@@ -0,0 +1,107 @@
+/**
+ * `search_catalog` tool — keyword / hybrid / semantic search across a
+ * vertical. Wraps `executeSemanticSearch` from `@voyantjs/catalog-rag`.
+ *
+ * Visibility filtering and audience-pool enforcement happen at the
+ * underlying API layer; the tool just wires args through.
+ */
+import { executeSemanticSearch } from "@voyantjs/catalog-rag";
+import { z } from "zod";
+import { enforceAudienceAuthorization, requireService } from "../registry.js";
+const searchCatalogArgs = z.object({
+    vertical: z.string().describe('The catalog vertical to search (e.g. "products", "cruises").'),
+    query: z.string().describe("Free-text query."),
+    mode: z
+        .enum(["keyword", "hybrid", "semantic"])
+        .default("hybrid")
+        .describe("Search mode. Hybrid blends keyword + vector; semantic is pure vector."),
+    limit: z.number().int().positive().max(100).default(20).describe("Max results."),
+    filters: z
+        .array(z.object({
+        field: z.string(),
+        op: z.enum(["eq", "in", "range"]),
+        value: z.unknown(),
+    }))
+        .optional()
+        .describe("Optional filter expressions (engine-translated)."),
+});
+export const searchCatalogTool = {
+    name: "search_catalog",
+    description: "Search a catalog vertical for sellable inventory matching a free-text query. " +
+        "Supports keyword, hybrid (keyword + semantic), or pure semantic search modes. " +
+        "Results are visibility-filtered for the calling actor; non-staff actors only see their own audience's view.",
+    inputSchema: searchCatalogArgs,
+    async handler(args, context) {
+        const indexer = requireService(context.catalog.indexer, "indexer");
+        const slice = (context.catalog.defaultSliceFor ??
+            ((vertical) => ({
+                vertical,
+                locale: context.defaultScope.locale,
+                audience: context.defaultScope.audience,
+                market: context.defaultScope.market,
+            })))(args.vertical, context.defaultScope);
+        enforceAudienceAuthorization(context.actor, [slice.audience]);
+        const results = args.mode === "keyword"
+            ? await indexer.search(slice, {
+                query: args.query,
+                mode: "keyword",
+                pagination: { limit: args.limit },
+                filters: args.filters?.map(toSearchFilter),
+            })
+            : await executeSemanticSearch({
+                adapter: indexer,
+                embeddings: requireService(context.catalog.embeddings, "embeddings"),
+                slice,
+                request: {
+                    query: args.query,
+                    mode: args.mode,
+                    pagination: { limit: args.limit },
+                    filters: args.filters?.map(toSearchFilter),
+                },
+            });
+        const summary = `Found ${results.hits.length} result(s) in ${args.vertical}.`;
+        const lines = results.hits.slice(0, args.limit).map((hit, i) => {
+            const title = hit.document.fields.title ??
+                hit.document.fields.name ??
+                hit.id;
+            return `${i + 1}. ${title} (id: ${hit.id}, score: ${hit.score.toFixed(2)})`;
+        });
+        return {
+            content: [{ type: "text", text: [summary, ...lines].join("\n") }],
+            structuredContent: {
+                vertical: args.vertical,
+                total: results.total,
+                hits: results.hits.slice(0, args.limit).map((hit) => ({
+                    id: hit.id,
+                    score: hit.score,
+                    fields: hit.document.fields,
+                })),
+            },
+        };
+    },
+};
+function toSearchFilter(filter) {
+    switch (filter.op) {
+        case "eq":
+            return {
+                kind: "eq",
+                field: filter.field,
+                value: filter.value,
+            };
+        case "in":
+            return {
+                kind: "in",
+                field: filter.field,
+                values: filter.value,
+            };
+        case "range": {
+            const range = filter.value;
+            return {
+                kind: "range",
+                field: filter.field,
+                gte: range.gte,
+                lte: range.lte,
+            };
+        }
+    }
+}

package/dist/tools/suggest-alternatives.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `suggest_alternatives` tool — semantic similarity for "more like this".
+ * Fetches the seed entity, then runs a semantic search using a synthesized
+ * query built from the entity's title + description.
+ *
+ * Useful for AI agents asked "show me products like X" — the agent calls
+ * this rather than crafting its own search query.
+ */
+import { z } from "zod";
+import type { McpToolDefinition, McpToolResult } from "../contract.js";
+declare const suggestAlternativesArgs: z.ZodObject<{
+    vertical: z.ZodString;
+    seedEntityId: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SuggestAlternativesArgs = z.infer<typeof suggestAlternativesArgs>;
+export declare const suggestAlternativesTool: McpToolDefinition<SuggestAlternativesArgs, McpToolResult>;
+export {};
+//# sourceMappingURL=suggest-alternatives.d.ts.map

package/dist/tools/suggest-alternatives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-alternatives.d.ts","sourceRoot":"","sources":["../../src/tools/suggest-alternatives.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGtE,QAAA,MAAM,uBAAuB;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,uBAAuB,EAAE,aAAa,CAsF7F,CAAA"}

package/dist/tools/suggest-alternatives.js

@@ -0,0 +1,90 @@
+/**
+ * `suggest_alternatives` tool — semantic similarity for "more like this".
+ * Fetches the seed entity, then runs a semantic search using a synthesized
+ * query built from the entity's title + description.
+ *
+ * Useful for AI agents asked "show me products like X" — the agent calls
+ * this rather than crafting its own search query.
+ */
+import { executeSemanticSearch } from "@voyantjs/catalog-rag";
+import { z } from "zod";
+import { enforceAudienceAuthorization, requireService } from "../registry.js";
+const suggestAlternativesArgs = z.object({
+    vertical: z.string().describe("The catalog vertical to search."),
+    seedEntityId: z.string().describe("Id of the entity to find alternatives for."),
+    limit: z.number().int().positive().max(50).default(10).describe("Max alternatives to return."),
+});
+export const suggestAlternativesTool = {
+    name: "suggest_alternatives",
+    description: "Find catalog entries semantically similar to a seed entity. The seed's title + description " +
+        "are vectorized and matched against the audience's embedding pool. The seed itself is excluded from results.",
+    inputSchema: suggestAlternativesArgs,
+    async handler(args, context) {
+        const indexer = requireService(context.catalog.indexer, "indexer");
+        const embeddings = requireService(context.catalog.embeddings, "embeddings");
+        const resolveEntity = requireService(context.catalog.resolveEntity, "resolveEntity");
+        const seed = await resolveEntity(args.vertical, args.seedEntityId, context.defaultScope);
+        if (!seed) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `[NOT_FOUND] No ${args.vertical} entity with id "${args.seedEntityId}".`,
+                    },
+                ],
+                structuredContent: {
+                    error: {
+                        code: "NOT_FOUND",
+                        vertical: args.vertical,
+                        entityId: args.seedEntityId,
+                    },
+                },
+            };
+        }
+        const titlePart = seed.fields.title ?? seed.fields.name ?? "";
+        const descPart = seed.fields.description ??
+            seed.fields.shortDescription ??
+            "";
+        const query = `${titlePart}\n${descPart}`.trim();
+        const slice = (context.catalog.defaultSliceFor ??
+            ((vertical) => ({
+                vertical,
+                locale: context.defaultScope.locale,
+                audience: context.defaultScope.audience,
+                market: context.defaultScope.market,
+            })))(args.vertical, context.defaultScope);
+        enforceAudienceAuthorization(context.actor, [slice.audience]);
+        const results = await executeSemanticSearch({
+            adapter: indexer,
+            embeddings,
+            slice,
+            request: {
+                query,
+                mode: "semantic",
+                pagination: { limit: args.limit + 1 },
+            },
+        });
+        // Drop the seed itself if it surfaces in results.
+        const filtered = results.hits.filter((hit) => hit.id !== args.seedEntityId).slice(0, args.limit);
+        const summary = `Found ${filtered.length} alternative(s) similar to ${titlePart || args.seedEntityId}.`;
+        const lines = filtered.map((hit, i) => {
+            const t = hit.document.fields.title ??
+                hit.document.fields.name ??
+                hit.id;
+            return `${i + 1}. ${t} (id: ${hit.id}, similarity: ${hit.score.toFixed(2)})`;
+        });
+        return {
+            content: [{ type: "text", text: [summary, ...lines].join("\n") }],
+            structuredContent: {
+                vertical: args.vertical,
+                seedEntityId: args.seedEntityId,
+                alternatives: filtered.map((hit) => ({
+                    id: hit.id,
+                    score: hit.score,
+                    fields: hit.document.fields,
+                })),
+            },
+        };
+    },
+};

package/dist/tools/tools.test.d.ts

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

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

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

package/dist/tools/tools.test.js

@@ -0,0 +1,217 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMcpToolRegistry } from "../registry.js";
+import { checkAvailabilityTool } from "./check-availability.js";
+import { getEntityTool } from "./get-entity.js";
+import { getQuoteTool } from "./get-quote.js";
+import { searchCatalogTool } from "./search-catalog.js";
+import { suggestAlternativesTool } from "./suggest-alternatives.js";
+const indexerCapabilities = {
+    supportsKeywordSearch: true,
+    supportsHybridSearch: true,
+    supportsVectorFields: true,
+    vectorDimensions: 3,
+    maxVectorsPerDocument: null,
+    supportsCrossAudienceFederation: false,
+    supportsAdminDenormalization: true,
+};
+function makeContext(overrides = {}) {
+    return {
+        actor: "staff",
+        tenantId: "op_test",
+        defaultScope: { locale: "en-GB", audience: "staff", market: "default", actor: "staff" },
+        catalog: overrides,
+    };
+}
+function hit(id, score, fields = {}) {
+    return { id, score, document: { id, fields: { id, ...fields } } };
+}
+function makeIndexer(hits = []) {
+    return {
+        capabilities: indexerCapabilities,
+        async ensureCollection() { },
+        async upsert() { },
+        async delete() { },
+        async bulkReindex() { },
+        async search() {
+            return { hits, total: hits.length };
+        },
+    };
+}
+const stubEmbeddings = {
+    capabilities: {
+        modelId: "stub/v1",
+        dimensions: 3,
+        maxTokensPerInput: 1000,
+        maxBatchSize: 100,
+    },
+    async embed(texts) {
+        return texts.map(() => [0.1, 0.2, 0.3]);
+    },
+};
+describe("searchCatalogTool", () => {
+    it("returns hits as text + structured content", async () => {
+        const context = makeContext({
+            indexer: makeIndexer([hit("a", 0.9, { title: "Alpha" }), hit("b", 0.7, { title: "Beta" })]),
+            embeddings: stubEmbeddings,
+        });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(searchCatalogTool);
+        const result = await registry.dispatchTool("search_catalog", {
+            vertical: "products",
+            query: "wellness",
+            mode: "keyword",
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.structuredContent?.total).toBe(2);
+        expect((result.structuredContent?.hits)[0]?.id).toBe("a");
+    });
+    it("MISSING_SERVICE error when indexer not configured", async () => {
+        const context = makeContext({ embeddings: stubEmbeddings });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(searchCatalogTool);
+        const result = await registry.dispatchTool("search_catalog", {
+            vertical: "products",
+            query: "wellness",
+        });
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "MISSING_SERVICE" });
+    });
+    it("MISSING_SERVICE for embeddings when mode requires them", async () => {
+        const context = makeContext({ indexer: makeIndexer() });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(searchCatalogTool);
+        const result = await registry.dispatchTool("search_catalog", {
+            vertical: "products",
+            query: "x",
+            mode: "semantic",
+        });
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "MISSING_SERVICE" });
+    });
+});
+describe("getEntityTool", () => {
+    it("returns the resolved view with title + description", async () => {
+        const resolveEntity = vi.fn(async (vertical, entityId) => ({
+            vertical,
+            entityId,
+            fields: { title: "Bali Wellness", description: "Source description" },
+        }));
+        const context = makeContext({ resolveEntity });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(getEntityTool);
+        const result = await registry.dispatchTool("get_entity", {
+            vertical: "products",
+            entityId: "prod_xyz",
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.structuredContent?.entityId).toBe("prod_xyz");
+        expect((result.structuredContent?.fields).title).toBe("Bali Wellness");
+    });
+    it("returns NOT_FOUND when the entity doesn't exist", async () => {
+        const resolveEntity = vi.fn(async () => null);
+        const context = makeContext({ resolveEntity });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(getEntityTool);
+        const result = await registry.dispatchTool("get_entity", {
+            vertical: "products",
+            entityId: "phantom",
+        });
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "NOT_FOUND" });
+    });
+});
+describe("suggestAlternativesTool", () => {
+    it("excludes the seed entity from results", async () => {
+        const resolveEntity = vi.fn(async (vertical, entityId) => ({
+            vertical,
+            entityId,
+            fields: { title: "Bali Wellness", description: "yoga retreat" },
+        }));
+        const context = makeContext({
+            indexer: makeIndexer([
+                hit("seed_xyz", 0.99, { title: "Bali Wellness" }),
+                hit("alt_1", 0.85, { title: "Bali Yoga" }),
+                hit("alt_2", 0.75, { title: "Ubud Spa" }),
+            ]),
+            embeddings: stubEmbeddings,
+            resolveEntity,
+        });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(suggestAlternativesTool);
+        const result = await registry.dispatchTool("suggest_alternatives", {
+            vertical: "products",
+            seedEntityId: "seed_xyz",
+            limit: 5,
+        });
+        expect(result.isError).toBeUndefined();
+        const alts = result.structuredContent?.alternatives;
+        expect(alts).toHaveLength(2);
+        expect(alts.map((a) => a.id)).not.toContain("seed_xyz");
+    });
+    it("returns NOT_FOUND when the seed entity doesn't exist", async () => {
+        const context = makeContext({
+            indexer: makeIndexer(),
+            embeddings: stubEmbeddings,
+            resolveEntity: async () => null,
+        });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(suggestAlternativesTool);
+        const result = await registry.dispatchTool("suggest_alternatives", {
+            vertical: "products",
+            seedEntityId: "phantom",
+        });
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "NOT_FOUND" });
+    });
+});
+describe("checkAvailabilityTool", () => {
+    it("calls the live availability function and surfaces availability", async () => {
+        const checkAvailability = vi.fn(async () => ({
+            available: true,
+            details: { rooms_left: 3 },
+            checkedAt: "2026-09-01T12:00:00Z",
+        }));
+        const context = makeContext({ checkAvailability });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(checkAvailabilityTool);
+        const result = await registry.dispatchTool("check_availability", {
+            vertical: "hospitality",
+            entityId: "rmtp_xyz",
+            parameters: { dates: "2026-10-15..2026-10-22" },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.structuredContent?.available).toBe(true);
+    });
+});
+describe("getQuoteTool", () => {
+    it("returns the locked quote with expiry timestamp", async () => {
+        const getQuote = vi.fn(async () => ({
+            quoteId: "q_abc",
+            totalPrice: { amount: "1500.00", currency: "EUR" },
+            expiresAt: "2026-09-01T13:00:00Z",
+        }));
+        const context = makeContext({ getQuote });
+        const registry = createMcpToolRegistry({ context });
+        registry.register(getQuoteTool);
+        const result = await registry.dispatchTool("get_quote", {
+            vertical: "products",
+            entityId: "prod_xyz",
+            parameters: { dates: "2026-10-15..2026-10-22", pax: 2 },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(result.structuredContent?.quoteId).toBe("q_abc");
+        expect((result.structuredContent?.totalPrice).amount).toBe("1500.00");
+    });
+    it("MISSING_SERVICE when getQuote function not configured", async () => {
+        const context = makeContext({});
+        const registry = createMcpToolRegistry({ context });
+        registry.register(getQuoteTool);
+        const result = await registry.dispatchTool("get_quote", {
+            vertical: "products",
+            entityId: "x",
+            parameters: {},
+        });
+        expect(result.isError).toBe(true);
+        expect(result.structuredContent?.error).toMatchObject({ code: "MISSING_SERVICE" });
+    });
+});