@nestjs-mcp/server 0.1.0-alpha.4

package/examples/README.md

@@ -0,0 +1,56 @@
+# Examples Directory
+
+This directory contains ready-to-use example MCP servers demonstrating how to use the NestJS MCP Server module and expose different MCP capabilities. Each subfolder is a self-contained NestJS application showing a specific integration pattern.
+
+## Directory Overview
+
+- **mixed/**  
+  Demonstrates how to implement and expose multiple MCP capabilities (resources, tools, and prompts) in a single server. Useful for learning how to combine different features in one service.
+
+- **resources/**  
+  Shows how to define and register MCP resources using the `@Resource` decorator. Resources are used to expose structured data endpoints to LLMs.
+
+- **tools/**  
+  Provides examples of tools implemented with the `@Tool` decorator. Tools allow LLMs to invoke server-side actions or computations, including parameter validation.
+
+- **prompts/**  
+  Contains examples of conversational prompts using the `@Prompt` decorator. Prompts enable dynamic, parameterized conversational flows for LLMs.
+
+- **guards/**  
+  Shows how to implement and use guards in MCP servers to control access to capabilities and resources. Demonstrates different guard patterns and how to apply them to protect specific MCP features.
+
+- **async-import/**  
+  Example of asynchronous module configuration of the MCP module using `forRootAsync` and environment variables.
+
+## How to Run Examples
+
+To run any example, set the EXAMPLE environment variable to the folder name and use:
+
+```sh
+EXAMPLE=<example-folder> pnpm start:example
+```
+
+- Example for the `mixed` example: [mixed/](./mixed/)
+  ```sh
+  EXAMPLE=mixed pnpm start:example
+  ```
+
+> **Windows users:** Use [cross-env](https://www.npmjs.com/package/cross-env):
+>
+> ```sh
+> npx cross-env EXAMPLE=mixed pnpm start:example
+> ```
+
+The server will be available at [http://localhost:3000](http://localhost:3000).
+
+## Inspector Playground
+
+You can interactively test and debug these examples using the MCP Inspector Playground:
+
+```sh
+pnpm start:inspector
+```
+
+---
+
+For more details, see the code and comments in each example folder.

package/examples/async-import/app.module.ts

@@ -0,0 +1,22 @@
+import { Module } from '@nestjs/common';
+
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+import { McpModule } from '../../src/mcp.module';
+
+@Module({
+  imports: [
+    McpModule.forRootAsync({
+      imports: [ConfigModule.forRoot()],
+      useFactory: (configService: ConfigService) => ({
+        name: 'tools',
+        version: '1.0.0',
+        logging: {
+          enabled: configService.get('MCP_LOGGING_ENABLED'),
+          level: configService.get('MCP_LOGGING_LEVEL'),
+        },
+      }),
+    }),
+  ],
+})
+export class AppModule {}

package/examples/async-import/main.ts

@@ -0,0 +1,15 @@
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  try {
+    const app = await NestFactory.create(AppModule);
+    await app.listen(3000);
+    console.log('Async-import example server running on http://localhost:3000');
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+void bootstrap();

package/examples/guards/app.module.ts

@@ -0,0 +1,44 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  Module,
+} from '@nestjs/common';
+
+import { McpModule } from '../../src/mcp.module';
+
+import { APP_GUARD } from '@nestjs/core';
+import { GuardsResolver } from './guards.resolver';
+
+// Global guard (to be registered in app.module.ts)
+@Injectable()
+export class GlobalLogGuard implements CanActivate {
+  canActivate(_context: ExecutionContext): boolean {
+    // This will log for every request (NestJS global guard)
+    // You can add more context-specific logic if needed
+
+    console.log('[GlobalLogGuard] Global guard executed');
+    return true;
+  }
+}
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'tools',
+      version: '1.0.0',
+      logging: {
+        enabled: true,
+        level: 'verbose',
+      },
+    }),
+  ],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: GlobalLogGuard,
+    },
+    GuardsResolver,
+  ],
+})
+export class AppModule {}

package/examples/guards/guards.resolver.ts

@@ -0,0 +1,52 @@
+import { CanActivate } from '@nestjs/common';
+
+import {
+  McpExecutionContext,
+  Prompt,
+  Resolver,
+  Tool,
+  UseGuards,
+} from '../../src';
+
+import {
+  CallToolResult,
+  GetPromptResult,
+} from '@modelcontextprotocol/sdk/types';
+
+// Resolver-level guard
+export class ResolverLogGuard implements CanActivate {
+  canActivate(_context: McpExecutionContext): boolean {
+    console.log('[ResolverLogGuard] Resolver-level guard executed');
+    return true;
+  }
+}
+
+// Method-level guard
+export class MethodLogGuard implements CanActivate {
+  canActivate(_context: McpExecutionContext): boolean {
+    console.log('[MethodLogGuard] Method-level guard executed');
+    return true;
+  }
+}
+
+@UseGuards(ResolverLogGuard)
+@Resolver('guards')
+export class GuardsResolver {
+  @Prompt({ name: 'logPrompt' })
+  logPrompt(): GetPromptResult {
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: { type: 'text', text: 'Prompt executed' },
+        },
+      ],
+    };
+  }
+
+  @UseGuards(MethodLogGuard)
+  @Tool({ name: 'logTool' })
+  logTool(): CallToolResult {
+    return { content: [{ type: 'text', text: 'Tool executed' }] };
+  }
+}

package/examples/guards/main.ts

@@ -0,0 +1,11 @@
+import { NestFactory } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Resources example server running on http://localhost:3000');
+}
+
+void bootstrap();

package/examples/mixed/app.module.ts

@@ -0,0 +1,20 @@
+import { Module } from '@nestjs/common';
+
+import { McpModule } from '../../src/mcp.module';
+
+import { MixedResolver } from './mixed.resolver';
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'tools',
+      version: '1.0.0',
+      logging: {
+        enabled: true,
+        level: 'verbose',
+      },
+    }),
+  ],
+  providers: [MixedResolver],
+})
+export class AppModule {}

package/examples/mixed/main.ts

@@ -0,0 +1,11 @@
+import { NestFactory } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Resources example server running on http://localhost:3000');
+}
+
+void bootstrap();

package/examples/mixed/mixed.resolver.ts

@@ -0,0 +1,56 @@
+import {
+  CallToolResult,
+  GetPromptResult,
+  ReadResourceResult,
+} from '@modelcontextprotocol/sdk/types';
+
+import { Prompt, Resolver, Resource, Tool } from '../../src';
+
+@Resolver('mixed')
+export class MixedResolver {
+  @Resource({
+    name: 'country_list',
+    uri: 'contry://list',
+  })
+  getCountryList(uri: URL): ReadResourceResult {
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: 'Mexico, USA, Canada',
+        },
+      ],
+    };
+  }
+
+  @Tool({
+    name: 'get_country_info',
+  })
+  getCountryInfo(): CallToolResult {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'The capital of France is Paris.',
+        },
+      ],
+    };
+  }
+
+  @Prompt({
+    name: 'get_country_info',
+  })
+  getCountryInfoPrompt(): GetPromptResult {
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: 'What is the capital of France?',
+          },
+        },
+      ],
+    };
+  }
+}

package/examples/prompts/app.module.ts

@@ -0,0 +1,20 @@
+import { Module } from '@nestjs/common';
+
+import { McpModule } from '../../src/mcp.module';
+
+import { PromptsResolver } from './prompts.resolver';
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'tools',
+      version: '1.0.0',
+      logging: {
+        enabled: true,
+        level: 'verbose',
+      },
+    }),
+  ],
+  providers: [PromptsResolver],
+})
+export class AppModule {}

package/examples/prompts/main.ts

@@ -0,0 +1,11 @@
+import { NestFactory } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Resources example server running on http://localhost:3000');
+}
+
+void bootstrap();

package/examples/prompts/prompts.resolver.ts

@@ -0,0 +1,184 @@
+import { GetPromptResult } from '@modelcontextprotocol/sdk/types';
+import { z } from 'zod';
+
+import { Prompt, Resolver } from '../../src';
+
+@Resolver('prompts')
+export class PromptsResolver {
+  /**
+   * Simple prompt with only a name
+   * Use case: Basic functionality that requires no parameters
+   */
+  @Prompt({
+    name: 'greeting',
+  })
+  basicGreeting(): GetPromptResult {
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: 'Hello! How can I assist you today?',
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Prompt with name and argsSchema
+   * Use case: When you need validated input parameters
+   */
+  @Prompt({
+    name: 'personalized_greeting',
+    argsSchema: {
+      name: z.string().min(1),
+      timeOfDay: z.enum(['morning', 'afternoon', 'evening', 'night']),
+    },
+  })
+  personalizedGreeting({
+    name,
+    timeOfDay,
+  }: {
+    name: string;
+    timeOfDay: 'morning' | 'afternoon' | 'evening' | 'night';
+  }): GetPromptResult {
+    const greetings = {
+      morning: 'Good morning',
+      afternoon: 'Good afternoon',
+      evening: 'Good evening',
+      night: 'Good night',
+    };
+
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: `${greetings[timeOfDay]}, ${name}! How can I assist you today?`,
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Prompt with name and description
+   * Use case: When additional context helps the user understand the prompt's purpose
+   */
+  @Prompt({
+    name: 'help_guide',
+    description:
+      'Provides a general help guide about available system features',
+  })
+  helpGuide(): GetPromptResult {
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: `
+              # System Help Guide
+
+              Here are the main features available:
+              - **Account Management**: Update your profile, change settings
+              - **Content Creation**: Create and edit documents, media, and more
+              - **Collaboration**: Share and work with others
+              - **Analytics**: View performance metrics and reports
+
+              For more detailed help, please specify which feature you need assistance with.
+            `,
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Comprehensive prompt with all options
+   * Use case: Complex functionality requiring validated input and clear explanation
+   */
+  @Prompt({
+    name: 'product_recommendation',
+    description:
+      'Recommends products based on user preferences and requirements',
+    argsSchema: {
+      category: z.string(),
+      budget: z.string(),
+      preferences: z.string().optional(),
+    },
+  })
+  productRecommendation({
+    category,
+    budget,
+    preferences,
+  }: {
+    category: string;
+    budget: string;
+    preferences?: string;
+  }): GetPromptResult {
+    // Parse inputs
+    const parsedCategory = category as
+      | 'electronics'
+      | 'clothing'
+      | 'home'
+      | 'beauty';
+    const parsedBudget = parseFloat(budget);
+    const parsedPreferences = preferences
+      ? preferences.split(',').map((p) => p.trim())
+      : undefined;
+
+    // Mock product recommendations based on input parameters
+    const recommendations = {
+      electronics: [
+        { name: 'Wireless Earbuds', price: 79.99 },
+        { name: 'Smart Watch', price: 149.99 },
+        { name: 'Bluetooth Speaker', price: 59.99 },
+      ],
+      clothing: [
+        { name: 'Casual T-Shirt', price: 24.99 },
+        { name: 'Jeans', price: 49.99 },
+        { name: 'Sneakers', price: 89.99 },
+      ],
+      home: [
+        { name: 'Coffee Maker', price: 69.99 },
+        { name: 'Throw Blanket', price: 34.99 },
+        { name: 'Table Lamp', price: 42.99 },
+      ],
+      beauty: [
+        { name: 'Face Serum', price: 29.99 },
+        { name: 'Makeup Palette', price: 54.99 },
+        { name: 'Hair Dryer', price: 99.99 },
+      ],
+    };
+
+    // Filter by budget
+    const affordableProducts = recommendations[parsedCategory].filter(
+      (product) => product.price <= parsedBudget,
+    );
+
+    // Format recommendations
+    const productList = affordableProducts
+      .map((product) => `- ${product.name}: $${product.price.toFixed(2)}`)
+      .join('\n');
+
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: `Based on your ${parsedCategory} category and budget of $${parsedBudget.toFixed(2)}${
+              parsedPreferences
+                ? ` with preferences for ${parsedPreferences.join(', ')}`
+                : ''
+            }, here are my recommendations:\n\n${productList}`,
+          },
+        },
+      ],
+    };
+  }
+}

package/examples/resources/app.module.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+
+import { McpModule } from '../../src/mcp.module';
+import { ResourcesResolver } from './resources.resolver';
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'tools',
+      version: '1.0.0',
+      logging: {
+        enabled: true,
+        level: 'verbose',
+      },
+    }),
+  ],
+  providers: [ResourcesResolver],
+})
+export class AppModule {}

package/examples/resources/main.ts

@@ -0,0 +1,11 @@
+import { NestFactory } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Resources example server running on http://localhost:3000');
+}
+
+void bootstrap();

package/examples/resources/resources.resolver.ts

@@ -0,0 +1,123 @@
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol';
+import {
+  ReadResourceResult,
+  ServerNotification,
+  ServerRequest,
+} from '@modelcontextprotocol/sdk/types';
+
+import { Resolver, Resource } from '../../src';
+
+const USER_LIST = [
+  {
+    id: '1',
+    name: 'John Doe',
+    email: 'john.doe@example.com',
+  },
+  {
+    id: '2',
+    name: 'Jane Smith',
+    email: 'jane.smith@example.com',
+  },
+];
+
+@Resolver('resources')
+export class ResourcesResolver {
+  /**
+   * Simple resource with only a name
+   * Use case: Basic resource without metadata or template
+   */
+  @Resource({
+    name: 'get_users',
+    uri: 'users://list',
+  })
+  getSimpleDocument(
+    uri: URL,
+    _extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+  ): ReadResourceResult {
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify(USER_LIST),
+        },
+      ],
+    };
+  }
+
+  /**
+   * Resource with URI and metadata
+   * Use case: When you need to add contextual information about the resource
+   */
+  @Resource({
+    name: 'get_users_with_filters',
+    uri: 'users://list/metadata',
+    metadata: {},
+  })
+  getUserProfile(uri: URL): ReadResourceResult {
+    const users = USER_LIST.map((user) => ({ id: user.id, name: user.name }));
+
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify(users),
+        },
+      ],
+    };
+  }
+
+  /**
+   * Resource with template
+   * Use case: When you need dynamic parameters in the resource URI
+   */
+  @Resource({
+    name: 'greet',
+    template: 'geet://{name}',
+  })
+  getUserById(
+    uri: URL,
+    variables: {
+      name: string;
+    },
+    _extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+  ): ReadResourceResult {
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: `Hello, ${variables.name}!`,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Resource with template
+   * Use case: When you need dynamic parameters in the resource URI
+   */
+  @Resource({
+    name: 'get_user_by_id',
+    template: 'users://{userId}',
+    metadata: {
+      version: 1,
+    },
+  })
+  getUserByIdWithMetada(
+    uri: URL,
+    variables: {
+      userId: string;
+    },
+    _extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+  ): ReadResourceResult {
+    const user = USER_LIST.find((user) => user.id === variables.userId);
+
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: user ? JSON.stringify(user) : 'User not found',
+        },
+      ],
+    };
+  }
+}

package/examples/tools/app.module.ts

@@ -0,0 +1,20 @@
+import { Module } from '@nestjs/common';
+
+import { McpModule } from '../../src/mcp.module';
+
+import { ToolsResolver } from './tools.resolver';
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'tools',
+      version: '1.0.0',
+      logging: {
+        enabled: true,
+        level: 'verbose',
+      },
+    }),
+  ],
+  providers: [ToolsResolver],
+})
+export class AppModule {}