@reactionary/mcp 0.0.0-stage → 0.0.1

package/lib/reactionary-mcp-server.js

@@ -0,0 +1,322 @@
+import {
+  createMcpHandler,
+  fromJsonSchema,
+  McpServer
+} from "@modelcontextprotocol/server";
+import {
+  toNodeHandler
+} from "@modelcontextprotocol/node";
+import {
+  createInitialRequestContext,
+  MemoryCache,
+  SessionSchema
+} from "@reactionary/core";
+import * as z from "zod";
+import {
+  discoverReactionaryMCPTools
+} from "./tool-discovery.js";
+import {
+  REACTIONARY_SHOPPING_AGENT_GUIDE,
+  REACTIONARY_SHOPPING_AGENT_GUIDE_PROMPT,
+  REACTIONARY_SHOPPING_AGENT_GUIDE_URI
+} from "./shopping-agent-guide.js";
+class ReactionaryMCPServer {
+  constructor(clientFactory, options = {}) {
+    this.clientFactory = clientFactory;
+    this.options = options;
+    this.sessionStore = new ReactionaryMCPSessionStore(
+      this.options.sessionCache ?? new MemoryCache(),
+      this.options.sessionTtlSeconds ?? 60 * 60 * 24
+    );
+    this.handler = createMcpHandler(
+      (ctx) => this.createServer(getMcpSessionId(ctx.requestInfo)),
+      this.options.handler
+    );
+  }
+  clientFactory;
+  options;
+  handler;
+  sessionStore;
+  fetch(request, options) {
+    const sessionId = getOrCreateMcpSessionId(request);
+    const sessionRequest = withMcpSessionId(request, sessionId);
+    return this.handler.fetch(sessionRequest, options).then((response) => {
+      response.headers.set(MCP_SESSION_ID_HEADER, sessionId);
+      return response;
+    });
+  }
+  getHandler() {
+    return {
+      ...this.handler,
+      fetch: (request, options) => this.fetch(request, options),
+      close: () => this.close()
+    };
+  }
+  toNodeHandler() {
+    return toNodeHandler(this.getHandler());
+  }
+  close() {
+    return this.handler.close();
+  }
+  discoverTools() {
+    return this.discoverToolsForClient(
+      this.clientFactory(createInitialRequestContext())
+    );
+  }
+  async createServer(sessionId) {
+    const restoredSession = sessionId ? await this.sessionStore.get(sessionId) : void 0;
+    const requestContext = createInitialRequestContext();
+    if (restoredSession) {
+      requestContext.session = restoredSession;
+    }
+    const client = this.clientFactory(requestContext);
+    const server = new McpServer({
+      name: this.options.name ?? "@reactionary/mcp",
+      version: this.options.version ?? "0.0.1"
+    });
+    this.registerShoppingAgentGuide(server);
+    for (const tool of this.discoverToolsForClient(client)) {
+      this.registerTool(server, tool, sessionId, requestContext);
+    }
+    return server;
+  }
+  discoverToolsForClient(client) {
+    return discoverReactionaryMCPTools(client, this.options);
+  }
+  registerShoppingAgentGuide(server) {
+    server.registerResource(
+      "reactionary-shopping-agent-guide",
+      REACTIONARY_SHOPPING_AGENT_GUIDE_URI,
+      {
+        title: "Reactionary Shopping Agent Guide",
+        description: "Operational guide for combining Reactionary MCP shopping tools safely.",
+        mimeType: "text/markdown"
+      },
+      (uri) => ({
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: REACTIONARY_SHOPPING_AGENT_GUIDE
+          }
+        ]
+      })
+    );
+    server.registerPrompt(
+      REACTIONARY_SHOPPING_AGENT_GUIDE_PROMPT,
+      {
+        title: "Reactionary Shopping Agent Guide",
+        description: "Use this prompt to learn the recommended search, product, cart, checkout, and guardrail flow for Reactionary MCP tools."
+      },
+      () => ({
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: REACTIONARY_SHOPPING_AGENT_GUIDE
+            }
+          }
+        ]
+      })
+    );
+  }
+  registerTool(server, tool, sessionId, requestContext) {
+    const inputSchema = acceptsUndefined(tool.entrypoint.inputSchema) ? void 0 : toMcpSchema(tool.entrypoint.inputSchema);
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.entrypoint.title,
+        description: tool.entrypoint.description,
+        inputSchema,
+        outputSchema: toMcpOutputSchema(tool.entrypoint.outputSchema)
+      },
+      async (args) => {
+        const result = await callReactionaryTool(
+          tool,
+          inputSchema ? args : void 0
+        );
+        if (sessionId) {
+          await this.sessionStore.put(sessionId, requestContext.session);
+        }
+        return resultToCallToolResult(result);
+      }
+    );
+  }
+}
+const MCP_SESSION_ID_HEADER = "mcp-session-id";
+const SESSION_CACHE_KEY_PREFIX = "reactionary:mcp:session";
+class ReactionaryMCPSessionStore {
+  constructor(cache, ttlSeconds) {
+    this.cache = cache;
+    this.ttlSeconds = ttlSeconds;
+  }
+  cache;
+  ttlSeconds;
+  async get(sessionId) {
+    return await this.cache.get(
+      this.getCacheKey(sessionId),
+      SessionSchema
+    ) ?? void 0;
+  }
+  async put(sessionId, session) {
+    await this.cache.invalidate([this.getDependencyId(sessionId)]);
+    await this.cache.put(this.getCacheKey(sessionId), session, {
+      ttlSeconds: this.ttlSeconds,
+      dependencyIds: [this.getDependencyId(sessionId)]
+    });
+  }
+  getCacheKey(sessionId) {
+    return `${SESSION_CACHE_KEY_PREFIX}:${sessionId}`;
+  }
+  getDependencyId(sessionId) {
+    return `${SESSION_CACHE_KEY_PREFIX}:${sessionId}`;
+  }
+}
+function getMcpSessionId(request) {
+  return request?.headers.get(MCP_SESSION_ID_HEADER) ?? void 0;
+}
+function getOrCreateMcpSessionId(request) {
+  return getMcpSessionId(request) ?? crypto.randomUUID();
+}
+function withMcpSessionId(request, sessionId) {
+  if (getMcpSessionId(request) === sessionId) {
+    return request;
+  }
+  const headers = new Headers(request.headers);
+  headers.set(MCP_SESSION_ID_HEADER, sessionId);
+  return new Request(request, { headers });
+}
+function acceptsUndefined(schema) {
+  return schema.safeParse(void 0).success;
+}
+function toMcpSchema(schema) {
+  return fromJsonSchema(
+    z.toJSONSchema(prepareForJsonSchema(schema), {
+      io: "input"
+    })
+  );
+}
+function toMcpOutputSchema(schema) {
+  return toMcpSchema(z.object({
+    value: normalizeOutputValueSchema(schema)
+  }));
+}
+function normalizeOutputValueSchema(schema) {
+  if (schema instanceof z.ZodVoid || schema instanceof z.ZodUndefined) {
+    return z.null();
+  }
+  return schema.nullable();
+}
+function prepareForJsonSchema(schema) {
+  const def = getZodDef(schema);
+  switch (def.type) {
+    case "default":
+      return applySafeDefault(schema, prepareForJsonSchema(def.innerType));
+    case "object":
+      return copyMetadata(schema, z.looseObject(prepareShapeForJsonSchema(def.shape)));
+    case "array":
+      return copyMetadata(schema, z.array(prepareForJsonSchema(def.element)));
+    case "optional":
+      return copyMetadata(schema, prepareForJsonSchema(def.innerType).optional());
+    case "nullable":
+      return copyMetadata(schema, prepareForJsonSchema(def.innerType).nullable());
+    case "union":
+      return copyMetadata(schema, prepareUnionForJsonSchema(def.options));
+    default:
+      return schema;
+  }
+}
+function applySafeDefault(schema, preparedInnerType) {
+  const defaultValue = getSafeDefaultValue(schema);
+  if (!defaultValue.success) {
+    return copyMetadata(schema, preparedInnerType.optional());
+  }
+  return copyMetadata(
+    schema,
+    preparedInnerType.default(defaultValue.value)
+  );
+}
+function getSafeDefaultValue(schema) {
+  try {
+    return {
+      success: true,
+      value: getZodDef(schema).defaultValue
+    };
+  } catch {
+    return { success: false };
+  }
+}
+function copyMetadata(source, target) {
+  const metadata = source.meta();
+  return metadata ? target.meta(metadata) : target;
+}
+function getZodDef(schema) {
+  return schema._zod.def;
+}
+function prepareShapeForJsonSchema(shape) {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, value]) => [
+      key,
+      prepareForJsonSchema(value)
+    ])
+  );
+}
+function prepareUnionForJsonSchema(options) {
+  const preparedOptions = options.map(prepareForJsonSchema);
+  if (preparedOptions.length < 2) {
+    return preparedOptions[0] ?? z.unknown();
+  }
+  return z.union(
+    preparedOptions
+  );
+}
+async function callReactionaryTool(tool, input) {
+  const method = Reflect.get(
+    tool.capability,
+    tool.entrypoint.methodName
+  );
+  if (typeof method !== "function") {
+    throw new Error(`Reactionary MCP tool method not found: ${tool.name}`);
+  }
+  const result = await Reflect.apply(method, tool.capability, [input]);
+  if (!isReactionaryResult(result)) {
+    throw new Error(
+      `Reactionary MCP tool method did not return a Result: ${tool.name}`
+    );
+  }
+  return result;
+}
+function isReactionaryResult(value) {
+  return typeof value === "object" && value !== null && "success" in value && typeof value.success === "boolean";
+}
+function resultToCallToolResult(result) {
+  if (!result.success) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result.error)
+        }
+      ]
+    };
+  }
+  return {
+    structuredContent: toMcpStructuredContent(result.value),
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(toMcpStructuredContent(result.value))
+      }
+    ]
+  };
+}
+function toMcpStructuredContent(value) {
+  return {
+    value: value ?? null
+  };
+}
+export {
+  ReactionaryMCPServer
+};

package/lib/shopping-agent-guide.js

@@ -0,0 +1,138 @@
+const REACTIONARY_SHOPPING_AGENT_GUIDE_URI = "reactionary://mcp/guide/shopping-agent";
+const REACTIONARY_SHOPPING_AGENT_GUIDE_PROMPT = "reactionary-shopping-agent-guide";
+const REACTIONARY_SHOPPING_AGENT_GUIDE = `# Reactionary MCP Shopping Agent Guide
+
+This guide explains how an agent should combine Reactionary MCP tools when helping a shopper. It is based on the Reactionary documentation under documentation/docs, especially product data, product search, cart, checkout, and query/mutation conventions.
+
+## Core mental model
+
+Reactionary is a stateless commerce abstraction layer. It exposes vendor-independent capabilities such as product data, product search, price, inventory, cart, checkout, identity, orders, and personalization. The host application owns session state, routing, user confirmation, and business policy.
+
+Each MCP tool maps to a decorated Reactionary capability method. Tool inputs are object payloads:
+
+- Queries read data.
+- Mutations change state.
+- List queries should use pagination options. Reactionary avoids unbounded list requests.
+
+Do not invent identifiers. Product, SKU, variant, cart, checkout, customer, company, and order identifiers must come from prior tool results or explicit user-provided data.
+
+## General safety rules
+
+1. Prefer read-only tools before mutation tools.
+2. Treat cart, checkout, identity, profile, company, employee, and order-changing tools as state-changing.
+3. Ask the user before making a state-changing cart or checkout operation unless the user clearly requested that exact change.
+4. Verify the selected product variant/SKU before adding it to a cart.
+5. Verify price and inventory when those tools are available, especially before cart mutation or checkout handoff.
+6. After a mutation, read back the resulting object or use the returned object as the new source of truth.
+7. If a tool returns an error, do not guess the missing data. Explain what failed and ask for clarification or retry with corrected inputs.
+8. If search results are ambiguous, ask the user to choose before adding to cart.
+
+## Product discovery flow
+
+Use this flow for open-ended shopper requests such as "find coffee mugs" or "show me running shoes":
+
+1. Call productSearch.queryByTerm with the user's search term and pagination options.
+2. Present a small set of relevant products. Include names, visible variant/SKU information, and facets if useful.
+3. If the user selects a product, use product detail tools such as product.getBySlug, product.getBySKU, or product.getById to obtain the exact product and buyable variant.
+4. Remember that Reactionary uses a Product/Variant model. A variant is the buyable SKU. Search results are optimized for product listing pages and may contain only enough variant data for display and selection.
+5. Do not add a product to cart from a search result unless the result clearly identifies the intended buyable variant.
+
+## Product detail flow
+
+Use product detail tools when the user names a specific product, slug, SKU, or when a prior search result needs exact data:
+
+1. Use product.getBySlug for PDP-style links or SEO slugs.
+2. Use product.getBySKU when the cart or user gives a SKU/variant.
+3. Use product.getById only when the identifier came from Reactionary or the user explicitly provides it.
+4. When a product has multiple variants, ask the user to choose the intended variant unless one is already selected.
+5. For cart and checkout items, prefer SKU/variant identifiers from the item itself and hydrate display data with product.getBySKU if needed.
+
+## Price and inventory flow
+
+Product search results do not necessarily include authoritative price and inventory. When price or inventory tools are available:
+
+1. Use price.getCustomerPrice when the current shopper context may affect pricing.
+2. Use price.getListPrice when a public/list price is enough.
+3. Use inventory tools before promising availability.
+4. If price or stock cannot be verified, state that uncertainty clearly before proceeding.
+5. Re-check before checkout or payment handoff if the cart may be stale.
+
+## Cart flow
+
+Reactionary supports multiple concurrent carts. There is no universal "active cart"; the host application or shopper chooses which cart to use.
+
+Recommended cart flow:
+
+1. If a cart identifier is already known, use it.
+2. If not, list carts if the relevant cart capability is available and the user's context supports it.
+3. Do not create an empty placeholder cart just to browse. Create a cart when the shopper actually wants to add something.
+4. Before adding, resolve the product to an exact variant/SKU and quantity.
+5. Optionally verify price and inventory.
+6. Call the cart add/update mutation.
+7. Use the returned cart or read the cart again.
+8. Summarize the resulting cart: item, quantity, estimated price/total when available, and next actions.
+
+For add-to-cart, the expected pattern is:
+
+1. Product search or detail lookup.
+2. Variant/SKU selection.
+3. Cart create or cart selection.
+4. Cart add.
+5. Cart read/summarize.
+
+## Checkout flow
+
+In Reactionary, the cart records product selections and calculates price. Checkout is a separate session created from a cart. Once checkout starts, consider the cart read-only unless project-specific rules say otherwise.
+
+Recommended checkout flow:
+
+1. Ensure the user explicitly wants to start checkout.
+2. Read or use the latest cart.
+3. Verify price and inventory where tools exist.
+4. Initiate checkout from the cart.
+5. Use checkout tools to set shipping address, shipping instruction, payment instruction, and finalize according to available capabilities.
+6. Never claim payment has succeeded unless the relevant checkout/payment tool confirms it.
+
+For the current minimal demo scope, checkout/payment handoff may be intentionally disabled. In that case, stop after cart creation/addition and explain that checkout is not available in this MCP surface.
+
+## Pagination and list handling
+
+Reactionary list queries use paginationOptions with 1-based pages. Prefer small page sizes for agent interactions, for example 5 to 12 items. Do not request unbounded lists.
+
+When refining product search:
+
+1. Keep the prior search state where possible.
+2. Add selected facets/filters.
+3. Reset pageNumber to 1 after changing filters.
+4. Use additional pages only when the user asks for more.
+
+## B2B considerations
+
+Some carts, prices, catalogs, lists, and checkout permissions may depend on company context. Do not move a cart from one company to another. If the user asks to buy for a company, make sure company context and permissions are clear before mutating carts or checkout.
+
+## Error handling
+
+Reactionary tools return structured success/failure results through MCP. If a tool fails:
+
+- Do not silently continue as if the operation succeeded.
+- Do not fabricate missing identifiers or prices.
+- Explain the failing step in shopper-friendly language.
+- Ask for a correction when the problem is ambiguous.
+- Retry only with changed inputs or when the failure is clearly transient.
+
+## Suggested agent behavior
+
+Be concise and transactional. For shopping flows, users usually need:
+
+- A short result list.
+- A clear recommendation or disambiguation question.
+- Exact confirmation before mutation.
+- A post-mutation summary.
+
+Avoid exposing implementation details unless the user asks.
+`;
+export {
+  REACTIONARY_SHOPPING_AGENT_GUIDE,
+  REACTIONARY_SHOPPING_AGENT_GUIDE_PROMPT,
+  REACTIONARY_SHOPPING_AGENT_GUIDE_URI
+};

package/lib/tool-discovery.js

@@ -0,0 +1,21 @@
+import {
+  BaseCapability,
+  getReactionaryEntrypoints
+} from "@reactionary/core";
+const defaultToolName = (capabilityName, methodName) => `${capabilityName}.${methodName}`;
+function discoverReactionaryMCPTools(client, options = {}) {
+  const toolName = options.toolName ?? defaultToolName;
+  return Object.values(client).flatMap((value) => {
+    if (!(value instanceof BaseCapability)) {
+      return [];
+    }
+    return getReactionaryEntrypoints(value).map((entrypoint) => ({
+      name: toolName(entrypoint.capabilityName, entrypoint.methodName),
+      capability: value,
+      entrypoint
+    }));
+  });
+}
+export {
+  discoverReactionaryMCPTools
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@reactionary/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
+  "bin": {
+    "reactionary-mcp": "./cli.js"
+  },
+  "scripts": {
+    "start": "node --loader @swc-node/register/esm src/cli.ts",
+    "inspect": "node --loader @swc-node/register/esm src/inspect.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Solteq/reactionary.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "2.1.0",
+    "@modelcontextprotocol/server": "2.2.0",
+    "@reactionary/algolia": "0.0.1",
+    "@reactionary/commercetools": "0.0.1",
+    "@reactionary/core": "0.0.1",
+    "@reactionary/fake": "0.0.1",
+    "@reactionary/magento": "0.0.1",
+    "@reactionary/medusa": "0.0.1",
+    "@reactionary/meilisearch": "0.0.1",
+    "@reactionary/unomi": "0.0.1",
+    "dotenv": "^17.2.2",
+    "zod": "4.1.9"
+  },
+  "devDependencies": {
+    "@swc-node/register": "1.11.1",
+    "vitest": "^4.0.9"
+  },
+  "sideEffects": false
+}

package/src/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+interface CliOptions {
+    host: string;
+    port: number;
+    path: string;
+}
+export declare function parseOptions(args: string[], env: NodeJS.ProcessEnv): CliOptions;
+export {};

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lib/env-client-builder.js';
+export * from './lib/reactionary-mcp-server.js';
+export * from './lib/shopping-agent-guide.js';
+export * from './lib/tool-discovery.js';

package/src/inspect.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/lib/env-client-builder.d.ts

@@ -0,0 +1,16 @@
+import { type Cache, type RequestContext } from '@reactionary/core';
+import type { ReactionaryMCPClient } from './tool-discovery.js';
+export type ReactionaryMCPProviderSystem = 'ALGOLIA' | 'COMMERCETOOLS' | 'FAKE' | 'MAGENTO' | 'MEDUSA' | 'MEILISEARCH' | 'UNOMI';
+export interface CreateReactionaryClientFromEnvOptions {
+    env?: NodeJS.ProcessEnv;
+    contextOverrides?: Partial<RequestContext>;
+    cache?: Cache;
+}
+export interface ReactionaryMCPClientFromEnv {
+    client: ReactionaryMCPClient;
+    enabledSystems: ReactionaryMCPProviderSystem[];
+}
+export declare function createReactionaryClientFromEnv(options?: CreateReactionaryClientFromEnvOptions): ReactionaryMCPClientFromEnv;
+export declare function getEnabledReactionaryMCPProviderSystems(env?: NodeJS.ProcessEnv): ReactionaryMCPProviderSystem[];
+export declare function getNoEnabledProviderSystemsMessage(): string;
+export declare function parseCommaSeparatedEnvList(value: string | undefined): string[];

package/src/lib/load-project-root-env.d.ts

@@ -0,0 +1,2 @@
+export declare function loadProjectRootEnv(from?: string | URL, env?: NodeJS.ProcessEnv): void;
+export declare function resolveProjectRootEnvPath(from?: string | URL): string | undefined;

package/src/lib/reactionary-mcp-server.d.ts

@@ -0,0 +1,28 @@
+import { type CreateMcpHandlerOptions, type McpHttpHandler } from '@modelcontextprotocol/server';
+import { type NodeMcpRequestHandler } from '@modelcontextprotocol/node';
+import { type Cache, type RequestContext } from '@reactionary/core';
+import { type DiscoverReactionaryMCPToolsOptions, type ReactionaryMCPClient, type ReactionaryMCPTool } from './tool-discovery.js';
+export type ReactionaryMCPClientFactory = (requestContext: RequestContext) => ReactionaryMCPClient;
+export interface ReactionaryMCPServerOptions extends DiscoverReactionaryMCPToolsOptions {
+    name?: string;
+    version?: string;
+    sessionCache?: Cache;
+    sessionTtlSeconds?: number;
+    handler?: Pick<CreateMcpHandlerOptions, 'bus' | 'keepAliveMs' | 'legacy' | 'maxRequestBodySize' | 'maxSubscriptions' | 'onerror' | 'responseMode'>;
+}
+export declare class ReactionaryMCPServer {
+    private readonly clientFactory;
+    private readonly options;
+    private readonly handler;
+    private readonly sessionStore;
+    constructor(clientFactory: ReactionaryMCPClientFactory, options?: ReactionaryMCPServerOptions);
+    fetch(request: Request, options?: Parameters<McpHttpHandler['fetch']>[1]): Promise<Response>;
+    getHandler(): McpHttpHandler;
+    toNodeHandler(): NodeMcpRequestHandler;
+    close(): Promise<void>;
+    discoverTools(): ReactionaryMCPTool[];
+    private createServer;
+    private discoverToolsForClient;
+    private registerShoppingAgentGuide;
+    private registerTool;
+}

package/src/lib/shopping-agent-guide.d.ts

@@ -0,0 +1,3 @@
+export declare const REACTIONARY_SHOPPING_AGENT_GUIDE_URI = "reactionary://mcp/guide/shopping-agent";
+export declare const REACTIONARY_SHOPPING_AGENT_GUIDE_PROMPT = "reactionary-shopping-agent-guide";
+export declare const REACTIONARY_SHOPPING_AGENT_GUIDE = "# Reactionary MCP Shopping Agent Guide\n\nThis guide explains how an agent should combine Reactionary MCP tools when helping a shopper. It is based on the Reactionary documentation under documentation/docs, especially product data, product search, cart, checkout, and query/mutation conventions.\n\n## Core mental model\n\nReactionary is a stateless commerce abstraction layer. It exposes vendor-independent capabilities such as product data, product search, price, inventory, cart, checkout, identity, orders, and personalization. The host application owns session state, routing, user confirmation, and business policy.\n\nEach MCP tool maps to a decorated Reactionary capability method. Tool inputs are object payloads:\n\n- Queries read data.\n- Mutations change state.\n- List queries should use pagination options. Reactionary avoids unbounded list requests.\n\nDo not invent identifiers. Product, SKU, variant, cart, checkout, customer, company, and order identifiers must come from prior tool results or explicit user-provided data.\n\n## General safety rules\n\n1. Prefer read-only tools before mutation tools.\n2. Treat cart, checkout, identity, profile, company, employee, and order-changing tools as state-changing.\n3. Ask the user before making a state-changing cart or checkout operation unless the user clearly requested that exact change.\n4. Verify the selected product variant/SKU before adding it to a cart.\n5. Verify price and inventory when those tools are available, especially before cart mutation or checkout handoff.\n6. After a mutation, read back the resulting object or use the returned object as the new source of truth.\n7. If a tool returns an error, do not guess the missing data. Explain what failed and ask for clarification or retry with corrected inputs.\n8. If search results are ambiguous, ask the user to choose before adding to cart.\n\n## Product discovery flow\n\nUse this flow for open-ended shopper requests such as \"find coffee mugs\" or \"show me running shoes\":\n\n1. Call productSearch.queryByTerm with the user's search term and pagination options.\n2. Present a small set of relevant products. Include names, visible variant/SKU information, and facets if useful.\n3. If the user selects a product, use product detail tools such as product.getBySlug, product.getBySKU, or product.getById to obtain the exact product and buyable variant.\n4. Remember that Reactionary uses a Product/Variant model. A variant is the buyable SKU. Search results are optimized for product listing pages and may contain only enough variant data for display and selection.\n5. Do not add a product to cart from a search result unless the result clearly identifies the intended buyable variant.\n\n## Product detail flow\n\nUse product detail tools when the user names a specific product, slug, SKU, or when a prior search result needs exact data:\n\n1. Use product.getBySlug for PDP-style links or SEO slugs.\n2. Use product.getBySKU when the cart or user gives a SKU/variant.\n3. Use product.getById only when the identifier came from Reactionary or the user explicitly provides it.\n4. When a product has multiple variants, ask the user to choose the intended variant unless one is already selected.\n5. For cart and checkout items, prefer SKU/variant identifiers from the item itself and hydrate display data with product.getBySKU if needed.\n\n## Price and inventory flow\n\nProduct search results do not necessarily include authoritative price and inventory. When price or inventory tools are available:\n\n1. Use price.getCustomerPrice when the current shopper context may affect pricing.\n2. Use price.getListPrice when a public/list price is enough.\n3. Use inventory tools before promising availability.\n4. If price or stock cannot be verified, state that uncertainty clearly before proceeding.\n5. Re-check before checkout or payment handoff if the cart may be stale.\n\n## Cart flow\n\nReactionary supports multiple concurrent carts. There is no universal \"active cart\"; the host application or shopper chooses which cart to use.\n\nRecommended cart flow:\n\n1. If a cart identifier is already known, use it.\n2. If not, list carts if the relevant cart capability is available and the user's context supports it.\n3. Do not create an empty placeholder cart just to browse. Create a cart when the shopper actually wants to add something.\n4. Before adding, resolve the product to an exact variant/SKU and quantity.\n5. Optionally verify price and inventory.\n6. Call the cart add/update mutation.\n7. Use the returned cart or read the cart again.\n8. Summarize the resulting cart: item, quantity, estimated price/total when available, and next actions.\n\nFor add-to-cart, the expected pattern is:\n\n1. Product search or detail lookup.\n2. Variant/SKU selection.\n3. Cart create or cart selection.\n4. Cart add.\n5. Cart read/summarize.\n\n## Checkout flow\n\nIn Reactionary, the cart records product selections and calculates price. Checkout is a separate session created from a cart. Once checkout starts, consider the cart read-only unless project-specific rules say otherwise.\n\nRecommended checkout flow:\n\n1. Ensure the user explicitly wants to start checkout.\n2. Read or use the latest cart.\n3. Verify price and inventory where tools exist.\n4. Initiate checkout from the cart.\n5. Use checkout tools to set shipping address, shipping instruction, payment instruction, and finalize according to available capabilities.\n6. Never claim payment has succeeded unless the relevant checkout/payment tool confirms it.\n\nFor the current minimal demo scope, checkout/payment handoff may be intentionally disabled. In that case, stop after cart creation/addition and explain that checkout is not available in this MCP surface.\n\n## Pagination and list handling\n\nReactionary list queries use paginationOptions with 1-based pages. Prefer small page sizes for agent interactions, for example 5 to 12 items. Do not request unbounded lists.\n\nWhen refining product search:\n\n1. Keep the prior search state where possible.\n2. Add selected facets/filters.\n3. Reset pageNumber to 1 after changing filters.\n4. Use additional pages only when the user asks for more.\n\n## B2B considerations\n\nSome carts, prices, catalogs, lists, and checkout permissions may depend on company context. Do not move a cart from one company to another. If the user asks to buy for a company, make sure company context and permissions are clear before mutating carts or checkout.\n\n## Error handling\n\nReactionary tools return structured success/failure results through MCP. If a tool fails:\n\n- Do not silently continue as if the operation succeeded.\n- Do not fabricate missing identifiers or prices.\n- Explain the failing step in shopper-friendly language.\n- Ask for a correction when the problem is ambiguous.\n- Retry only with changed inputs or when the failure is clearly transient.\n\n## Suggested agent behavior\n\nBe concise and transactional. For shopping flows, users usually need:\n\n- A short result list.\n- A clear recommendation or disambiguation question.\n- Exact confirmation before mutation.\n- A post-mutation summary.\n\nAvoid exposing implementation details unless the user asks.\n";

package/src/lib/tool-discovery.d.ts

@@ -0,0 +1,11 @@
+import { BaseCapability, type ReactionaryEntrypointMetadata } from '@reactionary/core';
+export interface ReactionaryMCPTool {
+    name: string;
+    capability: BaseCapability;
+    entrypoint: ReactionaryEntrypointMetadata;
+}
+export type ReactionaryMCPClient = object;
+export interface DiscoverReactionaryMCPToolsOptions {
+    toolName?: (capabilityName: string, methodName: string) => string;
+}
+export declare function discoverReactionaryMCPTools(client: ReactionaryMCPClient, options?: DiscoverReactionaryMCPToolsOptions): ReactionaryMCPTool[];