support for custom controllers (#109)

* Adds support for custom controllers
* Adds example using custom controllers with the advanced server 
* Adds support for async configuration
* bump version to 1.8.1

Author: rinormaloku

CLAUDE.md

@@ -5,7 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # NestJS MCP Server Module
 
 ## Project Overview
-This is `@rekog/mcp-nest`, a NestJS module that transforms NestJS applications into Model Context Protocol (MCP) servers. It exposes tools, resources, and prompts for AI consumption via decorators, supporting multiple transport protocols (HTTP+SSE, Streamable HTTP, STDIO).
+This is `@rekog/mcp-nest`, a NestJS module that transforms NestJS applications into Model Context Protocol (MCP) servers. It exposes tools, resources, and prompts for AI consumption via decorators, supporting multiple transport protocols (HTTP+SSE, Streamable HTTP, STDIO) with optional OAuth 2.1 authentication.
 
 ## Essential Development Commands
 
@@ -34,10 +34,51 @@ npx --node-options=--experimental-vm-modules jest tests/mcp-tool.e2e.spec.ts
 npx --node-options=--experimental-vm-modules jest --testNamePattern="auth"
 ```
 
-## Core Architecture Patterns
+## Core Components
 
-### 1. Decorator-Based Registration System
-Tools, resources, and prompts are discovered through decorators using NestJS's reflection capabilities:
+### 1. McpModule - The Primary MCP Server Module
+Located at `src/mcp/mcp.module.ts:18`. This is the main module for creating MCP servers.
+
+**Key Features**:
+- Decorator-based tool/resource/prompt discovery via `McpRegistryService`
+- Multi-transport support (HTTP+SSE, Streamable HTTP, STDIO)
+- Dynamic controller generation for different transport types
+- Module instance isolation with unique `moduleId` per `forRoot()` call
+
+**Basic Usage**:
+```typescript
+McpModule.forRoot({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+  transport: [McpTransportType.SSE, McpTransportType.STREAMABLE_HTTP],
+  guards: [SomeGuard], // Optional authentication
+})
+```
+
+### 2. McpAuthModule - OAuth 2.1 Authorization Server
+Located at `src/authz/mcp-oauth.module.ts:76`. Provides complete OAuth 2.1 compliant Identity Provider implementation.
+
+**Key Features**:
+- Built-in GitHub and Google OAuth providers
+- Multiple storage backends (memory, TypeORM, custom)
+- MCP Authorization specification compliance (2025-06-18)
+- Dynamic client registration (RFC 7591)
+- PKCE support and comprehensive token validation
+
+**Basic Usage**:
+```typescript
+McpAuthModule.forRoot({
+  provider: GitHubOAuthProvider,
+  clientId: process.env.GITHUB_CLIENT_ID!,
+  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+  jwtSecret: process.env.JWT_SECRET!,
+  serverUrl: 'http://localhost:3030',
+  apiPrefix: 'auth',
+})
+```
+
+### 3. Tool Definition Pattern
+Tools are defined using decorators with three-parameter method signature:
 
 ```typescript
 @Injectable()
@@ -56,130 +97,146 @@ export class MyService {
 }
 ```
 
-**Key Pattern**: Method signature is `(args, context, httpRequest)` where:
-- `args`: Zod-validated parameters
+**Method Parameters**:
+- `args`: Zod-validated parameters from tool call
 - `context`: MCP context with `reportProgress`, `mcpServer`, `mcpRequest`, logging
-- `httpRequest`: HTTP request object (undefined for STDIO)
+- `request`: HTTP request object (undefined for STDIO transport)
 
-### 2. Multi-Transport Architecture
-Three transport types with different controllers:
+### 4. Transport Architecture
+Three transport types with dynamic controller creation:
 - **SSE**: `createSseController()` - GET `/sse` + POST `/messages`
 - **Streamable HTTP**: `createStreamableHttpController()` - POST `/mcp` (+ GET/DELETE for stateful)
-- **STDIO**: `StdioService` - No HTTP endpoints
+- **STDIO**: `StdioService` - No HTTP endpoints, uses standard input/output
 
-Each transport creates dynamic controllers via factory functions in `McpModule.forRoot()`.
+Controllers are generated dynamically in `McpModule.forRoot()` based on transport configuration.
+
+### 5. Module Integration Pattern
+Both modules work together for authenticated MCP servers:
 
-### 3. Request Scoping & Dependency Injection
-Uses NestJS's request scoping for per-request instances:
 ```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class RequestScopedService {
-  constructor(@Inject(REQUEST) private request: Request) {}
-}
+@Module({
+  imports: [
+    McpAuthModule.forRoot({ /* OAuth config */ }),
+    McpModule.forRoot({
+      guards: [McpAuthJwtGuard], // Links auth to MCP
+      /* other MCP config */
+    }),
+  ],
+  providers: [McpAuthJwtGuard],
+})
+class AppModule {}
 ```
 
-The `McpExecutorService` (REQUEST-scoped) orchestrates handler registration per request.
+## Documentation Structure
+The project maintains comprehensive documentation in the `docs/` directory:
 
-### 4. Module Instance Isolation
-Each `McpModule.forRoot()` call creates a unique module instance with its own `moduleId`:
-```typescript
-const moduleId = `mcp-module-${instanceIdCounter++}`;
-```
-This enables multiple MCP servers in one application with different endpoints/capabilities.
+### Core Guides
+- `docs/tools.md` - Tool creation, parameters, progress reporting, elicitation
+- `docs/resources.md` - Static and dynamic content serving
+- `docs/resource-templates.md` - Parameterized resource URIs
+- `docs/prompts.md` - Reusable prompt templates
+- `docs/server-examples.md` - Complete server configurations and transport examples
+- `docs/dependency-injection.md` - NestJS DI patterns within MCP context
 
-## Testing Patterns
+### Authorization Documentation
+- `docs/built-in-authorization-server.md` - Complete McpAuthModule usage and configuration
+- `docs/external-authorization-server/README.md` - External OAuth server integration
 
-### E2E Test Structure
-The test suite comprehensively covers all transport types:
-- E2E tests create actual NestJS apps with different transport configurations
-- Tests run the same scenarios across HTTP+SSE, Streamable HTTP (stateful/stateless), and STDIO
-- Use `createSseClient()`, `createStreamableClient()`, `createStdioClient()` helpers
+## Key Implementation Details
 
-### Test File Patterns
-- `*.e2e.spec.ts` - End-to-end integration tests
-- `*.spec.ts` - Unit tests
-- All tests require `--node-options=--experimental-vm-modules` flag
+### Module Instance Isolation
+Each `McpModule.forRoot()` creates isolated instances with unique `moduleId`:
+```typescript
+const moduleId = `mcp-module-${instanceIdCounter++}`;
+```
+This enables multiple MCP servers in one application with different capabilities.
 
-## Critical Implementation Details
+### Request Scoping & Discovery
+- `McpRegistryService` discovers decorated methods at bootstrap using `DiscoveryService`
+- `McpExecutorService` (REQUEST-scoped) handles per-request tool execution
+- Registry maintains maps by `mcpModuleId` for isolation
 
 ### Output Schema Validation
-Tools with `outputSchema` get validated results. Failed validation throws `McpError`:
+Tools with `outputSchema` validate results, throwing `McpError` on failure:
 ```typescript
 if (outputSchema) {
   const validation = outputSchema.safeParse(result);
   if (!validation.success) {
     throw new McpError(ErrorCode.InternalError, `Tool result does not match outputSchema`);
   }
-  return { structuredContent: result, content: this.buildDefaultContentBlock(result) };
 }
 ```
 
-### Resource URI Matching
-Resources use `path-to-regexp` for dynamic URI matching:
+### Resource URI Templates
+Resources use `path-to-regexp` for dynamic URIs:
 - Static: `uri: 'mcp://hello-world'`
 - Template: `uriTemplate: 'mcp://hello-world/{userId}/{userName}'`
 
-Templates extract parameters using `match()` function with URL decoding.
+### OAuth Store Configuration
+McpAuthModule supports multiple storage backends:
+- Memory store (default, testing)
+- TypeORM store (production, with unique connection name to avoid clashes)
+- Custom store implementation via `IOAuthStore` interface
 
-### Authentication Integration
-Guards apply to all MCP endpoints:
-```typescript
-McpModule.forRoot({
-  guards: [AuthGuard], // Applied to SSE/messages/mcp endpoints
-})
-```
-Request context flows through to tools via dependency injection.
+## Testing Patterns
+- E2E tests create actual NestJS apps with different transport configurations
+- Tests run scenarios across HTTP+SSE, Streamable HTTP (stateful/stateless), and STDIO
+- All tests require `--node-options=--experimental-vm-modules` flag
+- Use client helpers: `createSseClient()`, `createStreamableClient()`, `createStdioClient()`
 
-## Project-Specific Conventions
+## Project Structure
 
 ### File Organization
-- `src/mcp/` - Core MCP functionality
-- `src/authz/` - OAuth authentication module  
+- `src/mcp/` - Core MCP functionality (McpModule, transports, services)
+- `src/authz/` - OAuth authentication module (McpAuthModule)
 - `src/mcp/decorators/` - Tool/Resource/Prompt decorators
-- `src/mcp/services/handlers/` - Protocol request handlers
-- `src/mcp/transport/` - Transport implementations
-- `playground/` - Working examples
-- `tests/` - Comprehensive E2E test suite
-
-### Error Handling Patterns
-MCP tools should return standardized error format:
-```typescript
-return {
-  content: [{ type: 'text', text: error.message }],
-  isError: true,
-};
-```
-
-### Registry Service Pattern
-`McpRegistryService` discovers decorated methods at bootstrap using `DiscoveryService` and `MetadataScanner`. It maintains maps by `mcpModuleId` for isolation.
+- `src/mcp/services/handlers/` - MCP protocol request handlers
+- `src/mcp/transport/` - Transport implementations (SSE, Streamable HTTP, STDIO)
+- `src/authz/providers/` - OAuth providers (GitHub, Google, custom interface)
+- `src/authz/stores/` - Storage backends (memory, TypeORM, custom interface)
+- `playground/` - Working examples and demo servers
+- `tests/` - Comprehensive E2E test suite covering all transports
+- `docs/` - Complete documentation for all features
 
 ### HTTP Adapter Abstraction
-`HttpAdapterFactory` provides framework-agnostic request/response handling for Express/Fastify compatibility.
+`HttpAdapterFactory` at `src/mcp/adapters/` provides framework-agnostic request/response handling for Express/Fastify compatibility.
 
-## Key Integration Points
+## Integration Points
 
 ### With NestJS Ecosystem
-- Full DI container integration
-- Guard/Interceptor support
-- Request scoping
-- Module system
-- Versioning compatibility (VERSION_NEUTRAL)
+- Full dependency injection container integration
+- Guard/Interceptor support for authentication
+- Request scoping for per-request instances
+- Module system with dynamic module configuration
+- Compatibility with NestJS versioning (VERSION_NEUTRAL)
 
 ### With MCP SDK
-- Wraps `@modelcontextprotocol/sdk` transports
-- Handles MCP protocol schemas
-- Progress reporting via context
-- Elicitation support for interactive tools
+- Wraps `@modelcontextprotocol/sdk` for transport layer
+- Handles MCP protocol message schemas
+- Progress reporting via context object
+- Elicitation support for interactive tool calls
 
 ### External Dependencies
-- `zod` for parameter validation
-- `path-to-regexp` for URI matching
-- `zod-to-json-schema` for OpenAPI-style schemas
+- `@modelcontextprotocol/sdk` - Core MCP protocol implementation
+- `zod` - Parameter validation and schema definition
+- `path-to-regexp` - Dynamic URI matching for resource templates
+- `zod-to-json-schema` - Schema conversion for tool parameters
+- `passport` + provider strategies - OAuth authentication
+- `@nestjs/jwt` - JWT token management
+- `typeorm` (optional) - Database storage for OAuth data
+
+## Key Architecture Principles
+
+### Transform Pattern
+The module transforms existing NestJS services into MCP servers through decorators, making business logic available to AI systems without modification.
+
+### Transport Agnostic
+Each `McpModule.forRoot()` can serve multiple transport protocols simultaneously, with clients choosing their preferred connection method.
+
+### Security Integration
+Authentication is handled at the transport level via NestJS Guards, ensuring all MCP endpoints respect the same security policies as the rest of the application.
 
-## Important Notes from Copilot Instructions
+### Stateful vs Stateless
+Supports both stateful (session-based) and stateless operation modes, with configurable session ID generation for multi-user scenarios.
 
-- This module transforms NestJS services into MCP servers through decorators, not the other way around
-- The NestJS application hosts the MCP server, making existing business logic available to AI systems
-- Each `McpModule.forRoot()` creates an isolated instance with unique endpoints
-- Authentication uses standard NestJS Guards applied at the transport level
-- Progress reporting is handled through the MCP context object passed to tools
+- don't run linting, I don't care about it or formatting

docs/README.md

@@ -7,6 +7,10 @@
 - [Resources Guide](./resources.md) — Defining and exposing resources.
 - [Dependency Injection](docs/dependency-injection.md) — Leverage NestJS DI system throughout MCP components.
 
+### Advanced Usage
+
+- [Advanced Server Pattern](../playground/servers/advanced/README.md) — Direct service usage with custom controllers for maximum control over interceptors, guards, middleware, and endpoint configuration.
+
 ### OAuth & Authorization
 
 - [Built-in Authorization Server](./built-in-authorization-server.md) — Using the built-in Authorization Server for simpler setups.

docs/server-examples.md

@@ -316,6 +316,52 @@ curl -X POST http://localhost:3030/mcp \
   }'
 ```
 
+## Advanced Server Pattern
+
+For maximum control over your MCP endpoints, you can disable automatic controller generation and use the MCP services directly in custom controllers:
+
+```typescript
+@Module({
+  imports: [
+    McpModule.forRoot({
+      name: 'advanced-server',
+      version: '1.0.0',
+      transport: [], // Disable automatic controllers
+    }),
+  ],
+  controllers: [CustomSseController, CustomStreamableController],
+  providers: [GreetingTool],
+})
+class AppModule {}
+```
+
+And the controller would be similar to:
+
+```typescript
+@Controller()
+export class CustomStreamableController {
+  constructor(private readonly mcpStreamableHttpService: McpStreamableHttpService) {}
+
+  @Post('/mcp')
+  async handlePostRequest(
+    @Req() req: any,
+    @Res() res: any,
+    @Body() body: unknown,
+  ): Promise<void> {
+    await this.mcpStreamableHttpService.handlePostRequest(req, res, body);
+  }
+
+  // additional endpoints ...
+}
+```
+
+This pattern allows you to:
+- Apply custom guards, interceptors, and middleware
+- Define custom endpoint paths and routing
+- Have fine-grained control over request/response handling
+
+**See:** [Advanced Server Pattern Guide](../playground/servers/advanced/README.md) for a full implementation.
+
 ## Example Locations
 
 Complete examples can be found in:
@@ -325,6 +371,7 @@ Complete examples can be found in:
 - `playground/servers/stdio.ts` - STDIO server
 - `playground/servers/server-stateful-fastify.ts` - Fastify server
 - `playground/servers/server-stateful-oauth.ts` - Server with OAuth
+- `playground/servers/advanced/` - Advanced pattern with custom controllers
 
 ## Related
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@rekog/mcp-nest",
-  "version": "1.8.1-alpha.1",
+  "version": "1.8.1",
   "description": "NestJS module for creating Model Context Protocol (MCP) servers",
   "main": "dist/index.js",
   "license": "MIT",