yupno-mcp-server 1.0.3 → 2.0.0

package/README.md

@@ -1,61 +1,150 @@
-# Yupno MCP Server
+# Yupno MCP App Server
 
-MCP server for creating and managing events on [Yupno](https://yupno.io).
+MCP App server for creating and managing events on [Yupno](https://yupno.io) with visual preview support.
+
+## Features
+
+- **Visual Preview**: See your event card rendered in real-time as Claude creates it
+- **Streaming Support**: Preview updates progressively as Claude generates event details
+- **Theme Preview**: See colors, fonts, and background images applied immediately
+- **Dual Transport**: Works with both Claude Desktop (stdio) and HTTP-based hosts
 
 ## Installation
 
+```bash
+npm install yupno-mcp-server
+```
+
+Or run directly:
+
 ```bash
 npx yupno-mcp-server
 ```
 
 ## Configuration
 
-Add to your Claude settings:
+### Claude Desktop / Claude Code (Stdio Mode)
+
+Add to your Claude settings (`~/.claude/settings.json` or Claude Desktop config):
 
 ```json
 {
   "mcpServers": {
     "yupno": {
       "command": "npx",
-      "args": ["-y", "yupno-mcp-server"]
+      "args": ["-y", "yupno-mcp-server", "--stdio"]
     }
   }
 }
 ```
 
+### HTTP Mode (for development/testing)
+
+```bash
+npx yupno-mcp-server
+# Server runs on http://localhost:3001/mcp
+```
+
+Or with custom port:
+
+```bash
+PORT=8080 npx yupno-mcp-server
+```
+
 ## Available Tools
 
-### create_event
+### create_event (with UI preview)
 
-Create a new event with optional theming.
+Create a new event with visual preview.
 
 **Example prompt:** "Create an 80s party event for tomorrow at 7pm with a neon theme"
 
+**Parameters:**
+- `title` (required) - Event title (2-4 words, no emojis)
+- `eventDate` (required) - Start date/time in ISO 8601 format
+- `location` - Physical address or venue name
+- `description` - 2-3 sentences about the event
+- `theme` - Visual theme options (see below)
+- `customCss` - Advanced CSS customization
+
 ### get_event
 
-Get details of an existing event.
+Get details of an existing event by its event token.
 
-### update_event
+### update_event (with UI preview)
 
-Update an event (requires admin token).
+Update an event (requires admin token). Shows preview of changes.
 
 ### delete_event
 
 Delete an event (requires admin token).
 
+### get_rsvps
+
+Get the RSVP list for an event (requires admin token).
+
 ## Theme Options
 
 When creating events, you can specify visual themes:
 
-- `primaryColor` - Hex color for buttons/accents
-- `accentColor` - Secondary color
-- `backgroundColor` - Page background
-- `textColor` - Text color (for dark backgrounds)
-- `fontFamily` - Google Font name
-- `backgroundUrl` - HTTPS image URL
-- `backgroundOverlay` - Overlay opacity (0-1)
+| Option | Description | Example |
+|--------|-------------|---------|
+| `primaryColor` | Button/accent color | `#ff6b6b` |
+| `accentColor` | Secondary color | `#a84e30` |
+| `backgroundColor` | Page background | `#1a1a2e` (dark) or `#faf7f2` (light) |
+| `textColor` | Text color | `#ffffff` (for dark bg) or `#2d3436` (for light bg) |
+| `fontFamily` | Google Font name | `Poppins`, `Inter`, `Playfair Display` |
+| `backgroundUrl` | HTTPS image URL | Unsplash URL |
+| `backgroundOverlay` | Overlay opacity (0-1) | `0.6` (required with backgroundUrl) |
+
+### Recommended Fonts
+
+**Modern:** Poppins, Inter, Space Grotesk, Montserrat
+**Elegant:** Playfair Display, Cormorant Garamond
+**Bold:** Bebas Neue, Oswald, Righteous
+**Fun:** Bangers, Press Start 2P (avoid Lobster, Pacifico)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode (watches for changes)
+npm run dev
+
+# Build for production
+npm run build
+
+# Test with basic-host
+SERVERS='["http://localhost:3001/mcp"]' npm run basic-host
+```
+
+## Architecture
+
+```
+mcp-server/
+├── server.ts          # MCP server with registerAppTool/registerAppResource
+├── main.ts            # Entry point with dual transport support
+├── src/
+│   ├── event-preview.html   # UI template
+│   ├── event-preview.ts     # Client-side app logic
+│   ├── event-preview.css    # Event card styles
+│   └── global.css           # Base styles
+└── dist/              # Built output
+```
+
+## How It Works
+
+1. When Claude calls `create_event` or `update_event`, the server returns both:
+   - **Text content**: For Claude Code and non-UI hosts
+   - **UI reference**: Points to the event preview resource
+
+2. Claude Desktop fetches the UI resource and renders it in an iframe
 
-### Suggested Fonts
+3. The UI receives tool input via `ontoolinput` and `ontoolinputpartial` handlers:
+   - `ontoolinputpartial`: Shows preview as Claude streams the event data
+   - `ontoolinput`: Final render when input is complete
+   - `ontoolresult`: Displays event links after creation
 
-Press Start 2P, Monoton, Righteous, Bangers, Lobster, Pacifico,
-Playfair Display, Oswald, Bebas Neue, Space Grotesk
+4. Theme and custom CSS are applied to the preview card in real-time

package/dist/main.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Yupno MCP App Server - Entry Point
+ *
+ * Usage:
+ *   node dist/index.js          # HTTP mode (default) - for web hosts and testing
+ *   node dist/index.js --stdio  # Stdio mode - for Claude Desktop/Claude Code
+ *
+ * HTTP mode serves on http://localhost:3001/mcp (configurable via PORT env var)
+ * Stdio mode communicates via stdin/stdout for CLI integration
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
+ * This is the default mode, suitable for web-based hosts and local testing.
+ */
+export declare function startStreamableHTTPServer(createServerFn: () => McpServer): Promise<void>;
+/**
+ * Starts an MCP server with stdio transport.
+ * Use this mode for Claude Desktop and Claude Code integration.
+ */
+export declare function startStdioServer(createServerFn: () => McpServer): Promise<void>;

package/dist/main.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Yupno MCP App Server - Entry Point
+ *
+ * Usage:
+ *   node dist/index.js          # HTTP mode (default) - for web hosts and testing
+ *   node dist/index.js --stdio  # Stdio mode - for Claude Desktop/Claude Code
+ *
+ * HTTP mode serves on http://localhost:3001/mcp (configurable via PORT env var)
+ * Stdio mode communicates via stdin/stdout for CLI integration
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import { createServer } from "./server.js";
+/**
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
+ * This is the default mode, suitable for web-based hosts and local testing.
+ */
+export async function startStreamableHTTPServer(createServerFn) {
+    const port = parseInt(process.env.PORT ?? "3001", 10);
+    const app = createMcpExpressApp({ host: "0.0.0.0" });
+    app.use(cors());
+    app.all("/mcp", async (req, res) => {
+        const server = createServerFn();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on("close", () => {
+            transport.close().catch(() => { });
+            server.close().catch(() => { });
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            console.error("MCP error:", error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    const httpServer = app.listen(port, (err) => {
+        if (err) {
+            console.error("Failed to start server:", err);
+            process.exit(1);
+        }
+        console.log(`Yupno MCP App server listening on http://localhost:${port}/mcp`);
+        console.log("Use --stdio flag for Claude Desktop/Claude Code integration");
+    });
+    const shutdown = () => {
+        console.log("\nShutting down...");
+        httpServer.close(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+/**
+ * Starts an MCP server with stdio transport.
+ * Use this mode for Claude Desktop and Claude Code integration.
+ */
+export async function startStdioServer(createServerFn) {
+    const server = createServerFn();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Yupno MCP App server running (stdio mode)");
+}
+async function main() {
+    if (process.argv.includes("--stdio")) {
+        await startStdioServer(createServer);
+    }
+    else {
+        await startStreamableHTTPServer(createServer);
+    }
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ */
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,253 @@
+/**
+ * Yupno MCP App Server
+ * Creates events with visual preview support in Claude Desktop
+ */
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+const YUPNO_API = process.env.YUPNO_API_URL || "https://yupno.io";
+// Works both from source (server.ts) and compiled (dist/server.js)
+const DIST_DIR = import.meta.filename.endsWith(".ts")
+    ? path.join(import.meta.dirname, "dist")
+    : import.meta.dirname;
+// Resource URI for the event preview UI
+const EVENT_PREVIEW_RESOURCE = "ui://yupno/event-preview.html";
+// Shared theme schema
+const themeSchema = z.object({
+    primaryColor: z.string().optional().describe("Hex color for buttons"),
+    accentColor: z.string().optional().describe("Hex color for secondary elements"),
+    backgroundColor: z.string().optional().describe("Hex color for page background"),
+    textColor: z.string().optional().describe("Hex color for text"),
+    fontFamily: z.string().optional().describe("Google Font name"),
+    backgroundUrl: z.string().optional().describe("HTTPS URL for background image"),
+    backgroundOverlay: z.number().min(0).max(1).optional().describe("Dark overlay opacity 0-1"),
+}).optional();
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ */
+export function createServer() {
+    const server = new McpServer({
+        name: "Yupno Events",
+        version: "2.0.0",
+    });
+    // Register the event preview UI resource
+    registerAppResource(server, EVENT_PREVIEW_RESOURCE, EVENT_PREVIEW_RESOURCE, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const html = await fs.readFile(path.join(DIST_DIR, "src", "event-preview.html"), "utf-8");
+        return {
+            contents: [
+                { uri: EVENT_PREVIEW_RESOURCE, mimeType: RESOURCE_MIME_TYPE, text: html },
+            ],
+        };
+    });
+    // Create event tool with UI support
+    registerAppTool(server, "create_event", {
+        title: "Create Event",
+        description: `Create a new event on Yupno. Returns admin URL (for managing) and guest URL (for sharing).
+
+IMPORTANT - ALWAYS INCLUDE:
+- title: Short (2-4 words), NO emojis
+- eventDate: When the event starts
+- location: Where it's happening
+- description: 2-3 sentences about the event (what to expect, dress code, etc.)
+
+DESIGN RULES:
+- Fonts: Use Poppins, Inter, Playfair Display, or Montserrat. AVOID Lobster/Pacifico
+- Colors: Dark bg (#1a1a2e) needs light text (#ffffff). Light bg (#faf7f2) needs dark text (#2d3436)
+- Background images: Always set backgroundOverlay 0.5-0.7 for readability
+
+EXAMPLE:
+{
+  "title": "Summer Beats",
+  "eventDate": "2024-06-15T20:00:00",
+  "location": "The Rooftop, 123 Main St",
+  "description": "Join us for an unforgettable night of music and dancing. Dress code: smart casual.",
+  "theme": { "primaryColor": "#ff6b6b", "backgroundColor": "#1a1a2e", "textColor": "#ffffff", "fontFamily": "Poppins" }
+}`,
+        inputSchema: {
+            title: z.string().describe("Event title - keep SHORT (2-4 words), NO emojis"),
+            eventDate: z.string().describe("Start date/time in ISO 8601 format (REQUIRED)"),
+            endDate: z.string().optional().describe("End date/time in ISO 8601 format"),
+            timezone: z.string().optional().describe("IANA timezone (e.g., America/New_York)"),
+            location: z.string().optional().describe("Physical address or venue name"),
+            description: z.string().optional().describe("2-3 sentences about the event"),
+            organizerName: z.string().optional().describe("Name of the host/organizer"),
+            showGuestList: z.boolean().optional().describe("Show who's attending"),
+            collectEmail: z.boolean().optional().describe("Ask for guest email"),
+            rsvpDeadline: z.string().optional().describe("ISO 8601 date/time for RSVP cutoff"),
+            rsvpDeadlineHard: z.boolean().optional().describe("If true, block RSVPs after deadline"),
+            theme: themeSchema.describe("Visual theme"),
+            customCss: z.string().optional().describe("Raw CSS to inject"),
+        },
+        _meta: { ui: { resourceUri: EVENT_PREVIEW_RESOURCE } },
+    }, async (args) => {
+        try {
+            const res = await fetch(`${YUPNO_API}/api/v1/events`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(args),
+            });
+            const data = (await res.json());
+            if (!res.ok) {
+                return {
+                    content: [{ type: "text", text: `Error: ${data.error || JSON.stringify(data)}` }],
+                    structuredContent: { error: data.error || "Failed to create event" },
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Event created successfully!
+
+Admin URL (save this - for managing RSVPs): ${data.links.admin}
+Guest URL (share this): ${data.links.guest}
+
+Admin Token: ${data.adminToken}
+Event Token: ${data.eventToken}`,
+                    },
+                ],
+                structuredContent: {
+                    links: data.links,
+                    adminToken: data.adminToken,
+                    eventToken: data.eventToken,
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                structuredContent: { error: message },
+            };
+        }
+    });
+    // Get event tool (no UI needed - just returns data)
+    server.tool("get_event", "Get public details of an event by its event token.", {
+        eventToken: z.string().describe("The event token from the guest URL"),
+    }, async ({ eventToken }) => {
+        try {
+            const res = await fetch(`${YUPNO_API}/api/v1/events/${eventToken}`);
+            const data = (await res.json());
+            if (!res.ok) {
+                return { content: [{ type: "text", text: `Error: ${data.error || "Event not found"}` }] };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text", text: `Error: ${message}` }] };
+        }
+    });
+    // Update event tool with UI support
+    registerAppTool(server, "update_event", {
+        title: "Update Event",
+        description: "Update an existing event. Requires the admin token.",
+        inputSchema: {
+            adminToken: z.string().describe("The admin token for the event"),
+            title: z.string().optional(),
+            eventDate: z.string().optional(),
+            endDate: z.string().optional(),
+            timezone: z.string().optional(),
+            location: z.string().optional(),
+            description: z.string().optional(),
+            rsvpDeadline: z.string().optional().describe("ISO 8601 date/time for RSVP cutoff"),
+            rsvpDeadlineHard: z.boolean().optional().describe("If true, block RSVPs after deadline"),
+            theme: themeSchema,
+            customCss: z.string().optional().describe("Raw CSS to inject into event page"),
+        },
+        _meta: { ui: { resourceUri: EVENT_PREVIEW_RESOURCE } },
+    }, async ({ adminToken, ...updateData }) => {
+        try {
+            const res = await fetch(`${YUPNO_API}/api/v1/events/${adminToken}`, {
+                method: "PUT",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(updateData),
+            });
+            const data = (await res.json());
+            if (!res.ok) {
+                return {
+                    content: [{ type: "text", text: `Error: ${data.error || JSON.stringify(data)}` }],
+                    structuredContent: { success: false, error: data.error },
+                };
+            }
+            return {
+                content: [{ type: "text", text: "Event updated successfully!" }],
+                structuredContent: { success: true },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                structuredContent: { success: false, error: message },
+            };
+        }
+    });
+    // Delete event tool
+    server.tool("delete_event", "Delete an event. Requires the admin token. This action cannot be undone.", {
+        adminToken: z.string().describe("The admin token for the event"),
+    }, async ({ adminToken }) => {
+        try {
+            const res = await fetch(`${YUPNO_API}/api/v1/events/${adminToken}`, {
+                method: "DELETE",
+            });
+            if (!res.ok) {
+                const data = (await res.json());
+                return { content: [{ type: "text", text: `Error: ${data.error || "Failed to delete"}` }] };
+            }
+            return { content: [{ type: "text", text: "Event deleted successfully." }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text", text: `Error: ${message}` }] };
+        }
+    });
+    // Get RSVPs tool
+    server.tool("get_rsvps", "Get the list of RSVPs for an event. Requires both the event token and admin token.", {
+        eventToken: z.string().describe("The event token (16 hex chars from guest URL)"),
+        adminToken: z.string().describe("The admin token for the event"),
+    }, async ({ eventToken, adminToken }) => {
+        try {
+            const res = await fetch(`${YUPNO_API}/api/v1/events/${eventToken}/rsvps`, {
+                headers: {
+                    Authorization: `Bearer ${adminToken}`,
+                },
+            });
+            const data = (await res.json());
+            if (!res.ok) {
+                return { content: [{ type: "text", text: `Error: ${data.error || "Failed to get RSVPs"}` }] };
+            }
+            const { summary, rsvps } = data;
+            let text = `RSVPs Summary:
+- Total responses: ${summary.total}
+- Attending: ${summary.attending}
+- Declined: ${summary.declined}
+- Total guests (with +1s): ${summary.totalGuests}
+- Plus ones: ${summary.plusOnes}
+
+`;
+            if (rsvps.length === 0) {
+                text += "No RSVPs yet.";
+            }
+            else {
+                text += "Guest List:\n";
+                for (const rsvp of rsvps) {
+                    const status = rsvp.attending ? "Yes" : "No";
+                    const plusOne = rsvp.plusOne ? " (+1)" : "";
+                    text += `- ${rsvp.name}${plusOne}: ${status}`;
+                    if (rsvp.email)
+                        text += ` | ${rsvp.email}`;
+                    text += "\n";
+                }
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text", text: `Error: ${message}` }] };
+        }
+    });
+    return server;
+}