zuplo 6.67.32 → 6.68.0

package/docs/mcp-server/graphql.mdx

@@ -0,0 +1,241 @@
+---
+title: MCP Server GraphQL Endpoints
+sidebar_label: GraphQL
+---
+
+The MCP Server Handler supports GraphQL endpoints through the `x-zuplo-route`
+OpenAPI extension. This allows you to expose GraphQL APIs as MCP tools with
+automatic schema introspection and query execution capabilities.
+
+When you configure a route with the GraphQL extension, the MCP server
+automatically generates two tools:
+
+1. **Introspection tool** - Fetches the GraphQL schema so AI systems can
+   understand available queries, mutations, and types
+2. **Execute tool** - Executes GraphQL queries against the endpoint
+
+This enables AI systems to dynamically discover and interact with GraphQL APIs
+without requiring manual tool definitions for each query.
+
+:::caution
+
+GraphQL endpoint support for MCP Server is currently in beta. The API may change
+in future releases.
+
+:::
+
+## Quick Start
+
+### 1. Configure a GraphQL Endpoint
+
+Add a route that forwards to your GraphQL endpoint and include the
+`x-zuplo-route.mcp` configuration:
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/graphql": {
+      "post": {
+        "operationId": "graphql",
+        "summary": "GraphQL API endpoint",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://api.example.com",
+              "followRedirects": true
+            }
+          },
+          "mcp": {
+            "type": "graphql"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. Add to Your MCP Server
+
+Include the GraphQL route in your MCP Server configuration using the
+`operations` array:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "summary": "MCP server",
+        "operationId": "mcp-server",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "name": "My MCP Server",
+              "version": "1.0.0",
+              "operations": [
+                {
+                  "file": "./config/routes.oas.json",
+                  "id": "graphql"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This configuration automatically creates:
+
+- `graphql_introspect` - Tool to fetch the GraphQL schema
+- `graphql_execute` - Tool to execute GraphQL queries
+
+## Configuration Options
+
+The `x-zuplo-route.mcp` configuration for GraphQL supports the following
+options:
+
+- `type`: Must be set to `"graphql"`
+- `enabled`: Whether the GraphQL MCP capabilities are enabled (default: `true`).
+- `introspectionTool`: Configuration for the introspection tool.
+  - `name`: Custom name for the introspection tool.
+  - `description`: Custom description for the introspection tool.
+- `executeTool`: Configuration for the execute tool.
+  - `name`: Custom name for the execute tool.
+  - `description`: Custom description for the execute tool.
+
+For example:
+
+```json
+{
+  "paths": {
+    "/graphql": {
+      "post": {
+        "operationId": "github_graphql",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://api.github.com"
+            }
+          },
+          "mcp": {
+            "type": "graphql",
+            "introspectionTool": {
+              "name": "github_schema",
+              "description": "Fetch the GitHub GraphQL schema"
+            },
+            "executeTool": {
+              "name": "github_query",
+              "description": "Execute a query against the GitHub GraphQL API"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Custom GraphQL Tools
+
+For more complex scenarios like bounded mutations or queries with complex logic,
+you can create custom GraphQL tools as endpoints using the Zuplo
+[custom MCP tool patterns](./custom-tools.mdx) and the `graphql` library.
+
+Here's a simple example of a custom bounded GraphQL query that expects an `id`
+input from the MCP client:
+
+```json
+{
+  "paths": {
+    "/graphql/ship": {
+      "post": {
+        "summary": "Get details about a specific ship",
+        "operationId": "get_ship",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["id"],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "The ID of the ship to query"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "x-zuplo-route": {
+          "handler": {
+            "export": "default",
+            "module": "$import(./modules/get-ship)"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+In your handler (`modules/get-ship.ts`):
+
+```typescript
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const { id } = await request.json();
+
+  const query = `
+    query GetShip($id: ID!) {
+      ship(id: $id) {
+        name
+        model
+        manufacturer
+      }
+    }
+  `;
+
+  const response = await fetch("https://api.example.com/graphql", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      query,
+      variables: { id },
+    }),
+  });
+
+  return response;
+}
+```
+
+For more complex custom tools with validation, error handling, and multi-step
+workflows, see the [Custom Tools documentation](./custom-tools.mdx).
+
+## See Also
+
+- [MCP Server Handler](./introduction.mdx) - Main MCP Server documentation
+- [Custom Tools](./custom-tools.mdx) - Build custom MCP tools with complex logic
+- [GraphQL Best Practices](https://graphql.org/learn/best-practices/) -
+  GraphQL.org recommendations

package/docs/mcp-server/introduction.mdx

@@ -0,0 +1,122 @@
+---
+title: Model Context Protocol (MCP)
+sidebar_label: Introduction
+---
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is
+an open protocol that enables controlled interactions between AI systems and
+agents. It enables external tools and data sources to be utilized and read by AI
+agents that implement the protocol.
+
+Developed by Anthropic, MCP standardizes how AI applications can connect to a
+robust number of services while maintaining user control.
+
+## What's MCP?
+
+MCP acts as a bridge between AI systems (like Cursor, Claude Desktop, ChatGPT,
+or other LLMs) and external resources such as:
+
+- APIs and databases
+- File systems and cloud storage
+- Development tools and services
+- Custom business backends and workflows
+
+The protocol ensures that AI interactions with external systems are:
+
+- **Auditable**: Full visibility into what tools are accessed and how they're
+  used via a simple [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
+  message flow.
+- **Standardized**: Consistent interface across different tools, servers,
+  clients, languages, and services.
+
+## How Zuplo Enables MCP
+
+Zuplo's MCP Server Handler provides a perfect foundation for MCP implementations
+by:
+
+1. **Unified API Interface**: Transform any backend API service into a
+   standardized MCP-compatible server
+2. **Security & Control**: Built-in authentication, rate limiting, and access
+   controls
+3. **Monitoring & Analytics**: Full observability into AI tool usage and
+   performance
+4. **Developer Experience**: Easy configuration and deployment using your
+   existing OpenAPI specifications
+
+The MCP Server Handler transforms your existing Zuplo API gateway into a
+powerful toolset that AI systems can discover, understand, and invoke - bringing
+AI capabilities directly into your business workflows!
+
+## MCP Implementation Options
+
+Zuplo provides two approaches for implementing MCP servers:
+
+### 1. MCP Server Handler: Transform Routes into AI Tools
+
+The MCP Server Handler automatically transforms your API gateway routes into MCP
+tools that AI systems can discover and use.
+
+#### How It Works
+
+The MCP Server Handler:
+
+1. **Route Discovery**: Automatically exposes your Zuplo routes as discoverable
+   MCP tools
+2. **OpenAPI Integration**: Uses your existing OpenAPI specifications to provide
+   tool descriptions
+3. **Secure Access**: Leverages Zuplo's authentication and authorization
+   policies
+4. **Real-time Execution**: AI systems can invoke your routes as tools in
+   real-time
+
+#### Example Use Cases
+
+##### Customer Service AI Tools
+
+Transform your customer management APIs into AI tools:
+
+```
+- GET /customers/{id} → "Get customer information for user 123"
+- POST /tickets → "Create a support ticket with the following ..."
+- PUT /customers/{id}/status → "Update customer 123 status ..."
+```
+
+##### E-commerce AI Assistant
+
+Expose your e-commerce APIs as shopping tools:
+
+```
+- GET /products/search → "Search for products ..."
+- POST /cart/add → "Add item to cart"
+- GET /orders/{id} → "Get order status"
+```
+
+##### DevOps Automation
+
+Make your infrastructure APIs available to AI:
+
+```
+- GET /deployments → "List deployments"
+- POST /deployments → "Create new deployment"
+- GET /metrics → "Get system metrics"
+```
+
+#### Security Considerations
+
+When exposing routes as MCP tools:
+
+1. **Apply appropriate authentication policies** to ensure only authorized AI
+   systems can access your tools
+2. **Use rate limiting** to prevent abuse and control usage costs
+3. **Implement audit logging** to track tool usage and maintain compliance
+4. **Scope permissions carefully** - only expose routes and OpenAPI specs that
+   should be accessible to AI systems
+
+## Learn More
+
+- [MCP Server Handler Technical Documentation](../handlers/mcp-server.mdx)
+- [MCP Tools Documentation](./tools.mdx)
+- [MCP Prompts Documentation](./prompts.mdx)
+- [MCP Resources Documentation](./resources.mdx)
+- [MCP Custom Tools Documentation](./custom-tools.mdx)
+- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)

package/docs/mcp-server/openai-apps-sdk.mdx

@@ -0,0 +1,160 @@
+---
+title: MCP Server With OpenAI Apps SDK
+sidebar_label: OpenAI Apps SDK
+---
+
+The [OpenAI Apps SDK](https://developers.openai.com/apps-sdk) is an integration
+of MCP that lets you expose applications to ChatGPT. Zuplo's MCP Server provides
+built-in support for the Apps SDK through `tools`, `resources`, and the
+`ZuploMcpSdk` class, which allows you to optionally access incoming request
+metadata and set response metadata required for ChatGPT widget rendering.
+
+:::warning
+
+The OpenAI Apps SDK and support for it in Zuplo's `mcpServerHandler` is in beta
+and subject to change!
+
+:::
+
+## `tools`
+
+MCP tools define the functionality of your app. Zuplo MCP servers support tools
+for the OpenAI Apps SDK with `_meta` metadata through the `x-zuplo-route.mcp`
+configuration. Learn more about configuration options for `tools` in
+[the MCP Server Tools documentation](./tools.mdx).
+
+## `resources`
+
+MCP resources are how your app's sandboxed widgets are displayed in the chat
+interface. Zuplo MCP servers support resources for the OpenAI Apps SDK with
+`_meta` metadata through the `x-zuplo-route.mcp` configuration. Learn more about
+configuration options for `resources` in
+[the MCP Server Resources documentation](./resources.mdx).
+
+## Configuring metadata
+
+When configuring and describing your tools and resources, you may need to set
+specific `annotations` and static `_meta` for when ChatGPT inspects these
+entities. `_meta` is the main way that the OpenAI Apps SDK interfaces with an
+MCP server. For example, an application may want to set a `readOnlyHint`
+annotation on a tool and define that the tool renders a component for your
+application with the static `_meta["openai/outputTemplate"]` metadata:
+
+```json
+"x-zuplo-route": {
+  "corsPolicy": "none",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/weather)"
+  },
+  "mcp": {
+    "type": "tool",
+    "name": "get_current_weather",
+    "description": "Retrieve and render application weather component",
+    "annotations": {
+      "readOnlyHint": true
+    },
+    "_meta": {
+      "openai/toolInvocation/invoking": "Getting weather ...",
+      "openai/toolInvocation/invoked": "Weather ready!",
+      "openai/outputTemplate": "ui://widget/weather.html"
+    }
+  }
+}
+```
+
+The resource defined at `ui://widget/weather.html` can then be used to render
+the app. Learn more about this in
+[the Zuplo MCP Server Tools documentation](./tools.mdx),
+[the OpenAI Apps SDK documentation for defining tools](https://developers.openai.com/apps-sdk/plan/tools)
+and
+[the OpenAI Apps SDK documentation for setting up tools and resources](https://developers.openai.com/apps-sdk/build/mcp-server).
+
+## `ZuploMcpSdk`
+
+The `ZuploMcpSdk` class in the `@zuplo/runtime` provides methods to interact
+with an MCP request and response metadata, which is essential for building
+ChatGPT Apps that return `structuredContent` and `_meta` payloads _out of band_
+of the typical API response flow.
+
+This means that you can still use your existing APIs as MCP tools for your
+OpenAI Apps SDK application while wrapping them with a custom module that uses
+`ZuploMcpSdk` in order to propagate `_meta` application state.
+
+### Usage
+
+Import the SDK and create an instance in your custom handler by passing in the
+request context:
+
+```typescript
+import { ZuploContext, ZuploMcpSdk, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const sdk = new ZuploMcpSdk(context);
+
+  // Access the incoming MCP request metadata
+  const mcpRequest = sdk.getRawCallToolRequest();
+  console.log(`Incoming _meta: ${JSON.stringify(mcpRequest?.params._meta)}`);
+
+  // Invoke another route on the gateway and get data for the application
+  const response = await context.invokeRoute("/v1/api/data");
+  const data = await response.json();
+
+  // Set metadata on the response for the ChatGPT widget
+  sdk.setRawCallToolResult({
+    content: [{ type: "text", text: "Data retrieved" }],
+    _meta: {
+      applicationState: data,
+      timestamp: new Date().toISOString(),
+    },
+  });
+
+  return data;
+}
+```
+
+:::note
+
+`context.invokeRoute` keeps the new request within the gateway: it does _not_ go
+back out to HTTP. But it's important to keep in mind that an invoked route on
+the gateway _will_ re-invoke the inbound and outbound policy pipeline for the
+invoked route!
+
+:::
+
+### Methods
+
+#### `getRawCallToolRequest()`
+
+Retrieves the raw MCP `tools/call` request object, including any `_meta` sent by
+ChatGPT. Use this to access client context hints like locale or user agent.
+
+```typescript
+const mcpRequest = sdk.getRawCallToolRequest();
+const locale = mcpRequest?.params._meta?.["openai/locale"];
+```
+
+#### `setRawCallToolResult(result)`
+
+Sets the MCP tool result, including the `_meta` field that is sent to the
+ChatGPT widget but not visible to the model. Use this to pass data that your
+widget needs for rendering.
+
+```typescript
+sdk.setRawCallToolResult({
+  content: [{ type: "text", text: "Operation complete" }],
+  _meta: {
+    detailedData: largeDataObject,
+    lastSyncedAt: new Date().toISOString(),
+  },
+});
+```
+
+---
+
+For complete documentation on building ChatGPT Apps, see the
+[OpenAI Apps SDK documentation](https://developers.openai.com/apps-sdk) and
+[the OpenAI Apps SDK guide on setting up your MCP server](https://developers.openai.com/apps-sdk/build/mcp-server)