@solidcommerce/mcp-server 2.0.0-alpha.0

package/dist/server/buildServer.js

@@ -0,0 +1,104 @@
+// =============================================================================
+// src/server/buildServer.ts
+// Wave: W6 — Stream C
+//
+// Constructs an `@modelcontextprotocol/sdk` `Server` configured with the
+// dispatcher + provided tool list. The server returned here is *unconnected* —
+// callers (transports/stdio.ts, transports/streamableHttp.ts) call
+// `server.connect(t)` to bind a transport. For Streamable HTTP this is called
+// once per session via the index.ts `makeServer` factory.
+//
+// Why this is split from index.ts: tests need to stand up a server with a
+// fake `client` and assert dispatcher behavior in isolation, without booting
+// stdio/SSE.
+// =============================================================================
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { registerTools } from "./dispatcher.js";
+/**
+ * Project the full session auth context down to the subset tools may read.
+ * Deliberately DROPS the raw bearer token — tool handlers never need it (the
+ * SDK client already carries it) and must not be able to exfiltrate it.
+ */
+function toToolAuthInfo(auth) {
+    if (!auth)
+        return { mode: "apiKey", scopes: [] };
+    return {
+        mode: auth.mode,
+        ...(auth.companyId !== undefined ? { companyId: auth.companyId } : {}),
+        ...(auth.installId !== undefined ? { installId: auth.installId } : {}),
+        scopes: auth.scopes,
+        ...(auth.introspectionDegraded ? { introspectionDegraded: true } : {}),
+    };
+}
+export const SERVER_NAME = "@solidcommerce/mcp-server";
+/**
+ * Read the package.json sibling to dist/index.js (or src/index.js under tsx).
+ * We resolve relative to this module rather than `process.cwd()` so the
+ * version stays correct when the binary is launched from any directory.
+ *
+ * Defensive fallback: if package.json is unreadable (extremely unusual —
+ * would mean the install is broken), we ship a clearly-labelled
+ * `0.0.0-unknown` so the server still boots.
+ */
+function readPackageVersion() {
+    try {
+        // src/server/buildServer.ts → ../../package.json
+        // dist/server/buildServer.js → ../../package.json (same relative depth)
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(here, "..", "..", "package.json");
+        const raw = readFileSync(pkgPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.length > 0) {
+            return parsed.version;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0-unknown";
+}
+/**
+ * Wire a fully-configured MCP `Server`. Caller is responsible for `connect()`.
+ *
+ * The dispatcher's `ctxFactory` is closed over `client` + `setCurrentToolName`
+ * so each tool invocation:
+ *
+ *   1. Sets the audit ref to the tool name.
+ *   2. Receives a ToolContext { client, toolName }.
+ *   3. The SDK fires onRequest hooks → audit headers go on the wire.
+ *   4. After tool.handle resolves (or throws), the ref is cleared.
+ */
+export function buildMcpServer(opts) {
+    const version = opts.version ?? readPackageVersion();
+    const server = new Server({ name: SERVER_NAME, version }, {
+        // We advertise tools support; resources/prompts/sampling come in later
+        // waves (W8+). Empty `tools: {}` is the canonical "we have tools" flag
+        // per the MCP spec; the actual list is served by tools/list.
+        capabilities: { tools: {} },
+    });
+    const auth = toToolAuthInfo(opts.auth);
+    const ctxFactory = (toolName) => {
+        // Set the ref BEFORE returning the context — the very next thing the
+        // dispatcher does is call `tool.handle(args, ctx)`, and that handler
+        // is what triggers SDK requests + onRequest hooks.
+        opts.setCurrentToolName(toolName);
+        return { client: opts.client, toolName, auth };
+    };
+    registerTools(server, opts.tools, ctxFactory);
+    // Best-effort: clear the ref whenever the transport closes. With per-session
+    // Server instances (E-A1) each Streamable HTTP session has its own ref, but
+    // stdio reuses one Server for the process lifetime, so clearing on close
+    // still prevents a stale tool name leaking across a reconnect.
+    const originalOnClose = server.onclose;
+    server.onclose = () => {
+        opts.setCurrentToolName(null);
+        if (typeof originalOnClose === "function") {
+            originalOnClose();
+        }
+    };
+    return server;
+}
+//# sourceMappingURL=buildServer.js.map

package/dist/server/buildServer.js.map

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

package/dist/server/dispatcher.d.ts

@@ -0,0 +1,14 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ToolContext, ToolModule } from "../tools/contract.js";
+export interface ContextFactory {
+    (toolName: string): ToolContext;
+}
+/**
+ * Register `tools/list` and `tools/call` handlers on the MCP server.
+ *
+ * The dispatcher does NOT attach audit hooks; that's the job of the caller
+ * (index.ts) wiring `attachAuditHook(client)` and threading the resulting
+ * `setCurrentToolName` into `ctxFactory`.
+ */
+export declare function registerTools(server: Server, tools: ReadonlyArray<ToolModule>, ctxFactory: ContextFactory): void;
+//# sourceMappingURL=dispatcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/server/dispatcher.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAOxE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EAGX,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,cAAc;IAC7B,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC;CACjC;AA0FD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,UAAU,EAAE,cAAc,GACzB,IAAI,CAyFN"}

package/dist/server/dispatcher.js

@@ -0,0 +1,190 @@
+// =============================================================================
+// src/server/dispatcher.ts
+// Wave: W6 — Stream C
+//
+// Wires `ToolModule` instances onto an MCP `Server` via `setRequestHandler`
+// for `tools/list` and `tools/call`.
+//
+// Why direct setRequestHandler over the higher-level MCP `tool()` ergonomics:
+//
+//  1. SDK 1.0.4's `Server` class is the documented low-level API (the
+//     newer `McpServer` helper landed in 1.4+ and we're pinned to 1.0.4 to
+//     match Claude Desktop's bundled SDK).
+//  2. We need full control over the response envelope so we can surface
+//     `isError: true` + structured `required_scope` for the LLM scope-denied
+//     path. The high-level helper auto-serializes thrown errors into a flat
+//     text block which would lose structure.
+//
+// Flow per tools/call:
+//   1. Resolve the tool by name. Unknown name → `{ isError: true }` with a
+//      hint (do NOT throw — the SDK turns thrown errors into JSON-RPC errors,
+//      and we want the LLM to *see* the failure as a regular tool result).
+//   2. Parse args via the tool's Zod schema. Validation failure → structured
+//      `invalid_request` ToolResult.
+//   3. Call ctxFactory(toolName) → ToolContext, then tool.handle(args, ctx).
+//   4. Serialize ToolResult.content into MCP TextContent blocks. JSON entries
+//      are pretty-printed with 2-space indent so logs (and human eyes during
+//      debugging) stay readable.
+//   5. Propagate isError through the wire response.
+// =============================================================================
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+/**
+ * Convert a `ToolResultContent[]` into MCP wire `TextContent` blocks. JSON
+ * entries are stringified with 2-space indent. Text entries are passed through.
+ *
+ * The MCP wire content shape for tools is `{ type: "text", text: string }`
+ * (plus newer `image`/`resource` variants we don't use here).
+ */
+function serializeContent(content) {
+    return content.map((c) => {
+        if (c.type === "text") {
+            return { type: "text", text: c.text };
+        }
+        return { type: "text", text: JSON.stringify(c.json, null, 2) };
+    });
+}
+/**
+ * Build an MCP-shape error result without invoking the tool. Used for
+ * unknown-tool and arg-validation paths.
+ */
+function buildClientErrorResult(errorType, message, extra = {}) {
+    return {
+        content: [
+            {
+                type: "json",
+                json: { error: { type: errorType, message, ...extra } },
+            },
+        ],
+        isError: true,
+        structuredError: { type: errorType, message },
+    };
+}
+/**
+ * Convert a Zod schema to JSON Schema for the MCP `tools/list` response.
+ *
+ * MCP requires `inputSchema` to be a JSON Schema object with `type: "object"`
+ * at the root. `zod-to-json-schema` emits `$schema` + `definitions` keys we
+ * don't want on the wire — strip them. If a tool's schema isn't an object
+ * (e.g., `z.array(...)`), we wrap it under a single `value` property; this
+ * shouldn't happen in practice (every ToolModule takes a named-arg object),
+ * but we'd rather degrade gracefully than crash tools/list.
+ */
+function zodToMcpInputSchema(schema) {
+    // We intentionally accept ZodTypeAny but treat it loosely so we don't pull in
+    // the full zod-to-json-schema generic surface; the upstream types are
+    // permissive enough that ts-strict compilation here would require @ts-expect.
+    const raw = zodToJsonSchema(schema, {
+        target: "jsonSchema7",
+        $refStrategy: "none",
+    });
+    // Strip MCP-irrelevant top-level keys.
+    delete raw["$schema"];
+    delete raw["definitions"];
+    if (raw["type"] === "object") {
+        const out = {
+            type: "object",
+        };
+        if (raw["properties"] && typeof raw["properties"] === "object") {
+            out.properties = raw["properties"];
+        }
+        if (Array.isArray(raw["required"])) {
+            out.required = raw["required"];
+        }
+        return out;
+    }
+    // Fallback: wrap non-object schemas. See doc comment above.
+    return {
+        type: "object",
+        properties: { value: raw },
+        required: ["value"],
+    };
+}
+/**
+ * Register `tools/list` and `tools/call` handlers on the MCP server.
+ *
+ * The dispatcher does NOT attach audit hooks; that's the job of the caller
+ * (index.ts) wiring `attachAuditHook(client)` and threading the resulting
+ * `setCurrentToolName` into `ctxFactory`.
+ */
+export function registerTools(server, tools, ctxFactory) {
+    // Index for O(1) lookup; rejecting duplicates upfront is friendlier than
+    // letting the second registration silently shadow the first.
+    const byName = new Map();
+    for (const tool of tools) {
+        if (byName.has(tool.name)) {
+            throw new Error(`duplicate tool name: ${tool.name}`);
+        }
+        byName.set(tool.name, tool);
+    }
+    // tools/list — emit each tool's name, description, JSON-schema'd args, and
+    // the Claude UI annotations object. The `required_scope` field is documented
+    // in the description so the LLM can see it inline (the MCP spec doesn't
+    // define a top-level scope field).
+    //
+    // `annotations.readOnlyHint` / `.destructiveHint` is the March 2025 MCP-spec
+    // addition Claude UI requires for Connectors Directory listing. We surface
+    // exactly one per tool (mutually exclusive — enforced by
+    // test/tools/annotations.test.ts). Hosts that ignore the field degrade
+    // safely; hosts that require it (Claude UI) get a green lint pass.
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const list = tools.map((tool) => {
+            const annotations = {};
+            if (tool.readOnlyHint === true)
+                annotations.readOnlyHint = true;
+            if (tool.destructiveHint === true)
+                annotations.destructiveHint = true;
+            return {
+                name: tool.name,
+                description: `${tool.description}\n\nRequired scope: \`${tool.required_scope}\``,
+                inputSchema: zodToMcpInputSchema(tool.inputSchema),
+                annotations,
+            };
+        });
+        return { tools: list };
+    });
+    // tools/call — dispatch to the resolved ToolModule.
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: rawArgs } = req.params;
+        const tool = byName.get(name);
+        if (!tool) {
+            const err = buildClientErrorResult("not_found", `Unknown tool: ${name}`, { tool_name: name });
+            return {
+                content: serializeContent(err.content),
+                isError: true,
+            };
+        }
+        // Validate args. Zod's `safeParse` lets us return a structured error
+        // instead of letting a thrown ZodError bubble into the SDK's generic
+        // error path.
+        const parsed = tool.inputSchema.safeParse(rawArgs ?? {});
+        if (!parsed.success) {
+            const err = buildClientErrorResult("invalid_request", `Invalid arguments for tool ${name}`, { issues: parsed.error.issues });
+            return {
+                content: serializeContent(err.content),
+                isError: true,
+            };
+        }
+        let result;
+        try {
+            const ctx = ctxFactory(name);
+            result = await tool.handle(parsed.data, ctx);
+        }
+        catch (err) {
+            // Defense in depth: every well-behaved ToolModule.handle returns a
+            // ToolResult, even for errors (see contract.ts → mapSdkErrorToToolResult).
+            // But if a tool *does* throw, we still want a structured response.
+            const message = err instanceof Error ? err.message : String(err);
+            const fallback = buildClientErrorResult("server_error", message);
+            return {
+                content: serializeContent(fallback.content),
+                isError: true,
+            };
+        }
+        return {
+            content: serializeContent(result.content),
+            ...(result.isError ? { isError: true } : {}),
+        };
+    });
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/server/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/server/dispatcher.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,2BAA2B;AAC3B,sBAAsB;AACtB,EAAE;AACF,4EAA4E;AAC5E,qCAAqC;AACrC,EAAE;AACF,8EAA8E;AAC9E,EAAE;AACF,sEAAsE;AACtE,2EAA2E;AAC3E,2CAA2C;AAC3C,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,6CAA6C;AAC7C,EAAE;AACF,uBAAuB;AACvB,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,qCAAqC;AACrC,6EAA6E;AAC7E,8EAA8E;AAC9E,6EAA6E;AAC7E,iCAAiC;AACjC,oDAAoD;AACpD,gFAAgF;AAGhF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAarD;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,OAAyC;IAIjE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACtB,OAAO,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACjD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAS,sBAAsB,CAC7B,SAAiB,EACjB,OAAe,EACf,QAAiC,EAAE;IAEnC,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE;aACxD;SACF;QACD,OAAO,EAAE,IAAI;QACb,eAAe,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,mBAAmB,CAAC,MAAe;IAK1C,8EAA8E;IAC9E,sEAAsE;IACtE,8EAA8E;IAC9E,MAAM,GAAG,GAAG,eAAe,CAAC,MAA+C,EAAE;QAC3E,MAAM,EAAE,aAAa;QACrB,YAAY,EAAE,MAAM;KACrB,CAA4B,CAAC;IAE9B,uCAAuC;IACvC,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC;IACtB,OAAO,GAAG,CAAC,aAAa,CAAC,CAAC;IAE1B,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAkF;YACzF,IAAI,EAAE,QAAQ;SACf,CAAC;QACF,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/D,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,YAAY,CAA4B,CAAC;QAChE,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAa,CAAC;QAC7C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,4DAA4D;IAC5D,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE;QAC1B,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,KAAgC,EAChC,UAA0B;IAE1B,yEAAyE;IACzE,6DAA6D;IAC7D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,2EAA2E;IAC3E,6EAA6E;IAC7E,wEAAwE;IACxE,mCAAmC;IACnC,EAAE;IACF,6EAA6E;IAC7E,2EAA2E;IAC3E,yDAAyD;IACzD,uEAAuE;IACvE,mEAAmE;IACnE,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YAC9B,MAAM,WAAW,GAA0D,EAAE,CAAC;YAC9E,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;gBAAE,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC;YAChE,IAAI,IAAI,CAAC,eAAe,KAAK,IAAI;gBAAE,WAAW,CAAC,eAAe,GAAG,IAAI,CAAC;YACtE,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,GAAG,IAAI,CAAC,WAAW,yBAAyB,IAAI,CAAC,cAAc,IAAI;gBAChF,WAAW,EAAE,mBAAmB,CAAC,IAAI,CAAC,WAAW,CAAC;gBAClD,WAAW;aACZ,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,oDAAoD;IACpD,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAC5D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,GAAG,GAAG,sBAAsB,CAChC,WAAW,EACX,iBAAiB,IAAI,EAAE,EACvB,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB,CAAC;YACF,OAAO;gBACL,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC;gBACtC,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,qEAAqE;QACrE,qEAAqE;QACrE,cAAc;QACd,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,GAAG,GAAG,sBAAsB,CAChC,iBAAiB,EACjB,8BAA8B,IAAI,EAAE,EACpC,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAChC,CAAC;YACF,OAAO;gBACL,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC;gBACtC,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,IAAI,MAAkB,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,mEAAmE;YACnE,2EAA2E;YAC3E,mEAAmE;YACnE,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,sBAAsB,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;YACjE,OAAO;gBACL,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAC3C,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC;YACzC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,9 @@
+import type { SessionAuthContext } from "./auth/oauth.js";
+import type { McpHostName } from "./telemetry/hostName.js";
+export interface SessionContext {
+    /** Resolved per-user OAuth / apiKey identity (E-A3). */
+    readonly auth: SessionAuthContext;
+    /** Canonical calling surface for per-surface telemetry (E-A4). */
+    readonly hostName: McpHostName;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC"}

package/dist/session.js

@@ -0,0 +1,11 @@
+// =============================================================================
+// src/session.ts
+// Phase 0 / E-A3 + E-A4 — the per-session identity bundle.
+//
+// One SessionContext is resolved at `initialize` and bound to the session's
+// dedicated MCP Server: the auth identity (E-A3) and the calling host surface
+// (E-A4). Future per-session concerns (E-A5 rate-limit budget, etc.) attach
+// here rather than widening every factory signature.
+// =============================================================================
+export {};
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,iBAAiB;AACjB,2DAA2D;AAC3D,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,qDAAqD;AACrD,gFAAgF"}

package/dist/telemetry/hostName.d.ts

@@ -0,0 +1,26 @@
+/** Canonical surface ids (mirror docs/use_cases.md §7 telemetry NFR). */
+export declare const MCP_HOST_NAMES: readonly ["claude_code", "claude_ui", "codex_cli", "chatgpt_ui", "gemini_ui", "gemini_cli", "m365_copilot", "grok_cli"];
+export type McpHostName = (typeof MCP_HOST_NAMES)[number] | "unknown";
+export declare const MCP_HOST_UNKNOWN = "unknown";
+/** Force a fixed host id (single-host deployments / tests). Wins over detection. */
+export declare const ENV_HOST_NAME_OVERRIDE = "SC_MCP_HOST_NAME";
+export interface HostNameSignals {
+    /** MCP `initialize` params.clientInfo.name. */
+    readonly clientInfoName?: string | undefined;
+    /** HTTP `User-Agent` header. */
+    readonly userAgent?: string | undefined;
+    /** Env override (SC_MCP_HOST_NAME). Wins when set. */
+    readonly override?: string | undefined;
+}
+/**
+ * Map host signals to a canonical surface id. Override wins; otherwise the
+ * first matching pattern across (clientInfoName + userAgent); else `unknown`.
+ * Never throws.
+ */
+export declare function resolveHostName(signals: HostNameSignals): McpHostName;
+/**
+ * Defensively pull `params.clientInfo.name` out of a parsed MCP `initialize`
+ * request body. Returns undefined for any shape mismatch — never throws.
+ */
+export declare function extractClientInfoName(body: unknown): string | undefined;
+//# sourceMappingURL=hostName.d.ts.map

package/dist/telemetry/hostName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostName.d.ts","sourceRoot":"","sources":["../../src/telemetry/hostName.ts"],"names":[],"mappings":"AAeA,yEAAyE;AACzE,eAAO,MAAM,cAAc,yHASjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;AAEtE,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAezD,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,gCAAgC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CAkBrE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQvE"}

package/dist/telemetry/hostName.js

@@ -0,0 +1,80 @@
+// =============================================================================
+// src/telemetry/hostName.ts
+// Phase 0 / Item E-A4 — per-surface telemetry: resolve the calling AI host.
+//
+// Every one of the 8 distribution surfaces hits the SAME hosted MCP URL, so we
+// attribute traffic by the MCP `clientInfo.name` sent in the `initialize`
+// request (the canonical, host-controlled identity), with the HTTP User-Agent
+// as a secondary signal and an env override as an escape hatch.
+//
+// This is BEST-EFFORT telemetry, NOT a security control: a client can spoof its
+// name. Reliable attribution comes from pairing this with the server-minted
+// `install_id` (E-A3). The audit hook stamps both; the KQL dashboard pivots on
+// `mcp_host_name`.
+// =============================================================================
+/** Canonical surface ids (mirror docs/use_cases.md §7 telemetry NFR). */
+export const MCP_HOST_NAMES = [
+    "claude_code",
+    "claude_ui",
+    "codex_cli",
+    "chatgpt_ui",
+    "gemini_ui",
+    "gemini_cli",
+    "m365_copilot",
+    "grok_cli",
+];
+export const MCP_HOST_UNKNOWN = "unknown";
+/** Force a fixed host id (single-host deployments / tests). Wins over detection. */
+export const ENV_HOST_NAME_OVERRIDE = "SC_MCP_HOST_NAME";
+// Order matters — most specific first. `claude-code` must precede the `claude`
+// catch-all; `gemini-cli` must precede `gemini`.
+const HOST_PATTERNS = [
+    [/claude[-_ ]?code/i, "claude_code"],
+    [/codex/i, "codex_cli"],
+    [/chatgpt|openai/i, "chatgpt_ui"],
+    [/gemini[-_ ]?cli/i, "gemini_cli"],
+    [/gemini|vertex/i, "gemini_ui"],
+    [/copilot|m365|microsoft[-_ ]?365|teams/i, "m365_copilot"],
+    [/grok|xai/i, "grok_cli"],
+    [/claude|anthropic/i, "claude_ui"], // catch-all AFTER claude-code
+];
+/**
+ * Map host signals to a canonical surface id. Override wins; otherwise the
+ * first matching pattern across (clientInfoName + userAgent); else `unknown`.
+ * Never throws.
+ */
+export function resolveHostName(signals) {
+    const override = signals.override?.trim();
+    if (override && override.length > 0) {
+        // Accept a known canonical id verbatim; otherwise still honor the operator's
+        // explicit string by returning it (cast) — telemetry, not a closed enum gate.
+        return override;
+    }
+    const haystack = [signals.clientInfoName, signals.userAgent]
+        .filter((s) => typeof s === "string" && s.length > 0)
+        .join(" ");
+    if (haystack.length === 0)
+        return MCP_HOST_UNKNOWN;
+    for (const [pattern, name] of HOST_PATTERNS) {
+        if (pattern.test(haystack))
+            return name;
+    }
+    return MCP_HOST_UNKNOWN;
+}
+/**
+ * Defensively pull `params.clientInfo.name` out of a parsed MCP `initialize`
+ * request body. Returns undefined for any shape mismatch — never throws.
+ */
+export function extractClientInfoName(body) {
+    if (body === null || typeof body !== "object")
+        return undefined;
+    const params = body.params;
+    if (params === null || typeof params !== "object")
+        return undefined;
+    const clientInfo = params.clientInfo;
+    if (clientInfo === null || typeof clientInfo !== "object")
+        return undefined;
+    const name = clientInfo.name;
+    return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+//# sourceMappingURL=hostName.js.map

package/dist/telemetry/hostName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostName.js","sourceRoot":"","sources":["../../src/telemetry/hostName.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4BAA4B;AAC5B,4EAA4E;AAC5E,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,mBAAmB;AACnB,gFAAgF;AAEhF,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa;IACb,WAAW;IACX,WAAW;IACX,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,cAAc;IACd,UAAU;CACF,CAAC;AAIX,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAE1C,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAEzD,+EAA+E;AAC/E,iDAAiD;AACjD,MAAM,aAAa,GAAkD;IACnE,CAAC,mBAAmB,EAAE,aAAa,CAAC;IACpC,CAAC,QAAQ,EAAE,WAAW,CAAC;IACvB,CAAC,iBAAiB,EAAE,YAAY,CAAC;IACjC,CAAC,kBAAkB,EAAE,YAAY,CAAC;IAClC,CAAC,gBAAgB,EAAE,WAAW,CAAC;IAC/B,CAAC,wCAAwC,EAAE,cAAc,CAAC;IAC1D,CAAC,WAAW,EAAE,UAAU,CAAC;IACzB,CAAC,mBAAmB,EAAE,WAAW,CAAC,EAAE,8BAA8B;CACnE,CAAC;AAWF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,6EAA6E;QAC7E,8EAA8E;QAC9E,OAAO,QAAuB,CAAC;IACjC,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,SAAS,CAAC;SACzD,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SACjE,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAEnD,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,aAAa,EAAE,CAAC;QAC5C,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;IAC1C,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChE,MAAM,MAAM,GAAI,IAA6B,CAAC,MAAM,CAAC;IACrD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,UAAU,GAAI,MAAmC,CAAC,UAAU,CAAC;IACnE,IAAI,UAAU,KAAK,IAAI,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC5E,MAAM,IAAI,GAAI,UAAiC,CAAC,IAAI,CAAC;IACrD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC"}

package/dist/tools/contract.d.ts

@@ -0,0 +1,125 @@
+import type { SolidCommerceClient } from "@solidcommerce/sdk";
+import type { ZodTypeAny } from "zod";
+/** Foundation = OpenAPI-derived; Task = hand-authored composition. */
+export type ToolKind = "foundation" | "task";
+/**
+ * Resolved auth identity for the current MCP session (Phase 0 / E-A3).
+ * Populated by the per-session server factory from either a per-user OAuth
+ * bearer token (remote hosts) or the env API key (stdio / Scotty / internal).
+ */
+export interface ToolAuthInfo {
+    /** `oauth` = per-user bearer; `apiKey` = service-to-service env key. */
+    readonly mode: "oauth" | "apiKey";
+    /** Company the token is scoped to, when introspection surfaced it. */
+    readonly companyId?: string;
+    /** Per-(host, company) install id minted at OAuth consent. */
+    readonly installId?: string;
+    /** Granted scopes (empty for apiKey / when not surfaced). */
+    readonly scopes: ReadonlyArray<string>;
+    /**
+     * True when introspection could not verify the token (Auth outage / circuit
+     * open) and we forwarded it unverified — Platform remains the authority.
+     */
+    readonly introspectionDegraded?: boolean;
+}
+/** Provided to every tool handler. The client is already auth-injected. */
+export interface ToolContext {
+    /** Fully configured SDK client with audit hooks pre-installed. */
+    readonly client: SolidCommerceClient;
+    /** The MCP tool name being dispatched (for logging / audit headers). */
+    readonly toolName: string;
+    /**
+     * Resolved session auth identity. Optional so existing unit tests that build
+     * a bare context still compile; the dispatcher always populates it in
+     * production (see server/buildServer.ts).
+     */
+    readonly auth?: ToolAuthInfo;
+}
+/**
+ * MCP wire content. We deliberately accept both text + json — the
+ * MCP TypeScript SDK serializes both into its `TextContent` shape,
+ * with JSON values pretty-printed.
+ */
+export type ToolResultContent = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "json";
+    readonly json: unknown;
+};
+/**
+ * Structured error payload exposed to the LLM when an SDK call fails.
+ * Carrying `required_scope` distinct from the human message lets the LLM
+ * surface "you need scope X" cleanly without parsing English.
+ */
+export interface StructuredError {
+    readonly type: string;
+    readonly code?: string;
+    readonly required_scope?: string;
+    readonly retry_after?: number;
+    readonly request_id?: string;
+    readonly message?: string;
+}
+export interface ToolResult {
+    readonly content: ReadonlyArray<ToolResultContent>;
+    readonly isError?: boolean;
+    readonly structuredError?: StructuredError;
+}
+/**
+ * One MCP tool. Foundation tools are auto-emitted by the generator;
+ * task tools are hand-authored.
+ *
+ * `inputSchema` is a Zod schema — Stream C converts it to JSON Schema for
+ * the MCP `tools/list` response (the MCP SDK accepts JSON Schema, and Zod
+ * provides `z.toJSONSchema(...)` ergonomics in v3+).
+ */
+export interface ToolModule {
+    readonly name: string;
+    readonly kind: ToolKind;
+    readonly description: string;
+    readonly required_scope: string;
+    readonly inputSchema: ZodTypeAny;
+    readonly handle: (args: unknown, ctx: ToolContext) => Promise<ToolResult>;
+    /**
+     * Claude UI Connectors Directory submission requirement (March 2025 MCP spec):
+     * every tool MUST advertise exactly one of `readOnlyHint` or `destructiveHint`.
+     * Foundation tools derive this from HTTP method (GET → readOnly, write verbs →
+     * destructive). Task tools must set it manually — natural language can mislead
+     * (e.g. `publish_product_to_channels` is destructive even though "publish"
+     * reads neutrally). Enforced by `test/tools/annotations.test.ts`.
+     *
+     * Mutually exclusive: setting both is a build-time error.
+     */
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+}
+/**
+ * Map a thrown SDK error into a structured ToolResult. Used by the
+ * dispatcher (Stream C) AND by task tools (Stream B) when they catch
+ * partial failures and want to fold them into the result.
+ *
+ * Accepts three input shapes:
+ *
+ *   1. A typed `ApiError` (or duck-typed equivalent) with camelCase fields
+ *      (`requiredScope`, `requestId`, `retryAfter`). This is what the SDK's
+ *      `unwrap()` / `mapErrorEnvelope()` produces.
+ *
+ *   2. The raw openapi-fetch `result.error` — the *parsed JSON body* of a
+ *      4xx/5xx response. Foundation tools call `client.raw.<METHOD>(...)`
+ *      directly and forward `result.error` here without going through
+ *      `unwrap()`. The body is shaped `{ error: { type, code, message,
+ *      required_scope, retry_after, request_id, ... } }` (snake_case wire
+ *      fields). We unwrap one layer if present.
+ *
+ *   3. Anything else (network-level errors, plain `Error`, etc.) — wrapped
+ *      as `type: "transport"` so the LLM doesn't try to interpret a
+ *      missing `required_scope`.
+ *
+ * Why the unwrap matters for W6 acceptance: §4 requires that scope-denied
+ * tool calls surface the `required_scope` field on the wire. Without the
+ * unwrap, foundation tools (which forward `result.error` from openapi-fetch)
+ * would emit `type: "transport"` and lose `required_scope` entirely. See
+ * test/e2e/inspector.test.ts and scripts/w6_smoke.sh probe A6.
+ */
+export declare function mapSdkErrorToToolResult(err: unknown): ToolResult;
+//# sourceMappingURL=contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/tools/contract.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEtC,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1E;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CA+DhE"}