@mcp-weave/nestjs

NestJS-style decorators for building Model Context Protocol (MCP) servers with TypeScript.

Installation

npm install @mcp-weave/nestjs reflect-metadata
# or
pnpm add @mcp-weave/nestjs reflect-metadata

Important: Enable decorators in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Features

• Class Decorators - @McpServer to define MCP servers
• Method Decorators - @McpTool, @McpResource, @McpPrompt
• Parameter Decorators - @McpInput, @McpParam, @McpPromptArg
• Runtime Server - Start MCP servers from decorated classes
• Multiple Transports - Stdio (default) and SSE (Server-Sent Events)

Quick Start

import 'reflect-metadata';
import {
  McpServer,
  McpTool,
  McpResource,
  McpPrompt,
  McpInput,
  McpParam,
  McpPromptArg,
  createMcpServer,
} from '@mcp-weave/nestjs';

@McpServer({
  name: 'my-server',
  version: '1.0.0',
  description: 'My MCP server',
})
class MyServer {
  @McpTool({
    name: 'greet',
    description: 'Greets a user',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Name to greet' },
      },
      required: ['name'],
    },
  })
  greet(@McpInput() input: { name: string }) {
    return `Hello, ${input.name}!`;
  }

  @McpResource({
    uri: 'config://settings',
    name: 'Settings',
    description: 'Application settings',
  })
  getSettings() {
    return {
      contents: [
        {
          uri: 'config://settings',
          mimeType: 'application/json',
          text: JSON.stringify({ theme: 'dark' }),
        },
      ],
    };
  }

  @McpPrompt({
    name: 'welcome',
    description: 'Welcome message prompt',
    arguments: [{ name: 'username', description: 'User name', required: true }],
  })
  welcomePrompt(@McpPromptArg('username') username: string) {
    return {
      messages: [
        {
          role: 'user',
          content: { type: 'text', text: `Welcome ${username} to our service!` },
        },
      ],
    };
  }
}

// Start the server
createMcpServer(MyServer);

Decorators

@McpServer

Marks a class as an MCP server.

@McpServer({
  name: 'server-name',
  version: '1.0.0',
  description: 'Optional description',
})
class MyServer {}

@McpTool

Defines an MCP tool (callable function).

@McpTool({
  name: 'tool_name',
  description: 'What the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string' },
      param2: { type: 'number' },
    },
    required: ['param1'],
  },
})
myTool(@McpInput() input: ToolInput) {
  return result;
}

@McpResource

Defines an MCP resource (readable data).

@McpResource({
  uri: 'resource://path/{id}',
  name: 'Resource Name',
  description: 'Resource description',
  mimeType: 'application/json',
})
getResource(@McpParam('id') id: string) {
  return {
    contents: [{ uri: `resource://path/${id}`, text: 'content' }],
  };
}

@McpPrompt

Defines an MCP prompt template.

@McpPrompt({
  name: 'prompt_name',
  description: 'Prompt description',
  arguments: [
    { name: 'arg1', description: 'Argument 1', required: true },
    { name: 'arg2', description: 'Argument 2', required: false },
  ],
})
myPrompt(
  @McpPromptArg('arg1') arg1: string,
  @McpPromptArg('arg2') arg2?: string
) {
  return {
    messages: [{ role: 'user', content: { type: 'text', text: `...` } }],
  };
}

Parameter Decorators

| Decorator | Use Case | | --------------------- | ---------------------- | | @McpInput() | Tool input object | | @McpParam(name) | Resource URI parameter | | @McpPromptArg(name) | Prompt argument |

Runtime Server

createMcpServer

Creates and starts an MCP server from a decorated class.

import { createMcpServer } from '@mcp-weave/nestjs';

// Starts server on stdio transport
await createMcpServer(MyServer);

McpRuntimeServer

For more control, use the class directly:

import { McpRuntimeServer } from '@mcp-weave/nestjs';

const server = new McpRuntimeServer(MyServer, {
  transport: 'stdio',
});

await server.start();

SSE Transport (Server-Sent Events)

For web-based integrations, use the SSE transport:

import { McpRuntimeServer } from '@mcp-weave/nestjs';

const server = new McpRuntimeServer(MyServer, {
  transport: 'sse',
  port: 3000,
  endpoint: '/sse',
});

// Starts HTTP server with SSE endpoint
const httpServer = await server.start();

// Server available at:
// - SSE endpoint: http://localhost:3000/sse
// - Health check: http://localhost:3000/health

Or use the startSSE method directly:

const server = new McpRuntimeServer(MyServer);

// Start with SSE transport
const httpServer = await server.startSSE({
  port: 8080,
  endpoint: '/mcp',
});

SSE Features:

• CORS enabled by default
• Health check endpoint at /health
• Session management for multiple clients
• Automatic cleanup on connection close

Metadata Extraction

Extract metadata from decorated classes for code generation:

import { extractMetadata, getServerMetadata, getToolsMetadata } from '@mcp-weave/nestjs';

const metadata = extractMetadata(MyServer);
console.log(metadata.server);
console.log(metadata.tools);
console.log(metadata.resources);
console.log(metadata.prompts);

Requirements

• Node.js >= 18
• TypeScript >= 5.0
• reflect-metadata package

Related Packages

• @mcp-weave/core - Core types and utilities
• @mcp-weave/testing - Testing utilities
• @mcp-weave/cli - Command-line interface

License

MIT