使用说明

用于实现模型上下文协议服务器的NestJS模块。该模块将MCP协议稳健地集成到NestJS应用程序中，支持服务器发送事件（SSE）进行实时通信和工具执行。

特性

🔄 服务器发送事件（SSE）支持
🛠️ 工具注册和执行
📝 JSON-RPC消息格式
❤️ 心跳机制
✅ Zod模式验证
🚀 与NestJS轻松集成

安装

yarn add @omnihash/nestjs-mcp
# or
npm install @omnihash/nestjs-mcp

用法

1.导入模块

有三种方法可以使用MCP模块：使用装饰器、手动注册或两者兼而有之。

使用装饰品（推荐）

首先，使用装饰器创建工具服务：

// math-tools.service.ts
import { Injectable } from '@nestjs/common';
import { z } from 'zod';
import { McpTool, McpTools } from '@omnihash/nestjs-mcp';

@Injectable()
@McpTools('math')
export class MathToolsService {
  @McpTool({
    name: 'add',
    description: 'Add two numbers',
    schema: z.object({
      a: z.number().describe('First number'),
      b: z.number().describe('Second number'),
    }),
  })
  async add({ a, b }: { a: number; b: number }): Promise<number> {
    return a + b;
  }

  @McpTool({
    name: 'multiply',
    description: 'Multiply two numbers',
    schema: z.object({
      a: z.number().describe('First number'),
      b: z.number().describe('Second number'),
    }),
  })
  async multiply({ a, b }: { a: number; b: number }): Promise<number> {
    return a * b;
  }

  @McpTool({
    name: 'divide',
    description: 'Divide two numbers',
    schema: z.object({
      dividend: z.number().describe('The dividend'),
      divisor: z.number().describe('The divisor'),
    }),
  })
  async divide({
    dividend,
    divisor,
  }: {
    dividend: number;
    divisor: number;
  }): Promise<number> {
    if (divisor === 0) {
      throw new Error('Division by zero is not allowed');
    }
    return dividend / divisor;
  }

  @McpTool({
    name: 'sqrt',
    description: 'Calculate square root',
    schema: z.object({
      n: z.number().min(0).describe('Number to find square root of'),
    }),
  })
  async sqrt({ n }: { n: number }): Promise<number> {
    return Math.sqrt(n);
  }

  @McpTool({
    name: 'power',
    description: 'Calculate power',
    schema: z.object({
      base: z.number().describe('Base number'),
      exponent: z.number().describe('Exponent'),
    }),
  })
  async power({
    base,
    exponent,
  }: {
    base: number;
    exponent: number;
  }): Promise<number> {
    return Math.pow(base, exponent);
  }
}

// string-tools.service.ts
@Injectable()
@McpTools('string')
export class StringToolsService {
  @McpTool({
    name: 'reverse',
    description: 'Reverse a string',
    schema: z.object({
      text: z.string().describe('Text to reverse'),
    }),
  })
  async reverse({ text }: { text: string }): Promise<string> {
    return text.split('').reverse().join('');
  }

  @McpTool({
    name: 'wordCount',
    description: 'Count words in text',
    schema: z.object({
      text: z.string().describe('Text to count words in'),
      includeNumbers: z
        .boolean()
        .default(false)
        .describe('Include numbers in word count'),
    }),
  })
  async wordCount({
    text,
    includeNumbers,
  }: {
    text: string;
    includeNumbers: boolean;
  }): Promise<{
    totalWords: number;
    uniqueWords: number;
    wordFrequency: Record<string, number>;
  }> {
    const words = text.toLowerCase().match(/\b\w+\b/g) || [];
    const filteredWords = includeNumbers
      ? words
      : words.filter((word) => isNaN(Number(word)));

    const frequency: Record<string, number> = {};
    filteredWords.forEach((word) => {
      frequency[word] = (frequency[word] || 0) + 1;
    });

    return {
      totalWords: filteredWords.length,
      uniqueWords: Object.keys(frequency).length,
      wordFrequency: frequency,
    };
  }

  @McpTool({
    name: 'capitalize',
    description: 'Capitalize first letter of each word',
    schema: z.object({
      text: z.string().describe('Text to capitalize'),
    }),
  })
  async capitalize({ text }: { text: string }): Promise<string> {
    return text.replace(/\b\w/g, (char) => char.toUpperCase());
  }

  @McpTool({
    name: 'extractEmails',
    description: 'Extract all email addresses from text',
    schema: z.object({
      text: z.string().describe('Text to search for emails'),
    }),
  })
  async extractEmails({ text }: { text: string }): Promise<string[]> {
    const emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
    return text.match(emailRegex) || [];
  }
}

// Create a module to provide your tools
@Module({
  providers: [MathToolsService, StringToolsService],
  exports: [MathToolsService, StringToolsService],
})
export class ToolsModule {}

然后在你的 app.module.ts:

import { Module } from '@nestjs/common';
import { McpModule } from '@omnihash/nestjs-mcp';
import { ToolsModule } from './tools/tools.module';

@Module({
  imports: [
    McpModule.forRoot({
      name: 'my-mcp-server',
      version: '1.0.0',
      description: 'My MCP Server Implementation',
    }),
    ToolsModule,
  ],
})
export class AppModule {}

手动注册

或者，您可以手动注册工具：

import { Module } from '@nestjs/common';
import { McpModule } from '@omnihash/nestjs-mcp';
import { z } from 'zod';

@Module({
  imports: [
    McpModule.forRootAsync({
      useFactory: () => ({
        name: 'my-mcp-server',
        version: '1.0.0',
        description: 'MCP server with manual tools',
        tools: [
          {
            name: 'greet',
            schema: z.object({
              name: z.string().describe('Name to greet'),
            }),
            handler: async ({ name }) => {
              return `Hello, ${name}!`;
            },
          },
        ],
      }),
    }),
    // Note: You can also register decorator tools alongside your
    // manual registration by importing your ToolsModule
    ToolsModule,
  ],
})
export class AppModule {}

可用端点

导入模块后，以下端点将可用：

GET /sse -建立SSE连接
POST /messages -处理MCP消息
GET /health -健康检查端点
GET /capabilities -返回服务器功能

配置选项

这 McpModule.forRoot() 方法接受以下选项：

interface McpModuleOptions {
  name: string; // Server name
  version: string; // Server version
  description: string; // Server description
  tools: McpTool[]; // Array of tools
}

interface McpTool {
  name: string; // Tool name
  schema: z.ZodObject; // Zod schema for input validation
  handler: (params: any) => Promise<any>; // Tool implementation
}

许可证

麻省理工学院

项目结构示例

src/
  ├── app.module.ts           # Example application module
  ├── main.ts                # Application entry point
  └── tools/                 # Example tool implementations
      ├── api-tools.service.ts
      ├── math-tools.service.ts
      ├── string-tools.service.ts
      └── tools.module.ts

API工具

// api-tools.service.ts
import { Injectable } from '@nestjs/common';
import axios from 'axios';
import { z } from 'zod';
import { McpTool, McpTools } from '@omnihash/nestjs-mcp';

@Injectable()
@McpTools('api')
export class ApiToolsService {
  @McpTool({
    name: 'getTodoList',
    description: 'Get a todo item by ID',
    schema: z.object({
      id: z.string().describe('Todo list ID'),
    }),
  })
  async getTodoList({ id }: { id: string }): Promise<any> {
    const response = await axios.get(
      `https://jsonplaceholder.typicode.com/todos/${id}`,
    );
    return response.data;
  }
}

数学工具（扩展）

@McpTool({
  name: 'divide',
  description: 'Divide two numbers',
  schema: z.object({
    dividend: z.number().describe('The dividend'),
    divisor: z.number().describe('The divisor'),
  }),
})
async divide({
  dividend,
  divisor,
}: {
  dividend: number;
  divisor: number;
}): Promise<number> {
  if (divisor === 0) {
    throw new Error('Division by zero is not allowed');
  }
  return dividend / divisor;
}

@McpTool({
  name: 'sqrt',
  description: 'Calculate square root',
  schema: z.object({
    n: z.number().min(0).describe('Number to find square root of'),
  }),
})
async sqrt({ n }: { n: number }): Promise<number> {
  return Math.sqrt(n);
}

@McpTool({
  name: 'power',
  description: 'Calculate power',
  schema: z.object({
    base: z.number().describe('Base number'),
    exponent: z.number().describe('Exponent'),
  }),
})
async power({
  base,
  exponent,
}: {
  base: number;
  exponent: number;
}): Promise<number> {
  return Math.pow(base, exponent);
}

字符串工具（扩展）

@McpTool({
  name: 'capitalize',
  description: 'Capitalize first letter of each word',
  schema: z.object({
    text: z.string().describe('Text to capitalize'),
  }),
})
async capitalize({ text }: { text: string }): Promise<string> {
  return text.replace(/\b\w/g, (char) => char.toUpperCase());
}

@McpTool({
  name: 'extractEmails',
  description: 'Extract all email addresses from text',
  schema: z.object({
    text: z.string().describe('Text to search for emails'),
  }),
})
async extractEmails({ text }: { text: string }): Promise<string[]> {
  const emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
  return text.match(emailRegex) || [];
}

高级用法

工具发现

该模块自动发现装饰有 @McpTool 在服务装饰 @McpTools。这意味着您可以将工具组织成逻辑组：

@Injectable()
@McpTools('math')      // Tools will be prefixed with 'math/'
export class MathTools {
  @McpTool({
    name: 'add',       // Will be available as 'math/add'
    description: '...',
    schema: z.object({...}),
  })
  async add() {...}
}

@Injectable()
@McpTools('string')    // Tools will be prefixed with 'string/'
export class StringTools {
  @McpTool({
    name: 'reverse',   // Will be available as 'string/reverse'
    description: '...',
    schema: z.object({...}),
  })
  async reverse() {...}
}

错误处理

工具可能会抛出错误，这些错误将在MCP响应中正确格式化：

@McpTool({
  name: 'divide',
  schema: z.object({
    dividend: z.number(),
    divisor: z.number(),
  }),
})
async divide({ dividend, divisor }) {
  if (divisor === 0) {
    throw new Error('Division by zero');  // Will be returned as a JSON-RPC error
  }
  return dividend / divisor;
}

异步配置

您可以使用 forRootAsync 对于动态配置：

@Module({
  imports: [
    McpModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        name: config.get('MCP_SERVER_NAME'),
        version: config.get('MCP_SERVER_VERSION'),
        description: config.get('MCP_SERVER_DESCRIPTION'),
      }),
    }),
  ],
})
export class AppModule {}

自定义工具响应类型

工具可以返回复杂的对象，这些对象将自动转换为MCP内容：

@McpTool({
  name: 'analyze',
  schema: z.object({
    text: z.string(),
  }),
})
async analyze({ text }) {
  return {
    wordCount: text.split(/\s+/).length,
    charCount: text.length,
    sentiment: calculateSentiment(text),
    language: detectLanguage(text),
  };
}

发展

先决条件

Node.js 18或更高版本
npm或纱线

设置

克隆存储库

git clone git@github.com:omnihash/nestjs-mcp.git
cd nestjs-mcp

安装依赖项

nvm use

yarn install

运行示例服务器

yarn start:dev

运行测试

# Unit tests
yarn test

# E2E tests
yarn test:e2e

# Test coverage
yarn test:cov

贡献

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

地方发展

要在另一个项目中本地开发和测试该模块：

链接包：

cd nestjs-mcp
npm link

在您的项目中：

cd your-project
npm link @omnihash/nestjs-mcp

添加到您的项目 package.json:

{
  "dependencies": {
    "@omnihash/nestjs-mcp": "*"
  }
}

NestJS MCP模块

使用说明

特性

安装

用法

1.导入模块

使用装饰品（推荐）

手动注册

可用端点

配置选项

许可证

更多示例

项目结构示例

API工具

数学工具（扩展）

字符串工具（扩展）

高级用法

工具发现

错误处理

异步配置

自定义工具响应类型

发展

先决条件

设置

运行测试

贡献

地方发展

使用说明

特性

安装

用法

1.导入模块

使用装饰品（推荐）

手动注册

可用端点

配置选项

许可证

更多示例

项目结构示例

API工具

数学工具（扩展）

字符串工具（扩展）

高级用法

工具发现

错误处理

异步配置

自定义工具响应类型

发展

先决条件

设置

运行测试

贡献

地方发展

相关 MCP

模型上下文协议服务器

NodeMCU设备管理服务

NestJS MCP服务器模块

大模型HTTP代理服务

工资管理MCP服务器

模型上下文协议服务器