zuplo 6.67.32 → 6.68.0

package/docs/mcp-server/custom-tools.mdx

@@ -0,0 +1,487 @@
+---
+title: MCP Server Custom Tools
+sidebar_label: Custom Tools
+---
+
+The MCP Server Handler supports custom tools that allow you to create
+sophisticated MCP
+([Model Context Protocol](https://modelcontextprotocol.io/introduction)) tools
+using OpenAPI specifications and custom handler functions. This provides the
+flexibility to build complex workflows that can invoke multiple API routes,
+implement custom business logic, and provide rich responses to AI systems
+without having to sacrifice the governance and power of an OpenAPI
+configuration.
+
+:::tip
+
+Custom tools give you full programmatic control over tool behavior within an
+[MCP Server Handler](../handlers/mcp-server.mdx). Define tools using standard
+OpenAPI patterns with custom TypeScript handlers for complex multi-step
+workflows and custom logic.
+
+:::
+
+## Key Features
+
+- **OpenAPI Standard**: Define tools using standard OpenAPI specifications
+- **Custom Handlers**: Implement complex logic using TypeScript functions
+- **Complex Workflows**: Chain multiple API calls, implement business logic, and
+  handle complex data transformations
+- **Type Safety**: Built-in JSON Schema validation for LLM tool arguments and
+  inputs
+- **Runtime Integration**: Access to `context.invokeRoute()`, logging, and other
+  Zuplo runtime features
+
+## Quick Start
+
+### 1. Define Your API Specification
+
+Create an OpenAPI specification that defines your tools:
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "version": "0.0.1",
+    "title": "My Calculator API",
+    "description": "A simple calculator API with basic arithmetic operations"
+  },
+  "paths": {
+    "/add": {
+      "post": {
+        "summary": "Add two numbers",
+        "description": "Adds two numbers together and returns the result",
+        "operationId": "addNumbers",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TwoNumberOperation"
+              }
+            }
+          }
+        },
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "default",
+            "module": "$import(./modules/add)"
+          },
+          "mcp": {
+            "type": "tool"
+          }
+        }
+      }
+    },
+    "/multiply": {
+      "post": {
+        "summary": "Multiply two numbers",
+        "description": "Multiplies two numbers together and returns the result",
+        "operationId": "multiplyNumbers",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TwoNumberOperation"
+              }
+            }
+          }
+        },
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "default",
+            "module": "$import(./modules/multiply)"
+          },
+          "mcp": {
+            "type": "tool"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "TwoNumberOperation": {
+        "type": "object",
+        "required": ["a", "b"],
+        "properties": {
+          "a": {
+            "type": "number",
+            "description": "First number"
+          },
+          "b": {
+            "type": "number",
+            "description": "Second number"
+          }
+        },
+        "example": {
+          "a": 10,
+          "b": 5
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. Create Custom Handler Functions
+
+Create handler modules for your tools that map to your routes:
+
+```typescript
+// modules/add.ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const args = await request.json();
+  context.log.info(`Adding ${args.a} + ${args.b}`);
+  return args.a + args.b;
+}
+```
+
+```typescript
+// modules/multiply.ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const args = await request.json();
+  context.log.info(`Multiplying ${args.a} * ${args.b}`);
+  return args.a * args.b;
+}
+```
+
+### 3. Configure the MCP Server Handler
+
+Configure the MCP Server Handler to use your OpenAPI specification:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "operationId": "mcp-server-handler",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "name": "Calculator MCP Server",
+              "version": "0.0.0",
+              "operations": [
+                {
+                  "file": "./config/calculator-api.oas.json",
+                  "id": "addNumbers"
+                },
+                {
+                  "file": "./config/calculator-api.oas.json",
+                  "id": "multiplyNumbers"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Deploy and Test
+
+Deploy your project and test your MCP server:
+
+```bash
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector
+
+# Or test with curl
+curl https://your-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{ "jsonrpc": "2.0", "id": "0", "method": "tools/list" }'
+```
+
+## Advanced Usage
+
+### Complex Multi-Step Workflows
+
+Create sophisticated workflows that chain multiple operations:
+
+```typescript
+// modules/process-order.ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const args = await request.json();
+
+  // Step 1: Validate customer
+  const customerResp = await context.invokeRoute(
+    `/customers/${args.customerId}`,
+  );
+  if (!customerResp.ok) {
+    throw new Error("Customer not found");
+  }
+
+  // Step 2: Check inventory
+  const inventoryChecks = await Promise.all(
+    args.items.map((item: any) =>
+      context.invokeRoute(
+        `/inventory/${item.productId}/check?quantity=${item.quantity}`,
+      ),
+    ),
+  );
+
+  const unavailableItems = inventoryChecks
+    .map((resp, i) => ({ resp, item: args.items[i] }))
+    .filter(({ resp }) => !resp.ok)
+    .map(({ item }) => item.productId);
+
+  if (unavailableItems.length > 0) {
+    throw new Error(`Items not available: ${unavailableItems.join(", ")}`);
+  }
+
+  // Step 3: Create order
+  const orderResp = await context.invokeRoute("/orders", {
+    method: "POST",
+    body: JSON.stringify({
+      customerId: args.customerId,
+      items: args.items,
+    }),
+    headers: { "Content-Type": "application/json" },
+  });
+
+  const order = await orderResp.json();
+
+  return {
+    orderId: order.id,
+    status: "created",
+    total: order.total,
+    estimatedDelivery: order.estimatedDelivery,
+  };
+}
+```
+
+This utilizes `context.invokeRoute` to invoke various routes on a gateway. This
+powerful workflow lets you create composite routes and tools that call many
+different routes on your gateway.
+
+:::note
+
+`context.invokeRoute` _will_ utilize the full inbound and outbound policy
+pipeline but does not go back out to HTTP: requests stay within the gateway.
+This means that policies you set on your MCP server route will be invoked
+alongside policies that are associated with any calls made through
+`context.invokeRoute`.
+
+:::
+
+A corresponding OpenAPI definition makes this custom route available on your
+gateway.
+
+```json
+{
+  "/process-order": {
+    "post": {
+      "summary": "Process a customer order",
+      "description": "Process a customer order through multiple validation steps",
+      "operationId": "processOrder",
+      "requestBody": {
+        "required": true,
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "required": ["customerId", "items"],
+              "properties": {
+                "customerId": {
+                  "type": "string",
+                  "description": "Unique customer identifier"
+                },
+                "items": {
+                  "type": "array",
+                  "description": "List of items to order",
+                  "items": {
+                    "type": "object",
+                    "required": ["productId", "quantity"],
+                    "properties": {
+                      "productId": {
+                        "type": "string",
+                        "description": "Product identifier"
+                      },
+                      "quantity": {
+                        "type": "number",
+                        "description": "Number of items to order"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "responses": {
+        "200": {
+          "description": "Order processed successfully",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "orderId": {
+                    "type": "string",
+                    "description": "Generated order ID"
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": ["created", "pending", "confirmed"],
+                    "description": "Order status"
+                  },
+                  "total": {
+                    "type": "number",
+                    "description": "Total amount"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "x-zuplo-route": {
+        "handler": {
+          "export": "default",
+          "module": "$import(./modules/process-order)"
+        }
+      }
+    }
+  }
+}
+```
+
+Then, simply add this operation to an MCP server to make it available as a tool:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "x-zuplo-route": {
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "operations": [
+                {
+                  "file": "./config/routes.oas.json",
+                  "id": "processOrder"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Error Handling
+
+Handle errors gracefully by throwing standard JavaScript errors. These then get
+caught by the MCP Server and are served back to the LLM client so it can take
+action:
+
+```typescript
+// modules/validate-user.ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const args = await request.json();
+
+  if (args.shouldFail) {
+    throw new Error(args.errorMessage || "Validation failed");
+  }
+
+  return { valid: true, userId: args.userId };
+}
+```
+
+### Accessing Request Headers
+
+Access the original request headers through the standard `ZuploRequest` object.
+These headers are piped through the MCP server on your gateway into your route.
+This means you can handle headers from MCP clients like you would on any other
+route:
+
+```typescript
+// modules/check-headers.ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const args = await request.json();
+  const headerValue = request.headers.get(args.headerName);
+
+  if (headerValue) {
+    return `Header '${args.headerName}': ${headerValue}`;
+  } else {
+    return `Header '${args.headerName}' not found`;
+  }
+}
+```
+
+## Best Practices
+
+### Tool Design
+
+1. **Clear Operation IDs**: Use descriptive, action-oriented operation IDs
+   (`addNumbers`, `processOrder`)
+2. **Detailed Descriptions**: Help AI systems understand what your tool does
+3. **Error Handling**: Throw meaningful JavaScript errors
+4. **Unique Names**: Ensure operation IDs are unique across your API
+
+## Troubleshooting
+
+### Common Issues
+
+**Tool not appearing in `tools/list`:**
+
+- Check that the endpoint is a POST method in your OpenAPI spec
+- Verify the operation has an `operationId`
+- Check for validation errors in your OpenAPI specification
+- Ensure the handler module exports a default function
+
+**Handler execution failures:**
+
+- Use `context.log.error()`, `context.log.warn()`, `context.log.info()` for
+  logging
+- Verify API routes being invoked through `invokeRoute` exist and are accessible
+- Test individual API calls outside the MCP context
+- Check that your handler function is properly exported as default
+
+**Schema validation errors:**
+
+- Ensure JSON schemas are properly defined in the OpenAPI spec
+- Check that request body schemas match the data your handler expects
+- Verify response schemas match the data your handler returns
+
+### Debugging Tips
+
+1. **Enable Debug Logging**: Use `context.log.debug()` liberally and turn on
+   [debug mode in your MCP server](../handlers/mcp-server.mdx)
+2. **Test Components Separately**: Test API routes and business logic
+   independently
+3. **Use MCP Inspector**: Interactive testing is invaluable for development
+4. **Validate OpenAPI**: Use tools like Swagger Editor to validate your OpenAPI
+   specification
+
+## Learn More
+
+- [MCP Server Handler](../handlers/mcp-server.mdx) - For simple route-to-tool
+  mapping
+- [Model Context Protocol Overview](../mcp-server/introduction.mdx) -
+  Understanding MCP concepts
+- [MCP Specification](https://modelcontextprotocol.io/specification/) - Official
+  protocol documentation