### Start the Muppet local development server Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/basic.mdx Once dependencies are installed, run the development command to start a local server. This allows for real-time testing and development of the Muppet application. The command is consistent across different package managers. ```bash npm run dev ``` ```bash yarn dev ``` ```bash pnpm dev ``` ```bash bun run dev ``` -------------------------------- ### Install dependencies for a Muppet project Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/basic.mdx After creating a new Muppet project, navigate into the project directory and install the necessary dependencies. This step prepares the project for development by downloading all required packages. It is compatible with common JavaScript package managers. ```bash cd my-app npm i ``` ```bash cd my-app yarn ``` ```bash cd my-app pnpm i ``` ```bash cd my-app bun i ``` -------------------------------- ### Create a new Muppet application with `create-muppet` Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/basic.mdx Initialize a new Muppet project using the `create-muppet` command. This command scaffolds a starter template into a specified directory, allowing users to choose their preferred transport layer and runtime. It supports various package managers for project setup. ```bash npm create muppet@latest my-app ``` ```bash yarn create muppet my-app ``` ```bash pnpm create muppet@latest my-app ``` ```bash bun create muppet@latest my-app ``` ```bash deno init --npm muppet@latest my-app ``` -------------------------------- ### Initialize Hono Project and Install Dependencies Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This snippet demonstrates how to initialize a new Hono project using pnpm and install necessary dependencies like Muppet, @modelcontextprotocol/sdk, @hono/standard-validator, and Zod for validation. ```bash # Initialize a new hono project, here we are using nodejs but you can use any other template pnpm create hono@latest my-mcp -i -t nodejs -p pnpm # Install dependencies pnpm add muppet @modelcontextprotocol/sdk @hono/standard-validator # You can use any validation lib that supports Standard Schema pnpm add zod ``` -------------------------------- ### Start Muppet Documentation Development Server Source: https://github.com/muppet-dev/muppet/blob/main/CONTRIBUTING.md This command starts the development server for the Muppet documentation. It uses nx to run the 'dev' target for the 'docs' project, making the documentation accessible locally at http://localhost:3000. ```bash pnpm nx dev docs ``` -------------------------------- ### Set up Muppet with Node.js Hono and SSE Transport Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/nodejs.md This code snippet illustrates the setup of a Node.js server using Hono to integrate Muppet with Server-Sent Events (SSE). It defines a GET endpoint to establish the SSE connection and a POST endpoint to handle messages, ensuring the transport is initialized before processing requests. The `serve` function from `@hono/node-server` is used to start the server. ```ts let transport: SSEHonoTransport | null = null; const server = new Hono(); server.get("/sse", (c) => { return streamSSE(c, async (stream) => { transport = new SSEHonoTransport("/messages"); transport.connectWithStream(stream); await bridge({ mcp, transport, }); }); }); server.post("/messages", async (c) => { if (!transport) { throw new Error("Transport not initialized"); } await transport.handlePostMessage(c); return c.text("ok"); }); server.onError((err, c) => { console.error(err); return c.body(err.message, 500); }); serve({ fetch: server.fetch, port: 3000, }); ``` -------------------------------- ### Install Project Dependencies with pnpm Source: https://github.com/muppet-dev/muppet/blob/main/CONTRIBUTING.md This command installs all necessary project dependencies for the Muppet monorepo using pnpm. It should be run after cloning the repository to set up the development environment. ```bash pnpm install ``` -------------------------------- ### TypeScript: Initialize and Run Muppet Server with Stdio Transport Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This TypeScript code demonstrates how to initialize and run a Muppet server application. It configures the server with a name and version, then bridges the Muppet Control Plane (MCP) with a `StdioServerTransport` for communication. This setup allows the Muppet server to interact with clients via standard input/output. ```TypeScript muppet(app, { name: "weather", version: "1.0.0" }).then((mcp) => { if (!mcp) { throw new Error("MCP not initialized"); } // Bridge the mcp with the transport bridge({ mcp, transport: new StdioServerTransport() }); }); ``` -------------------------------- ### Define Static Resource Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/resources/index.mdx This TypeScript example shows how to define a static resource. Unlike dynamic resources, static resources have a fixed URI and do not support completion functions, making them suitable for content that is always available at the same location regardless of LLM input. ```ts // Placeholder for content from ./content/docs/concepts/resources/example-static.ts // Actual TypeScript code for defining a static resource would be here, e.g.: // export const staticResource = { // uri: "muppet:about-us", // // ... other definitions // }; ``` -------------------------------- ### Define Completions for Dynamic Resources Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/resources/index.mdx This TypeScript example illustrates how to provide completions for dynamic resource variables. It allows you to suggest a list of possible values (e.g., cities) to the LLM for a dynamic URI parameter, enhancing LLM guidance and ensuring valid inputs. ```ts // Placeholder for content from ./content/docs/concepts/resources/example-completions.ts // Actual TypeScript code for defining completions would be here, e.g.: // export const dynamicResourceWithCompletions = { // uri: "muppet:forecast/{city}", // completions: async () => ["London", "Paris", "New York"], // // ... other definitions // }; ``` -------------------------------- ### Define a Dynamic Prompt Template in TypeScript Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/prompts/index.mdx This TypeScript example demonstrates how to define a reusable prompt template using `@muppet/core`. It includes variable placeholders, type definitions, and an example of completions and schema validation using Zod, showcasing how prompts can be made dynamic and validated. ```ts // example-prompt.ts import { definePrompt } from '@muppet/core'; export const explainTopicPrompt = definePrompt({ name: 'explainTopic', template: 'Explain {topic} to me like I\'m five.', variables: { topic: { type: 'string', description: 'The topic to explain.', completions: ['AI', 'Quantum Physics', 'Blockchain'] } }, description: 'A simple prompt to explain a topic in an easy-to-understand way.' }); // Another example related to mValidator and completions import { z } from 'zod'; // Assuming zod for Standard Schema export const cityPrompt = definePrompt({ name: 'askCity', template: 'What is the capital of {country}?', variables: { country: { type: 'string', description: 'The country for which to find the capital.', validator: z.string().min(3), // Example of mValidator with Zod completions: ['France', 'Germany', 'Japan'] } }, description: 'Prompt to ask for a country\'s capital, with validation and completions.' }) ``` -------------------------------- ### Setting up Muppet with SSE Transport in Deno using Hono Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/deno.md This code snippet demonstrates how to initialize a Muppet SSEHonoTransport and integrate it with a Deno server built using the Hono web framework. It sets up a GET endpoint for SSE streaming and a POST endpoint for handling incoming messages, ensuring the transport is initialized before message handling. ```ts let transport: SSEHonoTransport | null = null; const server = new Hono(); server.get("/sse", (c) => { return streamSSE(c, async (stream) => { transport = new SSEHonoTransport("/messages"); transport.connectWithStream(stream); await bridge({ mcp, transport, }); }); }); server.post("/messages", async (c) => { if (!transport) { throw new Error("Transport not initialized"); } await transport.handlePostMessage(c); return c.text("ok"); }); server.onError((err, c) => { console.error(err); return c.body(err.message, 500); }); Deno.serve(server.fetch); ``` -------------------------------- ### Bun SSE Proxy Server Setup with Hono Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/bun.md This TypeScript code demonstrates how to set up a proxy server using Hono and Bun to handle Server-Sent Events (SSE) for the Muppet framework. It initializes an SSEHonoTransport, connects it to an SSE stream, and bridges it with the Muppet Control Plane (mcp). It also includes an endpoint to handle incoming messages and an error handler, ensuring the transport is initialized before handling messages. ```TypeScript let transport: SSEHonoTransport | null = null; const server = new Hono(); server.get("/sse", (c) => { return streamSSE(c, async (stream) => { transport = new SSEHonoTransport("/messages"); transport.connectWithStream(stream); await bridge({ mcp, transport, }); }); }); server.post("/messages", async (c) => { if (!transport) { throw new Error("Transport not initialized"); } await transport.handlePostMessage(c); return c.text("ok"); }); server.onError((err, c) => { console.error(err); return c.body(err.message, 500); }); export default server; ``` -------------------------------- ### Define Dynamic Resource URI Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/resources/index.mdx This TypeScript example demonstrates how to define a dynamic resource URI, where parts of the URI, like 'city', are replaced based on LLM input. It shows the structure for creating customizable resource paths that adapt to the LLM's request. ```ts // Placeholder for content from ./content/docs/concepts/resources/example-dynamic.ts // Actual TypeScript code for defining a dynamic resource would be here, e.g.: // export const dynamicResource = { // uri: "muppet:forecast/{city}", // // ... other definitions // }; ``` -------------------------------- ### Define Resource Fetcher Function Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/resources/index.mdx This TypeScript example demonstrates how to define a fetcher function for a resource. The fetcher is responsible for retrieving data based on the resource's URI, supporting asynchronous operations to fetch data from external APIs or databases, and returning it to the LLM. ```ts // Placeholder for content from ./content/docs/concepts/resources/example-fetcher.ts // Actual TypeScript code for defining a fetcher would be here, e.g.: // export const muppetInstance = new Muppet({ // resources: { // "muppet:forecast": async (uri: string) => { // const city = uri.split('/').pop(); // // Fetch data for the city // return { temperature: "25C" }; // } // } // }); ``` -------------------------------- ### Add MCP Server Configuration to Claude for Desktop JSON Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This JSON snippet illustrates how to add an MCP server entry, specifically for a 'weather' server, within the `mcpServers` key of your `claude_desktop_config.json`. This configuration tells Claude for Desktop how to launch the server, making its UI elements visible. Remember to replace the placeholder path with your actual server build path. ```json { "mcpServers": { "weather": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js" ] } } } ``` ```json { "mcpServers": { "weather": { "command": "node", "args": [ "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js" ] } } } ``` -------------------------------- ### Import Core Packages for Hono and Muppet Server Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This snippet shows the essential imports required at the top of `src/index.ts` for setting up the Hono server, Muppet tool bridging, and SDK components, along with Zod for schema validation. ```ts import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { Hono } from 'hono'; import { type ToolResponseType, bridge, describeTool, mValidator, muppet, } from "muppet"; import z from "zod"; ``` -------------------------------- ### Implement Muppet Tool Execution for Weather Alerts and Forecasts Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This snippet demonstrates how to define and implement API endpoints using Hono and Muppet's `describeTool` and `mValidator`. It includes the `get-alerts` tool for fetching weather alerts by state and the beginning of the `get-forecast` tool for retrieving weather forecasts by location. ```ts const app = new Hono(); // Define the get-alerts tool app.post( "/get-alerts", describeTool({ name: "get-alerts", description: "Get weather alerts for a state", }), mValidator( "json", z.object({ state: z .string() .length(2) .describe("Two-letter state code (e.g. CA, NY)"), }), ), async (c) => { const { state } = c.req.valid("json"); const stateCode = state.toUpperCase(); const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`; const alertsData = await makeNWSRequest(alertsUrl); if (!alertsData) { return c.json({ content: [ { type: "text", text: "Failed to retrieve alerts data", }, ], }); } const features = alertsData.features || []; if (features.length === 0) { return c.json({ content: [ { type: "text", text: `No active alerts for ${stateCode}`, }, ], }); } const formattedAlerts = features.map(formatAlert); const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`; return c.json({ content: [ { type: "text", text: alertsText, }, ], }); }, ); app.post( "/get-forecast", describeTool({ name: "get-forecast", description: "Get weather forecast for a location", }), mValidator( "json", z.object({ latitude: z .number() .min(-90) .max(90) ``` -------------------------------- ### JSON: Node.js Build Configuration for Muppet Server Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This JSON snippet provides a `package.json` configuration for building a Node.js-based Muppet server. It defines a `build` script using `esbuild` to bundle, minify, and output the server code to `./build/index.js`. It also lists `esbuild` as a development dependency required for the build process. ```JSON { "scripts": { "build": "esbuild --bundle --minify --platform=node --outfile=./build/index.js ./src/index.ts" }, "dependencies": { "esbuild": "^0.24.2" } } ``` -------------------------------- ### Open Claude for Desktop Configuration File for Editing Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx To begin configuring Claude for Desktop, you need to open its `claude_desktop_config.json` file. This snippet provides commands for opening the file using VS Code on both MacOS/Linux and Windows, ensuring you can modify the server settings. ```bash code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` ```powershell code $env:AppData\Claude\claude_desktop_config.json ``` -------------------------------- ### Build Muppet Documentation for Production Source: https://github.com/muppet-dev/muppet/blob/main/CONTRIBUTING.md This command builds the Muppet documentation for production deployment. It utilizes nx to execute the 'build' target for the 'docs' project, generating static assets suitable for hosting. ```bash pnpm nx build docs ``` -------------------------------- ### Initialize Muppet MCP Instance with TypeScript Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/muppet/index.mdx Demonstrates how to create an MCP (Muppet Control Plane) instance using the `muppet` function. It takes an application instance and a configuration object to set up the server, enabling the core functionality of the Muppet application. ```typescript import { muppet } from '@muppet-dev/muppet'; import { app } from './your-app'; // Your application instance const mcpApp = muppet(app, { name: 'my-mcp-server', version: '1.0.0', // logger: pino(), // Example logger instance // resources: { /* ... */ }, // events: new EventEmitter(), }); export default mcpApp; ``` -------------------------------- ### Define Helper Functions and Interfaces for NWS API Interaction Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This snippet provides helper functions for making requests to the National Weather Service (NWS) API and formatting alert data. It also defines TypeScript interfaces for the structure of NWS API responses, including `AlertFeature`, `AlertsResponse`, `PointsResponse`, and `ForecastResponse`. ```ts const NWS_API_BASE = "https://api.weather.gov"; const USER_AGENT = "weather-app/1.0"; // Helper function for making NWS API requests async function makeNWSRequest(url: string): Promise { const headers = { "User-Agent": USER_AGENT, Accept: "application/geo+json", }; try { const response = await fetch(url, { headers }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return (await response.json()) as T; } catch (error) { console.error("Error making NWS request:", error); return null; } } interface AlertFeature { properties: { event?: string; areaDesc?: string; severity?: string; status?: string; headline?: string; }; } // Format alert data function formatAlert(feature: AlertFeature): string { const props = feature.properties; return [ `Event: ${props.event || "Unknown"}`, `Area: ${props.areaDesc || "Unknown"}`, `Severity: ${props.severity || "Unknown"}`, `Status: ${props.status || "Unknown"}`, `Headline: ${props.headline || "No headline"}`, "---", ].join("\n"); } interface ForecastPeriod { name?: string; temperature?: number; temperatureUnit?: string; windSpeed?: string; windDirection?: string; shortForecast?: string; } interface AlertsResponse { features: AlertFeature[]; } interface PointsResponse { properties: { forecast?: string; }; } interface ForecastResponse { properties: { periods: ForecastPeriod[]; }; } ``` -------------------------------- ### TypeScript: Implement NWS Weather Forecast Tool Logic Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/quickstart/server.mdx This TypeScript code snippet defines the core logic for a weather forecast tool. It uses Zod for input validation of latitude and longitude, then interacts with the National Weather Service (NWS) API to fetch grid point data and subsequent forecast information. The snippet handles various error conditions, such as failed API requests or missing data, and formats the retrieved forecast periods into a human-readable text output. ```TypeScript .describe("Latitude of the location"), longitude: z .number() .min(-180) .max(180) .describe("Longitude of the location"), }), ), async (c) => { const { latitude, longitude } = c.req.valid("json"); // Get grid point data const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`; const pointsData = await makeNWSRequest(pointsUrl); if (!pointsData) { return c.json({ content: [ { type: "text", text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`, } ] }); } const forecastUrl = pointsData.properties?.forecast; if (!forecastUrl) { return c.json({ content: [ { type: "text", text: "Failed to get forecast URL from grid point data" } ] }); } // Get forecast data const forecastData = await makeNWSRequest(forecastUrl); if (!forecastData) { return c.json({ content: [ { type: "text", text: "Failed to retrieve forecast data" } ] }); } const periods = forecastData.properties?.periods || []; if (periods.length === 0) { return c.json({ content: [ { type: "text", text: "No forecast periods available" } ] }); } // Format forecast periods const formattedForecast = periods.map((period: ForecastPeriod) => [ `${period.name || "Unknown"}:`, `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`, `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`, `${period.shortForecast || "No forecast available"}`, "---" ].join("\n") ); const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`; return c.json({ content: [ { type: "text", text: forecastText } ] }); } ); ``` -------------------------------- ### Create LLM Bridge with TypeScript Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/muppet/index.mdx Illustrates how to establish a connection between an LLM (Large Language Model) and the Muppet server using the `bridge` function. It requires the previously created Muppet instance and a specified transport layer to facilitate communication. ```typescript import { bridge } from '@muppet-dev/muppet'; import mcpApp from './example-muppet'; // The Muppet instance created previously import { httpTransport } from '@muppet-dev/transports'; // Example transport layer const llmBridge = bridge(mcpApp, httpTransport); export default llmBridge; ``` -------------------------------- ### Muppet Function Configuration Options Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/muppet/index.mdx Defines the available configuration properties for the `muppet` function's configuration object. These options control the behavior and identification of the MCP server, including its name, version, logging, resources, and event handling. ```APIDOC Configuration Object Properties: name: description: The name of the MCP server. This is used to identify the server by the MCP Client. type: string required: true version: description: The version of the MCP server. This is used to identify the server by the MCP Client. type: string required: true logger: description: A logger instance to use for logging. It uses pino under the hood, so you can use any pino compatible logger. type: number required: false resources: type: Record required: false events: type: Emitter required: false ``` -------------------------------- ### Configure Pino Logger for Muppet Stdio Transport Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/concepts/transports/index.mdx Demonstrates how to configure the built-in `muppet` logger, which uses `pino`, to store logs in a specified file (`muppet.log`) when using the Stdio Transport. This prevents blocking stdio streams for `console.log`. ```ts muppet(app, { logger: pino( pino.destination( "./muppet.log", ), ) }) ``` -------------------------------- ### Cloudflare Worker with Hono and Durable Objects for SSE Transport Source: https://github.com/muppet-dev/muppet/blob/main/docs/content/docs/runtimes/cloudflare-workers.md This code creates a proxy server using Hono to handle SSE connections and messages within a Cloudflare Worker. The `MyDurableObject` class acts as a Durable Object, persisting the transport instance and processing requests via its `fetch` method. Session identification is managed using the `sessionId` query parameter, allowing for either new or existing Durable Object instances. ```ts const server = new Hono<{ Bindings: { transport: SSEHonoTransport } }>(); server.get("/sse", (c) => { return streamSSE(c, async (stream) => { c.env.transport.connectWithStream(stream); await bridge({ mcp, transport: c.env.transport, }); }); }); server.post("/messages", async (c) => { const transport = c.env.transport; if (!transport) { throw new Error("Transport not initialized"); } await transport.handlePostMessage(c); return c.text("ok"); }); server.onError((err, c) => { console.error(err); return c.body(err.message, 500); }); export class MyDurableObject extends DurableObject { transport?: SSEHonoTransport; constructor(ctx: DurableObjectState, env: Env) { super(ctx, env); this.transport = new SSEHonoTransport("/messages", ctx.id.toString()); } async fetch(request: Request) { return server.fetch(request, { ...this.env, transport: this.transport, }); } } export default { async fetch( request: Request, env: { MY_DO: DurableObjectNamespace }, ctx: ExecutionContext, ): Promise { const url = new URL(request.url); const sessionId = url.searchParams.get("sessionId"); const namespace = env.MY_DO; let stub: DurableObjectStub; if (sessionId) stub = namespace.get(namespace.idFromString(sessionId)); else stub = namespace.get(namespace.newUniqueId()); return stub.fetch(request); }, }; ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.