@nestjs-mcp/server 0.1.0-alpha.8 → 0.1.0

package/README.md

@@ -1,7 +1,13 @@
 # MCP Server NestJS Module Library <!-- omit in toc -->
 
-[![NPM Version](https://img.shields.io/npm/v/@your-org/nestjs-mcp-server)](https://www.npmjs.com/package/@nestjs-mcp/server)
+[![NPM Version](https://img.shields.io/npm/v/@nestjs-mcp/server)](https://www.npmjs.com/package/@nestjs-mcp/server)
+[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+[![Downloads](https://img.shields.io/npm/dm/@nestjs-mcp/server)](https://www.npmjs.com/package/@nestjs-mcp/server)
+[![CI Pipeline](https://github.com/adrian-d-hidalgo/nestjs-mcp-server/actions/workflows/run-tests.yml/badge.svg)](https://github.com/adrian-d-hidalgo/nestjs-mcp-server/actions/workflows/run-tests.yml)
+[![codecov](https://codecov.io/gh/adrian-d-hidalgo/nestjs-mcp-server/graph/badge.svg?token=5E228VKY5K)](https://codecov.io/gh/adrian-d-hidalgo/nestjs-mcp-server)
+[![Known Vulnerabilities](https://snyk.io/test/github/adrian-d-hidalgo/nestjs-mcp-server/badge.svg)](https://snyk.io/test/github/adrian-d-hidalgo/nestjs-mcp-server)
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
 ---
 
@@ -24,18 +30,24 @@
   - [Prompt](#prompt)
 - [Module API](#module-api)
   - [forRoot](#mcpmoduleforroot)
+  - [forRootAsync](#mcpmoduleforrootasync)
   - [forFeature](#mcpmoduleforfeature)
-  - [Resolver](#resolver)
+- [Module Usage](#module-usage)
+  - [1. Global Registration with `McpModule.forRoot`](#1-global-registration-with-mcpmoduleforroot)
+  - [2. Feature Module Registration with `McpModule.forFeature`](#2-feature-module-registration-with-mcpmoduleforfeature)
 - [Capabilities](#capabilities)
-  - [@Resolver](#resolver-decorator)
-  - [@Prompt](#prompt-decorator)
-  - [@Resource](#resource-decorator)
-  - [@Tool](#tool-decorator)
+  - [Resolver Decorator](#resolver-decorator)
+  - [Prompt Decorator](#prompt-decorator)
+  - [Resource Decorator](#resource-decorator)
+  - [Tool Decorator](#tool-decorator)
 - [Guards](#guards)
-  - [Global-level guards:](#global-guard-guards)
-  - [Resolver-level guards:](#resolver-level-guards)
-  - [Method-level guards:](#method-level-guards)
+  - [Global-level guards](#global-level-guards)
+  - [Resolver-level guards](#resolver-level-guards)
+  - [Method-level guards](#method-level-guards)
   - [Guard Example](#guard-example)
+  - [MCP Execution Context](#mcp-execution-context)
+- [Session Management](#session-management)
+- [Transport Options](#transport-options)
 - [Inspector Playground](#inspector-playground)
 - [Examples](#examples)
 - [Changelog](#changelog)
@@ -60,14 +72,13 @@ Register the MCP module in your NestJS app and expose a simple tool:
 
 ```ts
 import { Module } from '@nestjs/common';
-import { Injectable } from '@nestjs/common';
 
 import { CallToolResult } from '@modelcontextprotocol/sdk/types';
 
-import { Tool } from '@nestjs-mcp/server';
+import { Resolver, Tool, McpModule } from '@nestjs-mcp/server';
 
-@Injectable()
-export class AppService {
+@Resolver()
+export class HealthResolver {
   /**
    * Simple health check tool
    */
@@ -91,7 +102,7 @@ export class AppService {
       version: '1.0.0',
     }),
   ],
-  providers: [AppService],
+  providers: [HealthResolver],
 })
 export class AppModule {}
 ```
@@ -138,19 +149,31 @@ A Prompt defines a conversational flow, template, or interaction pattern for LLM
 
 ### `McpModule.forRoot`
 
-Registers the MCP Server globally in your NestJS application. Accepts an options object compatible with the MCP Server specification from `@modelcontextprotocol/sdk`.
+Registers the MCP Server globally in your NestJS application.
 
 **Parameters:**
 
-- `options: McpServerOptions` — Main server configuration (name, version, description, etc.)
+- `options: McpModuleOptions` — Main server configuration object:
+  - `name: string`: The name of your MCP server.
+  - `version: string`: The version of your MCP server.
+  - `instructions?: string`: Optional description of the MCP server for the client.
+  - `capabilities?: Record<string, unknown>`: Optional additional capabilities metadata.
+  - `providers?: Provider[]`: Optional array of NestJS providers to include in the module.
+  - `imports?: any[]`: Optional array of NestJS modules to import.
+  - `logging?: McpLoggingOptions`: Optional logging configuration:
+    - `enabled?: boolean` (default: `true`): Enable/disable logging.
+    - `level?: 'error' | 'warn' | 'log' | 'debug' | 'verbose'` (default: `'verbose'`): Set the logging level.
+  - `transports?: McpModuleTransportOptions`: Optional transport configuration (see [Transport Options](#transport-options)).
+  - `protocolOptions?: Record<string, unknown>`: Optional parameters passed directly to the underlying `@modelcontextprotocol/sdk` server instance.
 
 **Returns:**
 
-- A dynamic NestJS module with all MCP providers registered
+- A dynamic NestJS module with all MCP providers registered.
 
 **Example:**
 
 ```ts
+import { Module } from '@nestjs/common';
 import { McpModule } from '@nestjs-mcp/server';
 
 @Module({
@@ -158,6 +181,9 @@ import { McpModule } from '@nestjs-mcp/server';
     McpModule.forRoot({
       name: 'My Server',
       version: '1.0.0',
+      instructions: 'A server providing utility tools and data.',
+      logging: { level: 'log' },
+      transports: { sse: { enabled: false } }, // Disable SSE transport
       // ...other MCP options
     }),
   ],
@@ -165,28 +191,84 @@ import { McpModule } from '@nestjs-mcp/server';
 export class AppModule {}
 ```
 
+### `McpModule.forRootAsync`
+
+Registers the MCP Server globally using asynchronous options, useful for integrating with configuration modules like `@nestjs/config`.
+
+**Parameters:**
+
+- `options: McpModuleAsyncOptions` — Asynchronous configuration object:
+  - `imports?: any[]`: Optional modules to import before the factory runs.
+  - `useFactory: (...args: any[]) => Promise<McpModuleOptions> | McpModuleOptions`: A factory function that returns the `McpModuleOptions`.
+  - `inject?: any[]`: Optional providers to inject into the `useFactory`.
+
+**Returns:**
+
+- A dynamic NestJS module.
+
+**Example (with ConfigModule):**
+
+```ts
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { McpModule } from '@nestjs-mcp/server';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(), // Make sure ConfigModule is imported
+    McpModule.forRootAsync({
+      imports: [ConfigModule], // Import ConfigModule here too
+      useFactory: (configService: ConfigService) => ({
+        name: configService.get<string>('MCP_SERVER_NAME', 'Default Server'),
+        version: configService.get<string>('MCP_SERVER_VERSION', '1.0.0'),
+        instructions: configService.get<string>('MCP_SERVER_DESC'),
+        logging: {
+          level: configService.get('MCP_LOG_LEVEL', 'verbose'),
+        },
+        // ... other options from configService
+      }),
+      inject: [ConfigService], // Inject ConfigService into the factory
+    }),
+  ],
+})
+export class AppModule {}
+```
+
 ### `McpModule.forFeature`
 
-Registers additional MCP resources, tools, or prompts in a feature module. Use this to organize large servers into multiple modules.
+Registers additional MCP resources, tools, or prompts within a feature module. Use this to organize large servers into multiple modules. Resolvers containing MCP capabilities must be included in the `providers` array of the feature module.
 
 **Parameters:**
 
-- `providers: Provider[]` — Array of NestJS providers (resources, tools, prompts)
+- `options?: McpFeatureOptions` (Currently unused, reserved for future enhancements).
 
 **Returns:**
 
-- A dynamic module with the specified providers
+- A dynamic module.
 
 **Example:**
 
 ```ts
+// src/status/status.resolver.ts
+import { Resolver, Tool } from '@nestjs-mcp/server';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types';
+
+@Resolver('status')
+export class StatusResolver {
+  @Tool({ name: 'health_check' })
+  healthCheck(): CallToolResult {
+    return { content: [{ type: 'text', text: 'OK' }] };
+  }
+}
+
+// src/status/status.module.ts
+import { Module } from '@nestjs/common';
 import { McpModule } from '@nestjs-mcp/server';
+import { StatusResolver } from './status.resolver';
 
 @Module({
-  imports: [McpModule.forFeature()],
-  providers: [
-    /*Your Providers with Mcp Capabilities*/
-  ],
+  imports: [McpModule.forFeature()], // Import forFeature here
+  providers: [StatusResolver], // Register your resolver
 })
 export class StatusModule {}
 ```
@@ -236,9 +318,9 @@ import { ToolsResolver } from './tools.resolver';
 export class ToolsModule {}
 ```
 
-- Use `forRoot` only once in your root module.
-- Use `forFeature` as many times as needed in feature modules.
-- All resolvers, tools, and resources must be registered as providers.
+- Use `forRoot` or `forRootAsync` **only once** in your root module (`AppModule`).
+- Use `forFeature` in any feature module where you define MCP capabilities (`@Resolver` classes).
+- Ensure all Resolvers are listed in the `providers` array of their respective modules.
 
 ---
 
@@ -248,27 +330,38 @@ This library provides a set of decorators to define MCP capabilities and apply c
 
 ### Resolver Decorator
 
-A Resolver is a class that groups related MCP capabilities (such as prompts, resources, and tools) and provides a workspace context for them. Use the `@Resolver` decorator to mark a class as a resolver. Dependency injection is supported, and you can apply guards or other cross-cutting concerns at the class level.
+A Resolver is a class that groups related MCP capabilities. **All** MCP capability methods (`@Prompt`, `@Resource`, `@Tool`) **must** belong to a class decorated with `@Resolver`.
+
+- **No `@Injectable()` Needed:** Resolver classes are automatically treated as providers by the MCP module and **do not** require the `@Injectable()` decorator.
+- **Dependency Injection:** Standard NestJS dependency injection works within Resolver constructors.
+- **Namespacing:** You can optionally provide a string argument to `@Resolver('my_namespace')` to namespace the capabilities within that resolver.
+- **Guards:** Guards can be applied at the class level using `@UseGuards()`.
 
 **Example:**
 
 ```ts
 import { Resolver, Prompt, Resource, Tool } from '@nestjs-mcp/server';
+// Import any services you need to inject
+import { SomeService } from '../some.service';
 
-@Resolver('workspace')
+@Resolver('workspace') // No @Injectable()
 export class MyResolver {
-  @Prompt({ name: 'greet' })
-  greetPrompt() {
+  // Inject dependencies as usual
+  constructor(private readonly someService: SomeService) {}
+
+  @Prompt({ name: 'greet_user' }) // Capabilities must be inside a Resolver
+  greetPrompt(/*...args...*/) {
+    const greeting = this.someService.getGreeting();
     /* ... */
   }
 
-  @Resource({ name: 'user', uri: 'user://{id}' })
-  getUserResource() {
+  @Resource({ name: 'user_profile', uri: 'user://{id}' })
+  getUserResource(/*...args...*/) {
     /* ... */
   }
 
-  @Tool({ name: 'sum' })
-  sumTool() {
+  @Tool({ name: 'calculate_sum' })
+  sumTool(/*...args...*/) {
     /* ... */
   }
 }
@@ -280,57 +373,123 @@ You can also apply guards at the resolver level:
 import { UseGuards, Resolver } from '@nestjs-mcp/server';
 import { MyGuard } from './guards/my.guard';
 
-@UseGuards(MyGuard)
-@Resolver('secure')
+@UseGuards(MyGuard) // Applied to all capabilities in this Resolver
+@Resolver('secure') // No @Injectable()
 export class SecureResolver {
-  // ...
+  // All capabilities in this resolver will use MyGuard
 }
 ```
 
 ### Prompt Decorator
 
-Decorate methods within a Resolver to expose them as MCP Prompts.
+Decorate methods within a Resolver class to expose them as MCP Prompts. Accepts options compatible with `server.prompt()` from `@modelcontextprotocol/sdk`. **The `name` should use `snake_case`.**
 
 ```ts
-import { Prompt } from '@nestjs-mcp/server';
-
-@Resolver('workspace')
-export class MyResolver {
-  @Prompt({ name: 'greet' })
-  greetPrompt() {
-    /* ... */
+import { Prompt, Resolver } from '@nestjs-mcp/server';
+import { RequestHandlerExtra } from '@nestjs-mcp/server'; // Import type for extra info
+import { z } from 'zod'; // Example if using Zod schema
+
+// Optional: Define schema if needed
+// const SummaryArgs = z.object({ topic: z.string() });
+
+@Resolver('prompts') // Must be in a Resolver class
+export class MyPrompts {
+  @Prompt({
+    name: 'generate_summary',
+    description: 'Generates a summary for the given text.',
+    // argsSchema: SummaryArgs
+  })
+  generateSummaryPrompt(
+    // params: z.infer<typeof SummaryArgs>, // Arguments based on argsSchema (if defined)
+    extra: RequestHandlerExtra, // Contains sessionId and other metadata
+  ) {
+    console.log(`Generating summary for session: ${extra.sessionId}`);
+    /* ... return CallPromptResult ... */
+    return { content: [{ type: 'text', text: 'Summary generated.' }] };
   }
 }
 ```
 
 ### Resource Decorator
 
-Decorate methods within a Resolver to expose them as MCP Resources.
+Decorate methods within a Resolver class to expose them as MCP Resources. Accepts options compatible with `server.resource()` from `@modelcontextprotocol/sdk`. **The `name` should use `snake_case`.**
 
 ```ts
-import { Resource } from '@nestjs-mcp/server';
+import { Resource, Resolver } from '@nestjs-mcp/server';
+import { RequestHandlerExtra } from '@nestjs-mcp/server'; // Import type for extra info
+import { URL } from 'url'; // Type for URI resource
+import { z } from 'zod'; // Example if using Zod template
+
+// Optional: Define template schema if needed
+// const DocQueryTemplate = z.object({ query: z.string() });
+
+@Resolver('data') // Must be in a Resolver class
+export class MyResources {
+  @Resource({
+    name: 'user_profile',
+    uri: 'user://profiles/{userId}',
+    // metadata: { description: '...' } // Optional
+  })
+  getUserProfile(
+    uri: URL, // First argument is the parsed URI
+    // metadata: Record<string, any> // Second argument if is defined
+    extra: RequestHandlerExtra, // Contains sessionId and other metadata
+  ) {
+    const userId = uri.pathname.split('/').pop(); // Example: Extract ID from URI
+    console.log(`Fetching profile for ${userId}, session: ${extra.sessionId}`);
+    /* ... return CallResourceResult ... */
+    return { content: [{ type: 'text', text: `Profile data for ${userId}` }] };
+  }
 
-@Resolver('workspace')
-export class MyResolver {
-  @Resource({ name: 'user', uri: 'user://{id}' })
-  getUserResource() {
-    /* ... */
+  @Resource({
+    name: 'document_list',
+    template: { type: 'string', description: 'Document content query' }, // Simple template example
+    // metadata: { list: true } // Optional
+  })
+  findDocuments(
+    uri: URL, // First arg based on simple template type
+    variables: Record<string, string>, // Second arg is path params (if any)
+    extra: RequestHandlerExtra, // Contains sessionId and other metadata
+  ) {
+    console.log(
+      `Finding documents matching '${query}', session: ${extra.sessionId}`,
+    );
+    /* ... return CallResourceResult ... */
+    return { content: [{ type: 'text', text: 'List of documents.' }] };
   }
 }
 ```
 
 ### Tool Decorator
 
-Decorate methods within a Resolver to expose them as MCP Tools.
+Decorate methods within a Resolver class to expose them as MCP Tools. Accepts options compatible with `server.tool()` from `@modelcontextprotocol/sdk`. **The `name` should use `snake_case`.**
 
 ```ts
-import { Tool } from '@nestjs-mcp/server';
-
-@Resolver('workspace')
-export class MyResolver {
-  @Tool({ name: 'sum' })
-  sumTool() {
-    /* ... */
+import { Tool, Resolver } from '@nestjs-mcp/server';
+import { RequestHandlerExtra } from '@nestjs-mcp/server'; // Import type for extra info
+import { z } from 'zod'; // Example using Zod for schema
+
+// Example Zod schema for parameters
+const SumParams = z.object({
+  num1: z.number(),
+  num2: z.number(),
+});
+
+@Resolver('utils') // Must be in a Resolver class
+export class MyTools {
+  @Tool({
+    name: 'calculate_sum',
+    description: 'Calculates the sum of two numbers.',
+    paramSchema: SumParams, // Use the Zod schema
+  })
+  sumTool(
+    params: z.infer<typeof SumParams>, // First arg is typed parameters from schema
+    extra: RequestHandlerExtra, // Contains sessionId and other metadata
+  ) {
+    console.log(`Calculating sum for session: ${extra.sessionId}`);
+    const result = params.num1 + params.num2;
+    /* ... return CallToolResult ... */
+    return { content: [{ type: 'text', text: `Result: ${result}` }] };
   }
 }
 ```
@@ -341,20 +500,22 @@ export class MyResolver {
 
 Apply one or more guards to a Resolver, to individual methods, or globally. Guards must implement the NestJS `CanActivate` interface.
 
-### Global-level guards:
+### Global-level guards
 
-This approach uses the standard NestJS global guard system. A global guard will protect all entry points of your MCP server by running before any connection is handled. Use this for authentication, API key checks, or any logic that should apply to every connection.
+This approach uses the standard NestJS global guard system (`APP_GUARD`). A global guard will protect **all** NestJS routes, including the MCP transport endpoints (like `/mcp` or `/sse`). Use this for broad authentication or checks that apply before any MCP-specific logic runs.
 
 ```ts
 // src/guards/global-auth.guard.ts
 import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Request } from 'express';
 
 @Injectable()
 export class GlobalAuthGuard implements CanActivate {
   canActivate(context: ExecutionContext): boolean {
-    // Example: Allow all requests (replace with real logic)
-    // You can access request info via context.switchToHttp().getRequest() if needed
-    return true;
+    const request = context.switchToHttp().getRequest<Request>();
+    const apiKey = request.headers['x-api-key'];
+    // Example: Check for a valid API key
+    return !!apiKey && apiKey === 'EXPECTED_KEY';
   }
 }
 ```
@@ -362,21 +523,15 @@ export class GlobalAuthGuard implements CanActivate {
 Register the guard globally in your main module:
 
 ```ts
+// src/app.module.ts
 import { Module } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
 import { McpModule } from '@nestjs-mcp/server';
 import { GlobalAuthGuard } from './guards/global-auth.guard';
-import { PromptsResolver } from './prompts.resolver';
 
 @Module({
-  imports: [
-    McpModule.forRoot({
-      name: 'My MCP Server',
-      version: '1.0.0',
-    }),
-  ],
+  imports: [McpModule.forRoot(/*...*/)],
   providers: [
-    PromptsResolver,
     {
       provide: APP_GUARD,
       useClass: GlobalAuthGuard,
@@ -386,116 +541,275 @@ import { PromptsResolver } from './prompts.resolver';
 export class AppModule {}
 ```
 
-**Key points:**
-
-- The guard will run for every request handled by your NestJS application, including all MCP endpoints.
-- You can implement any logic in canActivate, such as checking headers, tokens, or user roles.
-- This approach is fully compatible with NestJS and your MCP Server module.
+### Resolver-level guards
 
-### Resolver-level guards:
-
-This is a custom feature of this library. Resolver-level guards are applied using the `@UseGuards` decorator on a Resolver class. All MCP methods (`@Prompt`, `@Resource`, `@Tool`) in the resolver will be protected by these guards. Use this to enforce logic (e.g., role checks) for a specific group of capabilities.
+This is a custom feature of this library. Resolver-level guards are applied using the `@UseGuards()` decorator (exported from `@nestjs-mcp/server`) on a Resolver class. All MCP methods (`@Prompt`, `@Resource`, `@Tool`) **within that specific resolver** will be protected by these guards. Use this to enforce logic (e.g., role checks) for a group of related capabilities.
 
 ```ts
 import { UseGuards, Resolver, Prompt } from '@nestjs-mcp/server';
-import { MyGuard } from './guards/my.guard';
+import { RoleGuard } from './guards/role.guard';
 
-@UseGuards(MyGuard)
-@Resolver('secure')
-export class SecureResolver {
-  @Prompt({ name: 'securePrompt' })
-  securePrompt() {
+@UseGuards(RoleGuard)
+@Resolver('admin')
+export class AdminResolver {
+  @Prompt({ name: 'admin_action' })
+  adminAction(/*...*/) {
     /* ... */
   }
+  // ... other admin capabilities
 }
 ```
 
-### Method-level guards:
+### Method-level guards
 
-This is a custom feature of this library. Method-level guards are applied using the `@UseGuards` decorator directly on a method. Only the decorated MCP method will be protected by these guards. Use this for fine-grained access control on specific capabilities.
+This is a custom feature of this library. Method-level guards are applied using the `@UseGuards()` decorator directly on an MCP capability method (`@Prompt`, `@Resource`, `@Tool`). Only the decorated method will be protected by these guards. Use this for fine-grained access control on specific capabilities.
 
 ```ts
-import { UseGuards, Resolver, Prompt } from '@nestjs-mcp/server';
-import { MyGuard } from './guards/my.guard';
+import { UseGuards, Resolver, Prompt, Tool } from '@nestjs-mcp/server';
+import { SpecificCheckGuard } from './guards/specific-check.guard';
 
 @Resolver('mixed')
 export class MixedResolver {
-  @Prompt({ name: 'publicPrompt' })
+  @Prompt({ name: 'public_prompt' })
   publicPrompt() {
-    /* ... */
+    /* Publicly accessible */
   }
 
-  @UseGuards(MyGuard)
-  @Prompt({ name: 'protectedPrompt' })
-  protectedPrompt() {
-    /* ... */
+  @UseGuards(SpecificCheckGuard)
+  @Tool({ name: 'protected_tool' })
+  protectedTool(/*...*/) {
+    /* Requires SpecificCheckGuard to pass */
   }
 }
 ```
 
+**Important:** Resolver and Method-level guards **only run for MCP capability invocations**, not for the initial connection establishment handled by global guards. They use the custom `McpExecutionContext`.
+
 ### Guard Example
 
+A guard for Resolver or Method-level protection:
+
 ```ts
-import { CanActivate } from '@nestjs/common';
-import { McpExecutionContext } from '@nestjs-mcp/server';
+// src/guards/my-mcp.guard.ts
+import { CanActivate, Injectable } from '@nestjs/common';
+import { McpExecutionContext, SessionManager } from '@nestjs-mcp/server';
+
+@Injectable()
+export class MyMcpGuard implements CanActivate {
+  constructor(private readonly sessionManager: SessionManager) {}
 
-export class MyGuard implements CanActivate {
   canActivate(context: McpExecutionContext): boolean {
-    // Custom logic: allow or deny
+    const sessionId = context.getSessionId();
+    if (!sessionId) return false;
+
+    const handlerArgs = context.getArgs();
+
+    const session = this.sessionManager.getSession(sessionId);
+    const request = session?.request;
+    const userAgent = request?.headers['user-agent'];
+
+    console.log(`Guard activated for session ${sessionId} from ${userAgent}`);
+    console.log('Handler args:', handlerArgs);
+
     return true;
   }
 }
 ```
 
-### Using McpContext in Guards
+### MCP Execution Context
 
-When implementing guards for MCP resolvers and methods, you can use the `McpExecutionContext` interface to access MCP-specific context information. This interface extends the standard NestJS `ExecutionContext` and provides additional properties specific to MCP operations.
+When implementing **Resolver-level** or **Method-level** guards using `@UseGuards()` from this library, your `canActivate` method receives an `McpExecutionContext` instance. This context provides access to MCP-specific information:
 
-```ts
-import { CanActivate } from '@nestjs/common';
-import { McpExecutionContext } from '@nestjs-mcp/server';
-import { Request, Response } from 'express';
+```typescript
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { McpExecutionContext, SessionManager } from '@nestjs-mcp/server';
+import { Request } from 'express';
 
 @Injectable()
 export class McpAuthGuard implements CanActivate {
+  constructor(private readonly sessionManager: SessionManager) {}
+
   canActivate(context: McpExecutionContext): boolean {
-    // Access MCP-specific context
-    const { args, message } = context;
+    const sessionId = context.getSessionId();
+    if (!sessionId) {
+      console.error('Guard Error: MCP Session ID not found in context.');
+      return false;
+    }
+
+    const handlerArgs = context.getArgs<any>();
+    console.log('MCP Handler Arguments:', handlerArgs);
+
+    const session = this.sessionManager.getSession(sessionId);
+    if (!session) {
+      console.error(`Guard Error: Session not found for ID: ${sessionId}`);
+      return false;
+    }
+    const request = session.request as Request;
+
+    const authHeader = request.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      console.log('Guard Denied: Missing or invalid Bearer token.');
+      return false;
+    }
+    const token = authHeader.split(' ')[1];
+    const isValidToken = token === 'VALID_TOKEN';
+
+    if (isValidToken) {
+      console.log(`Guard Passed for session ${sessionId} with token.`);
+      return true;
+    } else {
+      console.log(`Guard Denied: Invalid token for session ${sessionId}.`);
+      return false;
+    }
+  }
+}
+```
+
+**Key points for `McpExecutionContext`:**
+
+- `getSessionId()`: Retrieves the unique ID for the current MCP session. **Crucial** for relating the guard check to the session state stored by `SessionManager`.
+- Arguments (`handlerArgs`): Provides the arguments passed specifically to the MCP handler method (`@Tool`, `@Prompt`, `@Resource`) being invoked. The structure of these arguments depends on the capability type and its definition (e.g., `params` for tools, `query`/`params` for resources). You access these via `context.getArgs()`, but be mindful of the actual structure based on the capability.
+- Request Data: Use the `SessionManager` injected into your guard to fetch the session details (including the original `Request`) based on the `sessionId` obtained from the context.
+- `switchToHttp().getResponse()` / `switchToHttp().getNext()`: These will throw errors as the Response object is not directly available or relevant in this context.
+
+Use `SessionManager` injected into your guard to fetch the session details (including the original `Request`) based on the `sessionId` obtained from the context.
 
-    // Access the current message from the request
-    if (message) {
-      const { req, res } = message;
+---
+
+## Session Management
+
+This library includes a `SessionManager` service responsible for tracking active MCP sessions. Each incoming MCP connection establishes a session, identified by a unique `sessionId`. The `SessionManager` typically stores the associated initial `Request` object for each session.
+
+**Why is it important?**
+
+- **Accessing Request Data:** Since MCP operations (tool calls, prompt executions) might happen independently of the initial HTTP connection (especially with streaming transports like SSE), the `SessionManager` provides a way to retrieve the original `Request` context associated with a specific `sessionId`. This is essential for guards or capability methods (within Resolvers) that need access to request headers, parameters, or other connection-specific details from the original request.
+- **State Management:** While currently focused on storing the request, the `SessionManager` could be extended to store additional session-specific state if needed by your application.
 
-      // Access Express request and response objects
-      const request = req as Request;
-      const response = res as Response;
+**Usage Example (in a Resolver):**
 
-      // Example: Check authorization header
-      const authHeader = request.headers.authorization;
+Resolvers might need access to the original request, for example, to get user information or API keys passed in headers during the initial connection.
 
-      // Implement your authentication logic here
-      // For example, check if the authorization header is valid
+```typescript
+import { Tool, Resolver, SessionManager } from '@nestjs-mcp/server';
+import { RequestHandlerExtra } from '@nestjs-mcp/server'; // Provides sessionId
+import { Request } from 'express';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types';
+import { z } from 'zod';
+
+const UserToolParams = z.object({
+  user_id: z.string().optional(),
+});
+
+@Resolver('user_tools') // No @Injectable() needed
+export class UserToolsResolver {
+  // Inject SessionManager
+  constructor(private readonly sessionManager: SessionManager) {}
+
+  @Tool({
+    name: 'get_user_agent',
+    description:
+      'Gets the user agent from the original request for the session.',
+    paramSchema: UserToolParams,
+  })
+  getUserAgent(
+    params: z.infer<typeof UserToolParams>,
+    extra: RequestHandlerExtra, // Get extra info, including sessionId
+  ): CallToolResult {
+    const sessionId = extra.sessionId;
+    if (!sessionId) {
+      return {
+        content: [{ type: 'text', text: 'Error: Session ID missing.' }],
+      };
+    }
+
+    // Use sessionId to get the session from the manager
+    const session = this.sessionManager.getSession(sessionId);
+    if (!session) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: Session not found for ID: ${sessionId}`,
+          },
+        ],
+      };
     }
 
-    // Access the arguments passed to the MCP method
-    const methodArgs = args;
+    // Access the original request stored in the session
+    const request = session.request as Request;
+    const userAgent = request.headers['user-agent'] || 'Unknown';
 
-    return true; // or false to deny access
+    return {
+      content: [
+        { type: 'text', text: `Session ${sessionId} User Agent: ${userAgent}` },
+      ],
+    };
   }
 }
 ```
 
-**Key properties of McpExecutionContext:**
+In this example:
+
+1. The `@Tool` method receives `extra: RequestHandlerExtra`, which contains the `sessionId`.
+2. The `SessionManager` is injected into the `UserToolsResolver`.
+3. The `sessionId` is used with `sessionManager.getSession()` to retrieve the session data.
+4. The original `request` object is accessed from the retrieved session data.
+
+The `SessionManager` is automatically registered as a provider when you use `McpModule.forRoot` or `McpModule.forRootAsync` and can be injected like any other NestJS provider.
+
+---
+
+## Transport Options
+
+The MCP server can communicate over different transport mechanisms. This library includes built-in support for:
+
+1.  **Streamable (`/mcp` endpoint):** A common transport using standard HTTP POST requests and responses. Suitable for most request/response interactions. Enabled by default.
+2.  **SSE (Server-Sent Events) (`/sse` endpoint):** A transport mechanism allowing the server to push updates to the client over a single HTTP connection. Useful for streaming responses or long-running operations. **Note:** This is considered a legacy transport but remains supported for compatibility. Enabled by default.
+
+You can configure which transports are enabled globally using the `transports` option in `McpModule.forRoot` or `McpModule.forRootAsync`.
+
+**Configuration:**
+
+```typescript
+import { Module } from '@nestjs/common';
+import { McpModule } from '@nestjs-mcp/server';
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'My Server',
+      version: '1.0.0',
+      transports: {
+        streamable: { enabled: true }, // Keep streamable enabled (default)
+        sse: { enabled: false }, // Disable legacy SSE transport
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Default Configuration:**
 
-- `args`: The arguments passed to the MCP method being guarded
-- `message`: The current message from the request, containing:
-  - `req`: The Express Request object
-  - `res`: The Express Response object
-- `getType()`: Returns the type of execution context (always 'mcp' for MCP operations)
-- `getClass()`: Returns the class of the resolver
-- `getArgs()`: Returns the arguments passed to the method
+If the `transports` option is omitted, both `streamable` (`/mcp`) and `sse` (`/sse`) are enabled by default.
 
-This context allows you to implement guards that are aware of the MCP protocol and can make decisions based on MCP-specific information, such as checking request headers, query parameters, or other request data.
+```typescript
+import { Module } from '@nestjs/common';
+import { McpModule } from '@nestjs-mcp/server';
+
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'My Server',
+      version: '1.0.0',
+      // Both streamable and sse will be enabled
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Disabling unused transports can slightly reduce the application's surface area and resource usage.
 
 ---
 
@@ -507,17 +821,19 @@ Use the Inspector Playground to interactively test and debug your MCP server end
 - Invoke endpoints and view responses in real time
 - Validate your server implementation against the MCP specification
 
-To launch the Inspector Playground:
+To launch the Inspector Playground (make sure your NestJS MCP server is running):
 
 ```sh
 npx @modelcontextprotocol/inspector
 ```
 
+It will typically connect to `http://localhost:3000` by default, or you can specify a different target URL.
+
 ---
 
 ## Examples
 
-The [`examples/`](./examples/) directory contains ready-to-use scenarios demonstrating how to register and expose MCP capabilities
+The [`examples/`](./examples/) directory contains ready-to-use scenarios demonstrating how to register and expose MCP capabilities.
 
 Each example is self-contained and follows best practices. For advanced usage, see the code and documentation in each example.