@iludolf/mcp-adapter

NestJS module for Model Context Protocol (MCP) integration. Enables your NestJS application to act as an MCP server, exposing tools, resources, and prompts to AI assistants.

Features

• 🔧 Decorator-based API - Use @McpTool, @McpResource, @McpPrompt decorators
• 🚀 Multiple transports - STDIO, SSE, HTTP support
• 🔄 SSE Keep-alive - Automatic ping to prevent connection timeouts
• 📦 NestJS integration - Full support for dependency injection
• 🔌 Async configuration - Use forRootAsync with ConfigService

Installation

npm install @iludolf/mcp-adapter
# or
pnpm add @iludolf/mcp-adapter
# or  
yarn add @iludolf/mcp-adapter

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install @modelcontextprotocol/sdk@^1.10.0 @nestjs/common @nestjs/core reflect-metadata rxjs zod

Package	Version
@modelcontextprotocol/sdk	^1.10.0
@nestjs/common	^10.0.0 || ^11.0.0
@nestjs/core	^10.0.0 || ^11.0.0
reflect-metadata	^0.1.13 || ^0.2.0
rxjs	^7.0.0
zod	^3.0.0

Quick Start

1. Import the module

import { Module } from "@nestjs/common"
import { McpModule, TransportType } from "@iludolf/mcp-adapter"

@Module({
  imports: [
    McpModule.forRoot({
      serverInfo: {
        name: "my-mcp-server",
        version: "1.0.0",
      },
      transport: TransportType.SSE, // or TransportType.STDIO
    }),
  ],
})
export class AppModule {}

2. Create MCP handlers

import { Injectable } from "@nestjs/common"
import { McpTool, McpResource, McpPrompt } from "@iludolf/mcp-adapter"
import { z } from "zod"

@Injectable()
export class MyMcpHandlers {
  @McpTool({
    name: "calculator",
    description: "Performs basic arithmetic",
    paramsSchema: {
      operation: z.enum(["add", "subtract"]),
      a: z.number(),
      b: z.number(),
    },
  })
  async calculate(args: { operation: string; a: number; b: number }) {
    const result = args.operation === "add" 
      ? args.a + args.b 
      : args.a - args.b
    return { content: [{ type: "text", text: String(result) }] }
  }

  @McpResource({
    name: "config",
    uri: "config://app",
    description: "Application configuration",
  })
  async getConfig() {
    return {
      contents: [{
        uri: "config://app",
        mimeType: "application/json",
        text: JSON.stringify({ version: "1.0.0" }),
      }],
    }
  }

  @McpPrompt({
    name: "greeting",
    description: "Generate a greeting",
    arguments: [{ name: "name", required: true }],
  })
  async generateGreeting(params: { arguments: { name: string } }) {
    return {
      messages: [{
        role: "assistant",
        content: { type: "text", text: `Hello, ${params.arguments.name}!` },
      }],
    }
  }
}

3. Register the handlers provider

@Module({
  imports: [McpModule.forRoot({ /* ... */ })],
  providers: [MyMcpHandlers],
})
export class AppModule {}

Configuration Options

McpModuleOptions

Option	Type	Default	Description
serverInfo	Implementation	required	Server name and version
serverOptions	ServerOptions	-	MCP SDK server options
transport	TransportType	STDIO	Transport type (STDIO, SSE, HTTP, NONE)
logger	McpLogger	DefaultMcpLogger	Custom logger
basePath	string	"mcp"	Base path for HTTP endpoints
global	boolean	false	Register module globally

Async Configuration

McpModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    serverInfo: {
      name: config.get("MCP_NAME"),
      version: config.get("MCP_VERSION"),
    },
    transport: TransportType.SSE,
  }),
  inject: [ConfigService],
})

HTTP Endpoints (SSE/HTTP transport)

When using SSE or HTTP transport, the following endpoints are available:

Endpoint	Method	Description
/{basePath}/sse	GET	SSE connection endpoint
/{basePath}/messages	POST	Message handling endpoint
/{basePath}/health	GET	Health check endpoint

SSE Keep-alive

SSE connections automatically send keep-alive pings every 30 seconds to prevent timeout errors (Body Timeout Error). This is handled transparently - no configuration needed.

Custom Logger

import { McpLogger } from "@iludolf/mcp-adapter"

class MyLogger implements McpLogger {
  info(message: string, context?: string) { /* ... */ }
  warn(message: string, context?: string) { /* ... */ }
  error(message: string, context?: string, trace?: string) { /* ... */ }
  debug(message: string, context?: string) { /* ... */ }
}

McpModule.forRoot({
  serverInfo: { name: "my-server", version: "1.0.0" },
  logger: new MyLogger(),
})

Compatibility

• MCP SDK: Uses the new registerTool, registerPrompt, registerResource API (SDK 1.10.0+)
• NestJS: Compatible with v10 and v11
• Node.js: Requires Node.js 18+

License

MIT