fastmcp 3.20.1 → 3.21.0

package/src/examples/custom-logger.ts

@@ -1,201 +0,0 @@
-/**
- * Example FastMCP server demonstrating custom logger implementations.
- *
- * Features demonstrated:
- * - Simple custom logger implementation
- * - File-based logging example
- * - Winston logger adapter
- * - Pino logger adapter
- *
- */
-
-import { z } from "zod";
-
-import { FastMCP, Logger } from "../FastMCP.js";
-
-// Example 1: Simple Custom Logger Implementation
-class SimpleCustomLogger implements Logger {
-  debug(...args: unknown[]): void {
-    console.log("[CUSTOM DEBUG]", new Date().toISOString(), ...args);
-  }
-
-  error(...args: unknown[]): void {
-    console.error("[CUSTOM ERROR]", new Date().toISOString(), ...args);
-  }
-
-  info(...args: unknown[]): void {
-    console.info("[CUSTOM INFO]", new Date().toISOString(), ...args);
-  }
-
-  log(...args: unknown[]): void {
-    console.log("[CUSTOM LOG]", new Date().toISOString(), ...args);
-  }
-
-  warn(...args: unknown[]): void {
-    console.warn("[CUSTOM WARN]", new Date().toISOString(), ...args);
-  }
-}
-
-// Example 2: File-based Logger
-// class FileLogger implements Logger {
-//   debug(...args: unknown[]): void {
-//     this.logToFile('DEBUG', ...args);
-//   }
-
-//   error(...args: unknown[]): void {
-//     this.logToFile('ERROR', ...args);
-//   }
-
-//   info(...args: unknown[]): void {
-//     this.logToFile('INFO', ...args);
-//   }
-
-//   log(...args: unknown[]): void {
-//     this.logToFile('LOG', ...args);
-//   }
-
-//   warn(...args: unknown[]): void {
-//     this.logToFile('WARN', ...args);
-//   }
-
-//   private logToFile(level: string, ...args: unknown[]): void {
-//     const timestamp = new Date().toISOString();
-//     const message = `[${timestamp}] [${level}] ${args.map(arg =>
-//       typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
-//     ).join(' ')}\n`;
-
-//     // In a real implementation, you might use fs.appendFile or a logging library
-//     console.log(message.trim());
-//   }
-// }
-
-// Example 3: Winston Logger Adapter
-// To use this example, install winston: npm install winston
-// import winston from 'winston';
-
-// class WinstonLoggerAdapter implements Logger {
-//   private winston: winston.Logger;
-
-//   constructor() {
-//     this.winston = winston.createLogger({
-//       level: 'debug',
-//       format: winston.format.combine(
-//         winston.format.timestamp(),
-//         winston.format.errors({ stack: true }),
-//         winston.format.json()
-//       ),
-//       transports: [
-//         new winston.transports.Console({
-//           format: winston.format.combine(
-//             winston.format.colorize(),
-//             winston.format.simple()
-//           )
-//         }),
-//         new winston.transports.File({ filename: 'fastmcp.log' })
-//       ]
-//     });
-//   }
-
-//   debug(...args: unknown[]): void {
-//     this.winston.debug(this.formatArgs(args));
-//   }
-
-//   error(...args: unknown[]): void {
-//     this.winston.error(this.formatArgs(args));
-//   }
-
-//   info(...args: unknown[]): void {
-//     this.winston.info(this.formatArgs(args));
-//   }
-
-//   log(...args: unknown[]): void {
-//     this.winston.info(this.formatArgs(args));
-//   }
-
-//   warn(...args: unknown[]): void {
-//     this.winston.warn(this.formatArgs(args));
-//   }
-
-//   private formatArgs(args: unknown[]): string {
-//     return args.map(arg =>
-//       typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
-//     ).join(' ');
-//   }
-// }
-
-// Example 4: Pino Logger Adapter
-// To use this example, install pino: npm install pino
-// import pino from 'pino';
-//
-// class PinoLoggerAdapter implements Logger {
-//   private pino: pino.Logger;
-//
-//   constructor() {
-//     this.pino = pino({
-//       level: 'debug',
-//       transport: {
-//         target: 'pino-pretty',
-//         options: {
-//           colorize: true,
-//           translateTime: 'SYS:standard',
-//           ignore: 'pid,hostname'
-//         }
-//       }
-//     });
-//   }
-//
-//   debug(...args: unknown[]): void {
-//     this.pino.debug(this.formatMessage(args));
-//   }
-//
-//   error(...args: unknown[]): void {
-//     this.pino.error(this.formatMessage(args));
-//   }
-//
-//   info(...args: unknown[]): void {
-//     this.pino.info(this.formatMessage(args));
-//   }
-//
-//   log(...args: unknown[]): void {
-//     this.pino.info(this.formatMessage(args));
-//   }
-//
-//   warn(...args: unknown[]): void {
-//     this.pino.warn(this.formatMessage(args));
-//   }
-//
-//   private formatMessage(args: unknown[]): string {
-//     return args.map(arg =>
-//       typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
-//     ).join(' ');
-//   }
-// }
-
-// Choose which logger to use (uncomment the one you want to use)
-const logger = new SimpleCustomLogger();
-// const logger = new FileLogger();
-// const logger = new WinstonLoggerAdapter();
-// const logger = new PinoLoggerAdapter();
-
-const server = new FastMCP({
-  logger: logger,
-  name: "custom-logger-example",
-  version: "1.0.0",
-});
-
-server.addTool({
-  description: "A test tool that demonstrates custom logging",
-  execute: async (args) => {
-    return `Received: ${args.message}`;
-  },
-  name: "test_tool",
-  parameters: z.object({
-    message: z.string().describe("A message to log"),
-  }),
-});
-
-// Start the server with stdio transport
-server.start({ transportType: "stdio" }).catch((error: unknown) => {
-  console.error("Failed to start server:", error);
-  process.exit(1);
-});

package/src/examples/oauth-server.ts

@@ -1,113 +0,0 @@
-/**
- * Example FastMCP server demonstrating OAuth well-known endpoint support.
- *
- * This example shows how to configure FastMCP to serve OAuth discovery endpoints
- * for both authorization server metadata and protected resource metadata.
- *
- * Run with: node dist/examples/oauth-server.js --transport http-stream --port 4111
- * Then visit:
- * - http://localhost:4111/.well-known/oauth-authorization-server
- * - http://localhost:4111/.well-known/oauth-protected-resource
- */
-
-import { FastMCP } from "../FastMCP.js";
-
-const server = new FastMCP({
-  name: "OAuth Example Server",
-  oauth: {
-    authorizationServer: {
-      authorizationEndpoint: "https://auth.example.com/oauth/authorize",
-      codeChallengeMethodsSupported: ["S256"],
-      // DPoP support
-      dpopSigningAlgValuesSupported: ["ES256", "RS256"],
-      grantTypesSupported: ["authorization_code", "refresh_token"],
-
-      introspectionEndpoint: "https://auth.example.com/oauth/introspect",
-      // Required fields
-      issuer: "https://auth.example.com",
-      // Optional fields
-      jwksUri: "https://auth.example.com/.well-known/jwks.json",
-      opPolicyUri: "https://example.com/policy",
-      opTosUri: "https://example.com/terms",
-      registrationEndpoint: "https://auth.example.com/oauth/register",
-      responseModesSupported: ["query", "fragment"],
-      responseTypesSupported: ["code"],
-      revocationEndpoint: "https://auth.example.com/oauth/revoke",
-      scopesSupported: ["read", "write", "admin"],
-      serviceDocumentation: "https://docs.example.com/oauth",
-      tokenEndpoint: "https://auth.example.com/oauth/token",
-      tokenEndpointAuthMethodsSupported: [
-        "client_secret_basic",
-        "client_secret_post",
-      ],
-      tokenEndpointAuthSigningAlgValuesSupported: ["RS256", "ES256"],
-
-      uiLocalesSupported: ["en-US", "es-ES"],
-    },
-    enabled: true,
-    protectedResource: {
-      authorizationDetailsTypesSupported: [
-        "payment_initiation",
-        "account_access",
-      ],
-      authorizationServers: ["https://auth.example.com"],
-      bearerMethodsSupported: ["header"],
-      dpopBoundAccessTokensRequired: false,
-      dpopSigningAlgValuesSupported: ["ES256", "RS256"],
-      jwksUri: "https://oauth-example-server.example.com/.well-known/jwks.json",
-      resource: "mcp://oauth-example-server",
-      resourceDocumentation: "https://docs.example.com/mcp-api",
-      resourceName: "OAuth Example API",
-      resourcePolicyUri: "https://example.com/resource-policy",
-      resourceSigningAlgValuesSupported: ["RS256", "ES256"],
-      resourceTosUri: "https://example.com/terms-of-service",
-      scopesSupported: ["read", "write", "admin"],
-      serviceDocumentation: "https://developer.example.com/api-docs",
-      tlsClientCertificateBoundAccessTokens: false,
-    },
-  },
-  version: "1.0.0",
-});
-
-// Add a simple tool to demonstrate the server functionality
-server.addTool({
-  description: "Get information about this OAuth-enabled MCP server",
-  execute: async () => {
-    return {
-      content: [
-        {
-          text: `This is an OAuth-enabled FastMCP server!
-
-OAuth Discovery Endpoints:
-- Authorization Server: /.well-known/oauth-authorization-server
-- Protected Resource: /.well-known/oauth-protected-resource
-
-The server demonstrates how to configure OAuth metadata for MCP servers
-that need to integrate with OAuth 2.0 authorization flows.`,
-          type: "text",
-        },
-      ],
-    };
-  },
-  name: "get-server-info",
-});
-
-// Start the server
-await server.start({
-  httpStream: { port: 4111 },
-  transportType: "httpStream",
-});
-
-console.log(`
-🚀 OAuth Example Server is running!
-
-Try these endpoints:
-- MCP (HTTP Stream): http://localhost:4111/mcp
-- MCP (SSE): http://localhost:4111/sse
-- Health: http://localhost:4111/health
-- OAuth Authorization Server: http://localhost:4111/.well-known/oauth-authorization-server
-- OAuth Protected Resource: http://localhost:4111/.well-known/oauth-protected-resource
-
-The OAuth endpoints work with both SSE and HTTP Stream transports and return
-JSON metadata following RFC 8414 standards.
-`);

package/src/examples/session-context.ts

@@ -1,269 +0,0 @@
-/**
- * Example demonstrating session context support in FastMCP stdio transport
- *
- * This example demonstrates the fix for issue #144:
- * Session context is now properly passed to tool execution handlers
- * when using stdio transport with an authenticate function.
- *
- * To run this example:
- * npx fastmcp dev src/examples/session-context.ts
- */
-
-import { z } from "zod";
-
-import { FastMCP } from "../FastMCP.js";
-
-interface UserSession {
-  [key: string]: unknown;
-  permissions: string[];
-  role: "admin" | "guest" | "user";
-  userId: string;
-  username: string;
-}
-
-const server = new FastMCP<UserSession>({
-  authenticate: async (request) => {
-    if (!request) {
-      console.log(
-        "[Auth] Authenticating stdio transport using environment variables",
-      );
-
-      const userId = process.env.USER_ID || "default-user";
-      const username = process.env.USERNAME || "Anonymous";
-      const role =
-        (process.env.USER_ROLE as "admin" | "guest" | "user") || "guest";
-      // Mock permissions based on role
-      const permissions =
-        role === "admin"
-          ? ["read", "write", "delete", "admin"]
-          : role === "user"
-            ? ["read", "write"]
-            : ["read"];
-      const session: UserSession = {
-        authenticatedAt: new Date().toISOString(),
-        permissions,
-        role,
-        userId,
-        username,
-      };
-
-      console.log(`[Auth] Authenticated user: ${username} (${role})`);
-
-      return session;
-    }
-
-    // For HTTP transport (request contains headers)
-    console.log("[Auth] Authenticating HTTP transport using headers");
-
-    const authHeader = request.headers["authorization"] as string;
-
-    if (!authHeader || !authHeader.startsWith("Bearer ")) {
-      throw new Response("Missing or invalid authorization header", {
-        status: 401,
-      });
-    }
-
-    const token = authHeader.substring(7);
-
-    // Mock token validation (in real implementation, validate against your auth service)
-    if (token === "admin-token") {
-      return {
-        authenticatedAt: new Date().toISOString(),
-        permissions: ["read", "write", "delete", "admin"],
-        role: "admin" as const,
-        userId: "admin-001",
-        username: "Administrator",
-      };
-    } else if (token === "user-token") {
-      return {
-        authenticatedAt: new Date().toISOString(),
-        permissions: ["read", "write"],
-        role: "user" as const,
-        userId: "user-001",
-        username: "Regular User",
-      };
-    }
-
-    throw new Response("Invalid token", { status: 401 });
-  },
-  name: "Session Context Demo",
-  version: "1.0.0",
-});
-
-// Tool that demonstrates session context access
-server.addTool({
-  description: "Get information about the current authenticated user",
-  execute: async (_args, context) => {
-    if (!context.session)
-      return "No session context available (this shouldn't happen after the fix!)";
-
-    const { session } = context;
-
-    return `✓ Session Context Available!
-    
-User Info:
-- User ID: ${session.userId}
-- Username: ${session.username}  
-- Role: ${session.role}
-- Permissions: ${session.permissions.join(", ")}
-- Authenticated At: ${session.authenticatedAt}`;
-  },
-  name: "whoami",
-});
-
-// Tool that demonstrates role-based access
-server.addTool({
-  description: "Perform an admin-only operation (requires admin role)",
-  execute: async (args, context) => {
-    if (!context.session)
-      return "No session context - cannot verify permissions";
-    if (context.session.role !== "admin")
-      return `Access denied. Current role: ${context.session.role}, required: admin`;
-    if (!context.session.permissions.includes("admin"))
-      return "Insufficient permissions for admin operations";
-
-    return `✓ Admin operation "${args.action}" executed successfully by ${context.session.username}`;
-  },
-  name: "admin-operation",
-  parameters: z.object({
-    action: z.string().describe("The admin action to perform"),
-  }),
-});
-
-// Tool that demonstrates permission checks
-server.addTool({
-  description: "Check what permissions the current user has",
-  execute: async (args, context) => {
-    if (!context.session) return "No session context available";
-
-    const hasPermission = context.session.permissions.includes(args.operation);
-
-    return `Permission Check for "${args.operation}":
-${hasPermission ? "✓ ALLOWED" : "! DENIED"}
-
-Your permissions: ${context.session.permissions.join(", ")}
-Your role: ${context.session.role}`;
-  },
-  name: "check-permissions",
-  parameters: z.object({
-    operation: z.string().describe("Operation to check permission for"),
-  }),
-});
-
-// Resource that uses session context
-server.addResource({
-  description: "Get detailed information about the current authenticated user",
-  load: async (auth) => {
-    if (!auth) {
-      return {
-        text: JSON.stringify(
-          {
-            authenticated: false,
-            error: "No authentication context available",
-          },
-
-          null,
-          2,
-        ),
-      };
-    }
-
-    return {
-      text: JSON.stringify(
-        {
-          authenticated: true,
-          user: {
-            authenticatedAt: auth.authenticatedAt,
-            id: auth.userId,
-            permissions: auth.permissions,
-            role: auth.role,
-            username: auth.username,
-          },
-        },
-
-        null,
-        2,
-      ),
-    };
-  },
-  mimeType: "application/json",
-  name: "Current User Information",
-  uri: "session://current-user",
-});
-
-// Prompt that uses session context
-server.addPrompt({
-  arguments: [
-    {
-      description: "Greeting style (formal, casual, friendly)",
-      name: "style",
-      required: false,
-    },
-  ],
-  description: "Generate a personalized greeting based on the current user",
-  load: async (args, auth) => {
-    const style = args.style || "friendly";
-
-    if (!auth) {
-      return "Hello! I don't have access to your session information.";
-    }
-
-    const greetings = {
-      casual: `Hey ${auth.username}! Nice to see you again.`,
-      formal: `Good day, ${auth.username}. You are logged in with ${auth.role} privileges.`,
-      friendly: `Hello ${auth.username}! 😊 You're logged in as a ${auth.role}. How can I help you today?`,
-    };
-
-    return greetings[style as keyof typeof greetings] || greetings.friendly;
-  },
-  name: "personalized-greeting",
-});
-
-// Start the server
-if (process.argv.includes("--http-stream")) {
-  const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
-
-  server.start({
-    httpStream: { port: PORT },
-    transportType: "httpStream",
-  });
-
-  console.log(`
-🚀 Session Context Demo server running on HTTP Stream!
-
-Try these endpoints:
-- MCP: http://localhost:${PORT}/mcp
-- Health: http://localhost:${PORT}/health
-
-Test with curl:
-curl -H "Authorization: Bearer admin-token" \\
-     -H "Content-Type: application/json" \\
-     -d '{"method":"tools/call","params":{"name":"whoami","arguments":{}}}' \\
-     http://localhost:${PORT}/mcp
-`);
-} else {
-  server.start({ transportType: "stdio" });
-
-  console.log(`
-🚀 Session Context Demo server started with stdio transport!
-
-Environment variables for authentication:
-- USER_ID=${process.env.USER_ID || "(not set - will use 'default-user')"}
-- USERNAME=${process.env.USERNAME || "(not set - will use 'Anonymous')"}  
-- USER_ROLE=${process.env.USER_ROLE || "(not set - will use 'guest')"}
-
-To test with different user roles:
-USER_ID=admin001 USERNAME="John Admin" USER_ROLE=admin npx fastmcp dev src/examples/session-context.ts
-
-Available tools:
-- whoami: Get current user info
-- admin-operation: Test admin permissions  
-- check-permissions: Check specific permissions
-
-Available resources:
-- session://current-user: Current user JSON data
-
-Available prompts:
-- personalized-greeting: Get a personalized greeting
-`);
-}