MCP Server (NestJS)

English | 中文

A NestJS-based server implementing the Model Context Protocol (MCP). It exposes endpoints for MCP metadata, JSON-RPC tool invocation, prompts, resources, and Swagger docs.

Overview

• MCP metadata: /.well-known/mcp.json
• JSON-RPC tools: POST /rpc
• Prompts: /prompts
• Resources: /resources
• Swagger UI: /docs

Features

• Auto-register tools from src/tools by scanning *.tool.ts / *.tool.js.
  • Object style: default export conforms to ToolDefinition (with name, handler, etc.)
  • Class style: export a class with execute(params).
  • Tool naming priority (class-style): static toolName > class name > filename base.
• Unified return type Promise<unknown>; handler results are wrapped with Promise.resolve(...).
• Global ValidationPipe and DTO for input validation and type safety.
• Swagger auto docs for quick inspection and testing.

Quick Start

pnpm install
pnpm run start:dev

Then visit:

• Swagger: http://localhost:3000/docs
• MCP metadata: http://localhost:3000/.well-known/mcp.json
• JSON-RPC: POST http://localhost:3000/rpc

JSON-RPC Example

Example calling an add tool (tool name may be add-numbers or the class static toolName):

curl -X POST http://localhost:3000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "add-numbers",
    "params": { "a": 1, "b": 2 },
    "id": 1
  }'

If you set a class static name:

export class AddNumbersTool {
  static toolName = 'add number';
  execute(params: { a: number; b: number }) {
    return params.a + params.b;
  }
}

Then call with method "add number".

Add a Tool

Create a *.tool.ts under src/tools using either style:

• Object style:

export default {
  name: 'echo',
  handler: (params: unknown) => Promise.resolve(params),
};

• Class style:

export class WeatherTool {
  static toolName = 'weather';
  execute(params: { city: string }) {
    return { city: params.city, temperature: 26, condition: 'Sunny' };
  }
}

Tools are auto-registered and can be called via /rpc.

Structure (key parts)

• src/main.ts: app bootstrap, global pipes, Swagger
• src/app.module.ts: module wiring
• src/tools/: tools directory (auto register)
• src/rpc/: JSON-RPC controller & DTO
• src/mcp/: MCP metadata controller
• src/prompts/, src/resources/: prompts & resources APIs

Notes

• A global AuthGuard is set as APP_GUARD. Adjust it if you require authentication/authorization.
• Ensure unique tool names to avoid registry overrides.

License

MIT