NestJS MCP Server Module

A NestJS module for exposing your services as an MCP (Model Context Protocol) server with Server-Sent Events (SSE) transport. This package simplifies exposing tools that clients can discover and execute via SSE.

Features

• SSE Transport: Built-in /sse endpoint for streaming and /messages for handling tool execution
• Tool Discovery: Automatically discover and register tools using decorators
• Tool Request Validation: Define Zod schemas to validate tool requests.
• Progress Notifications: Send continuous progress updates from tools to clients.

Installation

npm install @rekog/mcp-nest reflect-metadata @modelcontextprotocol/sdk zod

Quick Start

1. Import Module

// app.module.ts
import { Module } from '@nestjs/common';
import { McpModule } from '@rekog/mcp-nest';
import { GreetingTool } from './greeting.tool';

@Module({
  imports: [
    McpModule.forRoot({
      name: 'my-mcp-server',
      version: '1.0.0',
      capabilities: {}
    })
  ],
  providers: [GreetingTool]
})
export class AppModule {}

2. Define Tools

// greeting.tool.ts
import { Injectable } from '@nestjs/common';
import { Tool } from '@rekog/mcp-nest';
import { z } from 'zod';
import { Context } from '@rekog/mcp-nest/dist/services/mcp-tools.discovery';
import { Progress } from "@modelcontextprotocol/sdk/types.js";

@Injectable()
export class GreetingTool {
  constructor() {}

  @Tool({
    name: 'hello-world',
    description: 'Returns a greeting and simulates a long operation with progress updates',
    parameters: z.object({
      name: z.string().default('World'),
    }),
  })
  async sayHello({ name }, context: Context) {

      const greeting = `Hello, ${name}!`;

      const totalSteps = 5;
      for (let i = 0; i < totalSteps; i++) {
        await new Promise((resolve) => setTimeout(resolve, 500));

        // Send a progress update.
        await context.reportProgress({
          progress: (i + 1) * 20,
          total: 100,
        } as Progress);
      }

      return {
        content: [{ type: 'text', text: greeting }]
      };
  }
}

3. Start Server

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

Client Connection

Clients can connect using the MCP SDK:

import { Client } from '@modelcontextprotocol/sdk/client';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse';
import { z } from 'zod';

const client = new Client(
  { name: 'client-name', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(
  new SSEClientTransport(new URL('<http://localhost:3000/sse>'))
);

// Execute the 'hello-world' tool with progress tracking
const greetResult = await client.callTool(
  {
    name: 'hello-world',
    arguments: {
      name: 'MCP User',
    },
  },
  undefined, // responseSchema is optional, or you can define a Zod schema here
  {
    onprogress: (progress) => {
      console.log(
        `Progress: ${progress.progress}/${progress.total}`
      );
    },
  },
);

console.log(greetResult.content[0].text); // Output: Hello MCP User! I'm Test User from Test Org.

API Endpoints

• GET /sse: SSE connection endpoint
• POST /messages: Tool execution endpoint

Configuration Reference

McpOptions

Property	Type	Description	Default Value
name	string	Server name	-
version	string	Server version	-
capabilities	Record<string, any>	Server capabilities, defines what the server can do.	{}
sseEndpoint	string (optional)	Endpoint for SSE connections.	'sse'
messagesEndpoint	string (optional)	Endpoint for handling tool execution.	'messages'
globalApiPrefix	string (optional)	Global API prefix for all endpoints.	''

Tool Decorator

The @Tool decorator is used to define a method as an MCP tool.

@Tool({ name: string, description: string, parameters?: z.ZodObject<any> })

• name: The name of the tool. This will be used to list it in the listTools request.
• description: A description of the tool.
• parameters: (Optional) A Zod schema defining the expected structure of the tool's input arguments.