zuplo 6.67.32 → 6.68.0

package/docs/mcp-server/prompts.mdx

@@ -0,0 +1,283 @@
+---
+title: MCP Server Prompts
+sidebar_label: Prompts
+---
+
+The MCP (Model Context Protocol) Server handler supports prompts in addition to
+tools, enabling you to provide reusable, parameterized prompt templates through
+the MCP protocol.
+
+MCP prompts allow AI clients to request and execute structured prompt templates
+with dynamic parameters, making it easy to standardize and share prompt patterns
+and context across different AI workflows.
+
+## Overview
+
+Much like tools, Zuplo's MCP prompts work by utilizing structured API routes as
+prompt generators that return formatted messages for AI consumption. When an MCP
+client calls a prompt, your route handler returns a structured message array
+that the AI can use directly.
+
+But unlike MCP tools that perform actions and return data, MCP prompts return
+formatted instructions or context that guide AI reasoning and responses.
+
+## Configuration
+
+### Route Configuration
+
+Configure a route in your OpenAPI doc utilizing the `x-zuplo-route.mcp.type`
+property:
+
+```json
+{
+  "/greeting": {
+    "post": {
+      "operationId": "greeting",
+      "summary": "Generate a personalized greeting",
+      "description": "Creates a customized greeting for a given person",
+      "requestBody": {
+        "required": true,
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The name of the person to greet"
+                }
+              },
+              "required": ["name"]
+            }
+          }
+        }
+      },
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "default",
+          "module": "$import(./modules/greeting)"
+        },
+        "mcp": {
+          "type": "prompt",
+          "name": "greeting_generator",
+          "description": "Utilize this prompt to generate a personalized greeting message"
+        }
+      }
+    }
+  }
+}
+```
+
+The `x-zuplo-route.mcp` configuration for prompts supports:
+
+- `type`: Must be set to `"prompt"` otherwise this will be registered as a tool.
+- `name` - (optional) The identifier for the MCP prompt. If not provided, falls
+  back to the `operationId` of the route. If no `operationId` is set, falls back
+  to an auto-generated name.
+- `description` - (optional) Description of what the prompt generates. If not
+  provided, falls back to the operation's `description` or `summary` fields. If
+  those are not set, uses an auto-generated description.
+
+### MCP Server Handler Configuration
+
+Add prompt configuration to your MCP Server handler options using the
+`operations` array:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "x-zuplo-route": {
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "name": "example-mcp-server",
+              "version": "1.0.0",
+              "operations": [
+                {
+                  "file": "./config/routes.oas.json",
+                  "id": "greeting"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+See further details in the
+[MCP Server Handler documentation](../handlers/mcp-server.mdx).
+
+## Route Handler Implementation
+
+Your route handler must return a structured response with a `messages` array
+containing properly formatted message objects: these are the message objects
+that will populate the LLM's context and guide it, based on the templatized user
+input, towards the desired result:
+
+```typescript
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const { name } = await request.json();
+
+  return {
+    messages: [
+      {
+        role: "assistant",
+        content: {
+          type: "text",
+          text: `Create a personalized greeting for ${name}. Make it friendly and welcoming!`,
+        },
+      },
+    ],
+  };
+}
+```
+
+For more information on the format of messages to return to the LLM,
+
+- `role`: Either “user” or “assistant” to indicate the speaker in the message
+  flow.
+- `content`: One of the following content
+  [types defined by the MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#promptmessage).
+
+For more information, review
+[the `PromptMessage` type and "Data Types" described in the MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#promptmessage).
+
+### Multiple Messages
+
+You can return multiple messages to create complex and dynamic templates:
+
+```typescript
+return {
+  messages: [
+    {
+      role: "assistant",
+      content: {
+        type: "text",
+        text: "You are a helpful assistant that generates personalized greetings.",
+      },
+    },
+    {
+      role: "assistant",
+      content: {
+        type: "text",
+        text: `Create a warm greeting for ${name} in ${location}. Consider local customs and time of day.`,
+      },
+    },
+  ],
+};
+```
+
+## Testing MCP Prompts
+
+### List Available Prompts
+
+Use the MCP `prompts/list` method to see available prompts:
+
+```bash
+curl localhost:9000/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "prompts/list"
+  }'
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "prompts": [
+      {
+        "name": "greeting_generator",
+        "description": "Generate a personalized greeting message for someone in a specific location",
+        "arguments": [
+          {
+            "name": "name",
+            "description": "The name of the person to greet",
+            "required": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Execute a Prompt
+
+Use the MCP `prompts/get` method to execute a prompt with parameters:
+
+```bash
+curl localhost:9000/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "prompts/get",
+    "params": {
+      "name": "greeting_generator",
+      "arguments": {
+        "name": "john"
+      }
+    }
+  }'
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "description": "Generate a personalized greeting message for someone in a specific location",
+    "messages": [
+      {
+        "role": "assistant",
+        "content": {
+          "type": "text",
+          "text": "Create a personalized greeting for john. Make it friendly and welcoming!"
+        }
+      }
+    ]
+  }
+}
+```
+
+## Best Practices
+
+### Prompt Design
+
+- Write clear, specific prompt instructions that guide AI behavior
+- Use parameter interpolation to create dynamic, contextual prompts
+- Include relevant context and constraints in your prompt text
+- Consider the target AI model's strengths and prompt formatting preferences
+
+### Parameter Schema
+
+- Define comprehensive JSON schemas for prompt parameters - this _must_ appear
+  as a `application/json` request body in a `POST` to your route. Typically,
+  this will point to a module that programmatically can craft the prompt.
+- Include helpful descriptions for each parameter
+- Mark required parameters appropriately
+- Use validation to ensure parameter quality
+
+### Message Organization
+
+- Use `system` messages for general behavior instructions
+- Use `assistant` messages for specific task guidance
+- Structure complex prompts as multiple focused messages
+- Keep individual messages concise and purposeful

package/docs/mcp-server/resources.mdx

@@ -0,0 +1,288 @@
+---
+title: MCP Server Resources
+sidebar_label: Resources
+---
+
+The MCP (Model Context Protocol) Server handler supports resources in addition
+to tools and prompts, enabling you to provide read-only access to data or
+documents through the MCP protocol.
+
+MCP resources allow AI clients to request and read static structured data or
+content, making it easy to expose documentation, configuration files, or any
+other read-only information that AI systems can consume.
+
+## Overview
+
+Zuplo's MCP resources work by utilizing API routes as resource endpoints that
+return content when requested by an MCP client. Resources are read-only and must
+use the GET HTTP method.
+
+Unlike MCP tools that perform actions or MCP prompts that generate instructions,
+MCP resources provide direct access to content like HTML documents, CSS files,
+JSON data, or any other text-based content.
+
+## Configuration
+
+### Route Configuration
+
+Configure a route in your OpenAPI doc. Resources **_must_** use the `GET`
+method:
+
+```json
+{
+  "/html": {
+    "get": {
+      "operationId": "html",
+      "description": "Returns the AI applet's HTML",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "default",
+          "module": "$import(./modules/html)"
+        },
+        "mcp": {
+          "type": "resource",
+          "name": "html_doc",
+          "description": "The HTML document for the AI applet",
+          "uri": "ui://html",
+          "mimeType": "text/html"
+        }
+      }
+    }
+  }
+}
+```
+
+To provide MCP specific metadata for the resource, use the `mcp` property within
+`x-zuplo-route`:
+
+- `type`: Must be set to `"resource"` otherwise the MCP server handler will
+  default to "tool".
+- `name` (optional) - The identifier for the MCP resource. Defaults to the
+  operation's `operationId`. If no `operationId` is provided, falls back to an
+  auto-generated name.
+- `description` (optional) - Description of what the resource provides. Falls
+  back to the operation's `description` or `summary`. If those fields are not
+  provided, falls back to an auto-generated description.
+- `uri` (optional) - The URI identifier for the resource (for example,
+  `"file:///example.txt"`, `"ui://html"`). Defaults to
+  `"mcp://resources/{name}"`.
+- `mimeType` (optional) - The MIME type of the resource content (for example,
+  `"text/html"`, `"text/css"`, `"application/json"`). Falls back to the
+  response's Content-Type header or `"text/plain"`.
+- `enabled` (optional) - Whether this resource is enabled. Defaults to `true`.
+- `_meta` (`object`: optional) - An object containing any arbitrary metadata.
+
+Without the `mcp` configuration, the MCP server will attempt to register it as a
+tool, or if configured as a resource via legacy methods, use the defaults
+described above.
+
+### MCP Server Handler Configuration
+
+Add resource configuration to your MCP Server handler options using the
+`operations` array:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "x-zuplo-route": {
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "name": "example-mcp-server",
+              "version": "1.0.0",
+              "operations": [
+                {
+                  "file": "./config/routes.oas.json",
+                  "id": "html"
+                },
+                {
+                  "file": "./config/routes.oas.json",
+                  "id": "css"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+See further details in the
+[MCP Server Handler documentation](../handlers/mcp-server.mdx).
+
+## Route Handler Implementation
+
+Your route handler should return the content to be exposed as a resource. The
+handler can return various types of content:
+
+### Text Content
+
+```typescript
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  return `<div id="my-ai-applet"></div>`;
+}
+```
+
+### CSS Content
+
+```typescript
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  return `div { color: blue; }`;
+}
+```
+
+### JSON Data
+
+```typescript
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  return {
+    version: "1.0.0",
+    features: ["feature1", "feature2"],
+  };
+}
+```
+
+The content returned by your handler will be automatically converted to text and
+exposed through the MCP resource protocol.
+
+## Resource Requirements
+
+:::warning
+
+Resources must meet the following requirements:
+
+- **HTTP Method**: Resources must use the GET method only. Resources are
+  read-only by design.
+- **Single Method**: Each resource route must define exactly one HTTP method.
+- **Unique Names**: Resource names must be unique across all configured
+  resources in the MCP server.
+
+:::
+
+## Testing MCP Resources
+
+### List Available Resources
+
+Use the MCP `resources/list` method to see available resources:
+
+```bash
+curl https://my-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "0",
+    "method": "resources/list"
+  }'
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "0",
+  "result": {
+    "resources": [
+      {
+        "name": "html",
+        "uri": "mcp://resources/html",
+        "title": "html",
+        "description": "Returns the AI applet's HTML",
+        "mimeType": "text/plain"
+      },
+      {
+        "name": "css_doc",
+        "uri": "ui://css",
+        "title": "css_doc",
+        "description": "The CSS resource",
+        "mimeType": "text/css"
+      }
+    ]
+  }
+}
+```
+
+### Read a Resource
+
+Use the MCP `resources/read` method to read a resource by its URI:
+
+```bash
+curl https://my-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "0",
+    "method": "resources/read",
+    "params": {
+      "uri": "mcp://resources/html"
+    }
+  }'
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "0",
+  "result": {
+    "contents": [
+      {
+        "uri": "mcp://resources/html",
+        "mimeType": "text/plain",
+        "text": "<div id=\"my-ai-applet\"></div>"
+      }
+    ]
+  }
+}
+```
+
+### Read a Resource with Custom URI
+
+```bash
+curl https://my-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "0",
+    "method": "resources/read",
+    "params": {
+      "uri": "ui://css"
+    }
+  }'
+```
+
+## Best Practices
+
+### Resource Design
+
+- Expose read-only content that provides useful context to AI systems
+- Use descriptive resource names that clearly indicate what content is available
+- Include meaningful descriptions to help AI systems understand when to use each
+  resource
+- Choose appropriate MIME types that accurately represent your content
+
+### URI Naming
+
+- Use meaningful URI schemes that indicate the type of resource (for example,
+  `ui://` for UI components, `config://` for configuration)
+- Keep URIs consistent and predictable across related resources
+- Consider using the default `mcp://resources/{name}` format for simple
+  resources
+
+### Content Organization
+
+- Keep resource content focused and purposeful
+- Update resource content dynamically based on current state when appropriate
+- Consider resource size - extremely large resources may impact performance
+- Use appropriate MIME types to help clients understand how to process the
+  content

package/docs/mcp-server/testing.mdx

@@ -0,0 +1,53 @@
+---
+title: MCP Server Testing
+sidebar_label: Testing
+---
+
+# Testing Tools
+
+## Using MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is ideal
+for testing tools:
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+1. Set **Transport Type** to "Streamable HTTP"
+2. Set **URL** to your MCP endpoint (for example,
+   `https://your-gateway.zuplo.dev/mcp`)
+3. Connect and test your tools interactively
+
+## Using cURL
+
+Test individual tools directly:
+
+```bash
+# List available tools
+curl https://your-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "0",
+    "method": "tools/list"
+  }'
+
+# Call a specific tool
+curl https://your-gateway.zuplo.dev/mcp \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/call",
+    "params": {
+      "name": "addNumbers",
+      "arguments": {
+        "a": 5,
+        "b": 3
+      }
+    }
+  }'
+```