zuplo 7.4.4 → 7.4.5

package/docs/programmable-api/mcp-sdk.mdx

@@ -0,0 +1,240 @@
+---
+title: ZuploMcpSdk
+sidebar_label: MCP SDK
+description:
+  Reference for the ZuploMcpSdk class, which gives custom MCP tool handlers
+  access to the incoming tool call request and control over the tool result sent
+  back to the AI client.
+---
+
+The `ZuploMcpSdk` class provides a helper API for custom MCP tool handlers to
+interact with the MCP runtime. Use it to read metadata from the incoming
+`tools/call` request and to override fields of the tool result the gateway sends
+back to the AI client.
+
+```ts
+import { ZuploContext, ZuploMcpSdk, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const sdk = new ZuploMcpSdk(context);
+
+  // Read the incoming tool call request
+  const mcpRequest = sdk.getRawCallToolRequest();
+  context.log.info(`Tool called: ${mcpRequest?.params.name}`);
+
+  // Invoke a route on your gateway
+  const response = await context.invokeRoute("/todos");
+
+  // Override the content the model sees, keeping auto-derived structuredContent
+  sdk.setRawCallToolResult({
+    content: [{ type: "text", text: "Fetched the todo list" }],
+  });
+
+  return response;
+}
+```
+
+`ZuploMcpSdk` is available in custom tool handlers for both the
+[MCP Server handler](../handlers/mcp-server.mdx) and the
+[MCP Gateway](../mcp-gateway/introduction.mdx). It is exported from
+`@zuplo/runtime`.
+
+## Methods
+
+### `setRawCallToolResult(result)`
+
+Overrides fields of the MCP tool result the gateway is about to send to the AI
+client. Every field is independently optional — an absent field keeps the value
+the gateway derives from the downstream response.
+
+```ts
+setRawCallToolResult(result: ZuploMcpToolResultOverride): void
+```
+
+#### Parameters
+
+The `result` argument is a `ZuploMcpToolResultOverride` object with the
+following optional fields:
+
+| Field               | Type                        | Description                                                                                                                  |
+| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `content`           | `CallToolResult["content"]` | Content blocks the model reads. Replaces the gateway's default (the serialized downstream body in a text block).             |
+| `structuredContent` | `Record<string, unknown>`   | The structured form of the tool's output. Must be a JSON object — the MCP 2025-11-25 wire format rejects arrays and scalars. |
+| `_meta`             | `Record<string, unknown>`   | Per-call metadata. Replaces the gateway's default of `{}`.                                                                   |
+
+#### Compact summary example
+
+The most useful combination is `content` alone: a human-readable summary
+replaces the raw serialized body in the model's context, while
+`structuredContent` is still auto-derived from the downstream response. This
+reduces token consumption without losing data.
+
+```ts
+import { ZuploContext, ZuploMcpSdk, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await context.invokeRoute("/todos");
+  new ZuploMcpSdk(context).setRawCallToolResult({
+    content: [{ type: "text", text: "Fetched the todo list" }],
+  });
+  return response;
+}
+```
+
+The model sees `"Fetched the todo list"` instead of the full JSON body, but the
+`structuredContent` field still carries the complete payload for spec-compliant
+clients that read it.
+
+#### Full override example
+
+Override all available fields at once:
+
+```ts
+import { ZuploContext, ZuploMcpSdk, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await context.invokeRoute("/orders");
+  const orders = await response.json();
+
+  new ZuploMcpSdk(context).setRawCallToolResult({
+    content: [
+      {
+        type: "text",
+        text: `Found ${orders.length} orders totaling $${orders.total}`,
+      },
+    ],
+    structuredContent: { orders: orders.items, count: orders.length },
+    _meta: { source: "order-service", version: "2.0" },
+  });
+
+  return response;
+}
+```
+
+:::note
+
+**`isError` is not overridable.** It follows the HTTP status of the response
+your handler returns, so upstream failures cannot be masked. If the downstream
+route returns a non-2xx status, the tool result carries `isError: true`
+regardless of any override.
+
+:::
+
+:::caution{title="Single-use — consumed once"}
+
+The override is **consumed** when the gateway assembles the tool result. It is
+read and deleted from the context at that point, so calling
+`setRawCallToolResult` twice in the same request replaces the first value before
+the gateway reads it.
+
+:::
+
+#### How context lookup works
+
+`setRawCallToolResult` writes the override to the context that carried the
+matching `tools/call` request. The lookup travels exactly one
+`context.invokeRoute` generation up from the context passed to the constructor.
+
+This means:
+
+- In a typical custom tool handler that calls `context.invokeRoute`, the
+  override is written to the parent context (the one carrying the `tools/call`
+  request), which is correct.
+- If your handler calls `invokeRoute` to a route that **also** calls
+  `invokeRoute`, and you construct `ZuploMcpSdk` in that grandchild invocation,
+  the override is stored on the immediate parent — not the grandparent that
+  carries the tool call. The gateway never reads it. Construct `ZuploMcpSdk` in
+  the handler that is one level below the MCP route.
+
+### `getRawCallToolRequest()`
+
+Retrieves the original MCP `tools/call` request object from the context. Use
+this to access metadata like the `_meta` field from the incoming tool call.
+
+```ts
+getRawCallToolRequest(): CallToolRequest | null
+```
+
+Returns the `CallToolRequest` object, or `null` if no MCP tool call is in flight
+on the current or parent context.
+
+```ts
+import { ZuploContext, ZuploMcpSdk, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const sdk = new ZuploMcpSdk(context);
+  const mcpRequest = sdk.getRawCallToolRequest();
+
+  if (mcpRequest) {
+    const meta = mcpRequest.params._meta;
+    context.log.info(`Incoming _meta: ${JSON.stringify(meta)}`);
+  }
+
+  // ... handle the tool call
+}
+```
+
+Unlike `setRawCallToolResult`, this method can be called any number of times —
+the request object is not consumed.
+
+## Output schema enforcement
+
+When a tool advertises an `outputSchema` (via `includeOutputSchema` on the
+handler or route config), the gateway validates the tool result's
+`structuredContent` against that schema before sending it to the client. A
+result whose `structuredContent` does not conform to the advertised schema fails
+the call with a diagnostic `isError` result instead of a raw protocol error.
+
+This enforcement is skipped on the error path (`isError: true`), matching the
+MCP SDK's own behavior.
+
+### `includeOutputSchema` implies `includeStructuredContent`
+
+Advertising an `outputSchema` while returning no `structuredContent` makes the
+advertised schema inaccurate — spec-compliant clients reject the call. When
+`includeOutputSchema` resolves to `true`, the gateway automatically forces
+`includeStructuredContent` to `true` as well, and logs a warning naming the
+route where the override kicked in.
+
+You can set both explicitly to avoid the warning:
+
+```json
+{
+  "x-zuplo-route": {
+    "handler": {
+      "export": "mcpServerHandler",
+      "module": "$import(@zuplo/runtime)",
+      "options": {
+        "includeOutputSchema": true,
+        "includeStructuredContent": true
+      }
+    }
+  }
+}
+```
+
+## Type reference
+
+### `ZuploMcpToolResultOverride`
+
+```ts
+interface ZuploMcpToolResultOverride {
+  content?: CallToolResult["content"];
+  structuredContent?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+}
+```
+
+The subset of a `tools/call` result that a module author may override via
+`setRawCallToolResult`. Every field is independently optional.
+
+## See also
+
+- [MCP Server custom tools](../mcp-server/custom-tools.mdx) — how to build
+  custom MCP tool handlers with TypeScript
+- [MCP Server handler](../handlers/mcp-server.mdx) — handler configuration
+  reference including `includeOutputSchema` and `includeStructuredContent`
+- [MCP Gateway introduction](../mcp-gateway/introduction.mdx) — overview of the
+  MCP Gateway product
+- [MCP specification](https://modelcontextprotocol.io/specification/) — the
+  canonical protocol reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.4.4",
+  "version": "7.4.5",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.4.4",
-    "@zuplo/core": "7.4.4",
-    "@zuplo/runtime": "7.4.4",
-    "@zuplo/test": "7.4.4"
+    "@zuplo/cli": "7.4.5",
+    "@zuplo/core": "7.4.5",
+    "@zuplo/runtime": "7.4.5",
+    "@zuplo/test": "7.4.5"
   }
 }