fastmcp 3.20.1 → 3.21.0

package/src/bin/fastmcp.ts

@@ -1,191 +0,0 @@
-#!/usr/bin/env node
-
-import { execa } from "execa";
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-
-await yargs(hideBin(process.argv))
-  .scriptName("fastmcp")
-  .command(
-    "dev <file>",
-    "Start a development server",
-    (yargs) => {
-      return yargs
-        .positional("file", {
-          demandOption: true,
-          describe: "The path to the server file",
-          type: "string",
-        })
-
-        .option("watch", {
-          alias: "w",
-          default: false,
-          describe: "Watch for file changes and restart server",
-          type: "boolean",
-        })
-
-        .option("verbose", {
-          alias: "v",
-          default: false,
-          describe: "Enable verbose logging",
-          type: "boolean",
-        });
-    },
-
-    async (argv) => {
-      try {
-        const command = argv.watch
-          ? `npx @wong2/mcp-cli npx tsx --watch ${argv.file}`
-          : `npx @wong2/mcp-cli npx tsx ${argv.file}`;
-
-        if (argv.verbose) {
-          console.log(`[FastMCP] Starting server: ${command}`);
-          console.log(`[FastMCP] File: ${argv.file}`);
-          console.log(
-            `[FastMCP] Watch mode: ${argv.watch ? "enabled" : "disabled"}`,
-          );
-        }
-
-        await execa({
-          shell: true,
-          stderr: "inherit",
-          stdin: "inherit",
-          stdout: "inherit",
-        })`${command}`;
-      } catch (error) {
-        console.error(
-          "[FastMCP Error] Failed to start development server:",
-          error instanceof Error ? error.message : String(error),
-        );
-
-        if (argv.verbose && error instanceof Error && error.stack) {
-          console.error("[FastMCP Debug] Stack trace:", error.stack);
-        }
-
-        process.exit(1);
-      }
-    },
-  )
-
-  .command(
-    "inspect <file>",
-    "Inspect a server file",
-    (yargs) => {
-      return yargs.positional("file", {
-        demandOption: true,
-        describe: "The path to the server file",
-        type: "string",
-      });
-    },
-
-    async (argv) => {
-      try {
-        await execa({
-          stderr: "inherit",
-          stdout: "inherit",
-        })`npx @modelcontextprotocol/inspector npx tsx ${argv.file}`;
-      } catch (error) {
-        console.error(
-          "[FastMCP Error] Failed to inspect server:",
-          error instanceof Error ? error.message : String(error),
-        );
-
-        process.exit(1);
-      }
-    },
-  )
-
-  .command(
-    "validate <file>",
-    "Validate a FastMCP server file for syntax and basic structure",
-    (yargs) => {
-      return yargs
-        .positional("file", {
-          demandOption: true,
-          describe: "The path to the server file",
-          type: "string",
-        })
-
-        .option("strict", {
-          alias: "s",
-          default: false,
-          describe: "Enable strict validation (type checking)",
-          type: "boolean",
-        });
-    },
-
-    async (argv) => {
-      try {
-        const { existsSync } = await import("fs");
-        const { resolve } = await import("path");
-        const filePath = resolve(argv.file);
-
-        if (!existsSync(filePath)) {
-          console.error(`[FastMCP Error] File not found: ${filePath}`);
-          process.exit(1);
-        }
-
-        console.log(`[FastMCP] Validating server file: ${filePath}`);
-
-        const command = argv.strict
-          ? `npx tsc --noEmit --strict ${filePath}`
-          : `npx tsc --noEmit ${filePath}`;
-
-        try {
-          await execa({
-            shell: true,
-            stderr: "pipe",
-            stdout: "pipe",
-          })`${command}`;
-
-          console.log("[FastMCP] ✓ TypeScript compilation successful");
-        } catch (tsError) {
-          console.error("[FastMCP] ✗ TypeScript compilation failed");
-
-          if (tsError instanceof Error && "stderr" in tsError) {
-            console.error(tsError.stderr);
-          }
-
-          process.exit(1);
-        }
-
-        try {
-          await execa({
-            shell: true,
-            stderr: "pipe",
-            stdout: "pipe",
-          })`node -e "
-            (async () => {
-              try {
-                const { FastMCP } = await import('fastmcp');
-                await import('file://${filePath}');
-                console.log('[FastMCP] ✓ Server structure validation passed');
-              } catch (error) {
-                console.error('[FastMCP] ✗ Server structure validation failed:', error.message);
-                process.exit(1);
-              }
-            })();
-          "`;
-        } catch {
-          console.error("[FastMCP] ✗ Server structure validation failed");
-          console.error("Make sure the file properly imports and uses FastMCP");
-
-          process.exit(1);
-        }
-
-        console.log(
-          "[FastMCP] ✓ All validations passed! Server file looks good.",
-        );
-      } catch (error) {
-        console.error(
-          "[FastMCP Error] Validation failed:",
-          error instanceof Error ? error.message : String(error),
-        );
-
-        process.exit(1);
-      }
-    },
-  )
-
-  .help()
-  .parseAsync();

package/src/examples/addition.ts

@@ -1,333 +0,0 @@
-/**
- * Example FastMCP server demonstrating core functionality plus streaming output.
- *
- * Features demonstrated:
- * - Basic tool with type-safe parameters
- * - Streaming-enabled tool for incremental output
- * - Advanced tool annotations
- *
- * For a complete project template, see https://github.com/punkpeye/fastmcp-boilerplate
- */
-import { type } from "arktype";
-import * as v from "valibot";
-import { z } from "zod";
-
-import { FastMCP } from "../FastMCP.js";
-
-const server = new FastMCP({
-  name: "Addition",
-  ping: {
-    // enabled: undefined,
-    // Automatically enabled/disabled based on transport type
-    // Using a longer interval to reduce log noise
-    intervalMs: 10000, // default is 5000ms
-    // Reduce log verbosity
-    logLevel: "debug", // default
-  },
-  roots: {
-    // You can explicitly disable roots support if needed
-    // enabled: false,
-  },
-  version: "1.0.0",
-});
-
-// --- Zod Example ---
-const AddParamsZod = z.object({
-  a: z.number().describe("The first number"),
-  b: z.number().describe("The second number"),
-});
-
-server.addTool({
-  annotations: {
-    openWorldHint: false, // This tool doesn't interact with external systems
-    readOnlyHint: true, // This tool doesn't modify anything
-    title: "Addition (Zod)",
-  },
-  description: "Add two numbers (using Zod schema)",
-  execute: async (args) => {
-    // args is typed as { a: number, b: number }
-    console.log(`[Zod] Adding ${args.a} and ${args.b}`);
-    return String(args.a + args.b);
-  },
-  name: "add-zod",
-  parameters: AddParamsZod,
-});
-
-// --- ArkType Example ---
-const AddParamsArkType = type({
-  a: "number",
-  b: "number",
-});
-
-server.addTool({
-  annotations: {
-    destructiveHint: true, // This would perform destructive operations
-    idempotentHint: true, // But operations can be repeated safely
-    openWorldHint: true, // Interacts with external systems
-    readOnlyHint: false, // Example showing a modifying tool
-    title: "Addition (ArkType)",
-  },
-  description: "Add two numbers (using ArkType schema)",
-  execute: async (args, { log }) => {
-    // args is typed as { a: number, b: number } based on AddParamsArkType.infer
-    console.log(`[ArkType] Adding ${args.a} and ${args.b}`);
-
-    // Demonstrate long-running operation that might need a timeout
-    log.info("Starting calculation with potential delay...");
-
-    // Simulate a complex calculation process
-    if (args.a > 1000 || args.b > 1000) {
-      log.warn("Large numbers detected, operation might take longer");
-      // In a real implementation, this delay might be a slow operation
-      await new Promise((resolve) => setTimeout(resolve, 3000));
-    }
-
-    return String(args.a + args.b);
-  },
-  name: "add-arktype",
-  parameters: AddParamsArkType,
-  // Will abort execution after 2s
-  timeoutMs: 2000,
-});
-
-// --- Valibot Example ---
-const AddParamsValibot = v.object({
-  a: v.number("The first number"),
-  b: v.number("The second number"),
-});
-
-server.addTool({
-  annotations: {
-    openWorldHint: false,
-    readOnlyHint: true,
-    title: "Addition (Valibot)",
-  },
-  description: "Add two numbers (using Valibot schema)",
-  execute: async (args) => {
-    console.log(`[Valibot] Adding ${args.a} and ${args.b}`);
-    return String(args.a + args.b);
-  },
-  name: "add-valibot",
-  parameters: AddParamsValibot,
-});
-
-server.addResource({
-  async load() {
-    return {
-      text: "Example log content",
-    };
-  },
-  mimeType: "text/plain",
-  name: "Application Logs",
-  uri: "file:///logs/app.log",
-});
-
-server.addTool({
-  annotations: {
-    openWorldHint: false,
-    readOnlyHint: true,
-    streamingHint: true,
-  },
-  description: "Generate a poem line by line with streaming output",
-  execute: async (args, context) => {
-    const { theme } = args;
-    const lines = [
-      `Poem about ${theme} - line 1`,
-      `Poem about ${theme} - line 2`,
-      `Poem about ${theme} - line 3`,
-      `Poem about ${theme} - line 4`,
-    ];
-
-    for (const line of lines) {
-      await context.streamContent({
-        text: line,
-        type: "text",
-      });
-
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-    }
-
-    return;
-  },
-  name: "stream-poem",
-  parameters: z.object({
-    theme: z.string().describe("Theme for the poem"),
-  }),
-});
-
-server.addTool({
-  annotations: {
-    openWorldHint: false,
-    readOnlyHint: false,
-  },
-  description: "Test progress reporting without buffering delays",
-  execute: async (args, { reportProgress }) => {
-    console.log("Testing progress reporting fix for HTTP Stream buffering...");
-
-    await reportProgress({ progress: 0, total: 100 });
-    await new Promise((resolve) => setTimeout(resolve, 500));
-
-    await reportProgress({ progress: 25, total: 100 });
-    await new Promise((resolve) => setTimeout(resolve, 500));
-
-    await reportProgress({ progress: 75, total: 100 });
-    await new Promise((resolve) => setTimeout(resolve, 500));
-
-    // This progress should be received immediately
-    await reportProgress({ progress: 100, total: 100 });
-
-    return `Buffering test completed for ${args.testCase}`;
-  },
-  name: "test-buffering-fix",
-  parameters: z.object({
-    testCase: z.string().describe("Test case description"),
-  }),
-});
-
-server.addPrompt({
-  arguments: [
-    {
-      description: "Git diff or description of changes",
-      name: "changes",
-      required: true,
-    },
-  ],
-  description: "Generate a Git commit message",
-  load: async (args) => {
-    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
-  },
-  name: "git-commit",
-});
-
-server.addResourceTemplate({
-  arguments: [
-    {
-      description: "Documentation section to retrieve",
-      name: "section",
-      required: true,
-    },
-  ],
-  description: "Get project documentation",
-  load: async (args) => {
-    const docs = {
-      "api-reference":
-        "# API Reference\n\n## Authentication\nAll API requests require a valid API key in the Authorization header.\n\n## Endpoints\n- GET /users - List all users\n- POST /users - Create new user",
-      deployment:
-        "# Deployment Guide\n\nTo deploy this application:\n\n1. Build the project: `npm run build`\n2. Set environment variables\n3. Deploy to your hosting platform",
-      "getting-started":
-        "# Getting Started\n\nWelcome to our project! Follow these steps to set up your development environment:\n\n1. Clone the repository\n2. Install dependencies with `npm install`\n3. Run `npm start` to begin",
-    };
-
-    return {
-      text:
-        docs[args.section as keyof typeof docs] ||
-        "Documentation section not found",
-    };
-  },
-  mimeType: "text/markdown",
-  name: "Project Documentation",
-  uriTemplate: "docs://project/{section}",
-});
-
-server.addTool({
-  annotations: {
-    openWorldHint: false,
-    readOnlyHint: true,
-    title: "Get Documentation (Embedded)",
-  },
-  description:
-    "Retrieve project documentation using embedded resources - demonstrates the new embedded() feature",
-  execute: async (args) => {
-    return {
-      content: [
-        {
-          resource: await server.embedded(`docs://project/${args.section}`),
-          type: "resource",
-        },
-      ],
-    };
-  },
-  name: "get-documentation",
-  parameters: z.object({
-    section: z
-      .enum(["getting-started", "api-reference", "deployment"])
-      .describe("Documentation section to retrieve"),
-  }),
-});
-
-// Select transport type based on command line arguments
-const transportType = process.argv.includes("--http-stream")
-  ? "httpStream"
-  : "stdio";
-
-if (transportType === "httpStream") {
-  // Start with HTTP streaming transport
-  const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;
-
-  server.start({
-    httpStream: {
-      port: PORT,
-    },
-    transportType: "httpStream",
-  });
-
-  console.log(
-    `HTTP Stream MCP server is running at http://localhost:${PORT}/mcp`,
-  );
-  console.log("Use StreamableHTTPClientTransport to connect to this server");
-  console.log("For example:");
-  console.log(`
-  import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-  import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-  
-  const client = new Client(
-    {
-      name: "example-client",
-      version: "1.0.0",
-    },
-    {
-      capabilities: {},
-    },
-  );
-  
-  const transport = new StreamableHTTPClientTransport(
-    new URL("http://localhost:${PORT}/mcp"),
-  );
-  
-  await client.connect(transport);
-  `);
-} else if (process.argv.includes("--explicit-ping-config")) {
-  server.start({
-    transportType: "stdio",
-  });
-
-  console.log(
-    "Started stdio transport with explicit ping configuration from server options",
-  );
-} else if (process.argv.includes("--disable-roots")) {
-  // Example of disabling roots at runtime
-  const serverWithDisabledRoots = new FastMCP({
-    name: "Addition (No Roots)",
-    ping: {
-      intervalMs: 10000,
-      logLevel: "debug",
-    },
-    roots: {
-      enabled: false,
-    },
-    version: "1.0.0",
-  });
-
-  serverWithDisabledRoots.start({
-    transportType: "stdio",
-  });
-
-  console.log("Started stdio transport with roots support disabled");
-} else {
-  // Disable by default for:
-  server.start({
-    transportType: "stdio",
-  });
-
-  console.log("Started stdio transport with ping disabled by default");
-}