feat: MCP Prompts documentation

docs/handlers/mcp-server-prompts.mdx

@@ -0,0 +1,285 @@
+---
+title: MCP Server Prompts
+sidebar_label: MCP Server 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:
+
+```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)"
+        }
+      }
+    }
+  }
+}
+```
+
+To provide MCP specific metadata for the prompt, use `x-zuplo-mcp-prompt`:
+
+```json
+"x-zuplo-mcp-prompt": {
+  "name": "greeting_generator",
+  "description": "Utilize this prompt to generate a personalized greeting message"
+},
+```
+
+The `x-zuplo-mcp-prompt` extension supports:
+
+- `name` - The identifier for the MCP prompt
+- `description` - Description of what the prompt generates
+
+Without `x-zuplo-mcp-prompt`, the MCP server will use the route's `operationId`
+as the prompt name and the `summary` as the prompt description.
+
+### MCP Server Handler Configuration
+
+Add prompt configuration to your MCP Server handler options:
+
+```json
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "x-zuplo-route": {
+          "handler": {
+            "export": "mcpServerHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "name": "example-mcp-server",
+              "version": "1.0.0",
+              "prompts": [
+                {
+                  "path": "./config/routes.oas.json",
+                  "operationIds": ["greeting"]
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `prompts` array supports:
+
+- `path` - Path to the OpenAPI specification file containing prompt routes
+- `operationIds` - Array of operation IDs to include as MCP prompts
+
+## Route Handler Implementation
+
+Your route handler must return a structured response with a `messages` array
+containing properly formatted message objects:
+
+```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!`,
+        },
+      },
+    ],
+  };
+}
+```
+
+### Message Structure
+
+Each message in the `messages` array should follow this structure:
+
+- `role` - The role of the message (`"assistant"`, `"user"`, or `"system"`)
+- `content` - The content object with:
+  - `type` - Content type (`"text"` for text content)
+  - `text` - The actual text content
+
+For more information, review
+[the `PromptMessage` type described in the MCP docs](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: "system",
+      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