MCP Lambda SDK 到 NodeJs

一个用于创建运行在 AWS Lambda 上的模型上下文协议（MCP）服务器的 TypeScript SDK，使用装饰器实现。

概述

MCP Lambda SDK 到 NodeJs 提供了一种简单的方法，通过装饰器来创建作为 AWS Lambda 函数运行的 MCP 服务器。只需几个装饰器，您就可以将您的 Lambda 函数暴露为 MCP 工具，这些工具可以被遵循 Model Context Protocol 规范的 AI 系统调用。

安装

npm install mcp-lambda-nodejs

快速开始

1. 创建 MCP 服务器类

import { MCPServer, MCPTool, z } from 'mcp-lambda-nodejs';

@MCPServer({
  name: 'my-calculator-server',
  version: '1.0.0'
})
export class CalculatorServer {
  @MCPTool({
    title: '加法',
    description: '将两个数字相加',
    inputSchema: {
      a: z.number().describe('第一个数字'),
      b: z.number().describe('第二个数字')
    },
    outputSchema: {
      result: z.number().describe('两个数字之和'),
      operation: z.string().describe('操作描述')
    }
  })
  async add(params: { a: number; b: number }) {
    return {
      result: params.a + params.b,
      operation: `计算了 ${params.a} + ${params.b}`
    };
  }

  @MCPTool({
    title: '乘法',
    description: '将两个数字相乘',
    inputSchema: {
      a: z.number().describe('第一个数字'),
      b: z.number().describe('第二个数字')
    },
    outputSchema: {
      result: z.number().describe('两个数字的乘积')
    }
  })
  async multiply(params: { a: number; b: number }) {
    return {
      result: params.a * params.b
    };
  }
}

2. 创建 Lambda 处理程序

import { MCPHandlerFactory, APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'mcp-lambda-nodejs';
import { CalculatorServer } from './calculator-server';

// 使用工厂创建处理程序
export const calculatorHandler = MCPHandlerFactory.createHandler(CalculatorServer, 'calculator');

// 导出无服务器框架的主要函数
export async function main(event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> {
  return await calculatorHandler(event);
}

3. 部署到 AWS Lambda

配置您的 serverless.yml（或首选部署方法）：

service: my-mcp-server

provider:
  name: aws
  runtime: nodejs18.x

functions:
  calculator:
    handler: dist/calculator-handler.main
    events:
      - httpApi:
          path: /calculator
          method: post
      - httpApi:
          path: /calculator
          method: options

API 参考

装饰器

@MCPServer(config)

标记一个类为 MCP 服务器。

参数：

• config.name: 服务器名称标识符
• config.version: 服务器版本

@MCPTool(config)

标记一个方法为 MCP 工具。

参数：

• config.title: 易于阅读的工具标题
• config.description: 工具描述
• config.inputSchema: 输入验证的 Zod 模式对象
• config.outputSchema: 输出验证的 Zod 模式对象

工厂方法

MCPHandlerFactory.createHandler(ServerClass, serverName?)

为 MCP 服务器类创建一个 Lambda 处理程序函数。

参数：

• ServerClass: 被装饰的 MCP 服务器类
• serverName: 可选的服务器实例名称

返回值： AWS Lambda 处理程序函数

会话管理

SDK 包含内置的会话管理，以维护来自同一客户端会话的多个工具调用之间的状态。

import { MCPSessionManager } from 'mcp-lambda-nodejs';

@MCPServer({
  name: 'stateful-server',
  version: '1.0.0'
})
export class StatefulServer {
  private sessionManager = new MCPSessionManager();

  @MCPTool({
    title: '存储值',
    description: '在会话中存储一个值',
    inputSchema: {
      key: z.string(),
      value: z.string(),
      sessionId: z.string().optional()
    },
    outputSchema: {
      success: z.boolean()
    }
  })
  async storeValue(params: { key: string; value: string; sessionId?: string }) {
    if (params.sessionId) {
      await this.sessionManager.updateSessionState(params.sessionId, {
        [params.key]: params.value
      });
    }
    return { success: true };
  }
}

高级特性

自定义验证

您可以使用任何 Zod 模式进行输入和输出验证：

@MCPTool({
  title: '处理用户',
  description: '处理用户数据',
  inputSchema: {
    user: z.object({
      name: z.string().min(1),
      email: z.string().email(),
      age: z.number().int().min(0).max(120)
    })
  },
  outputSchema: {
    processed: z.boolean(),
    userId: z.string().uuid()
  }
})
async processUser(params: { user: { name: string; email: string; age: number } }) {
  // 在这里处理用户逻辑
  return {
    processed: true,
    userId: crypto.randomUUID()
  };
}

错误处理

SDK 自动处理错误并以正确的 MCP 格式返回它们：

@MCPTool({
  title: '除法',
  description: '将两个数字相除',
  inputSchema: {
    dividend: z.number(),
    divisor: z.number()
  },
  outputSchema: {
    result: z.number()
  }
})
async divide(params: { dividend: number; divisor: number }) {
  if (params.divisor === 0) {
    throw new Error('不允许除以零');
  }
  return {
    result: params.dividend / params.divisor
  };
}

示例

查看 /examples 目录中的完整工作示例：

• 计算器服务器：基本算术运算
• 数据处理服务器：高级数据操作工具

要求

• Node.js 18+
• TypeScript 5.0+
• AWS Lambda（用于部署）

依赖项

• @modelcontextprotocol/sdk: MCP 协议实现
• zod: 模式验证
• reflect-metadata: 装饰器元数据支持
• uuid: 会话ID生成

许可证

MIT

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

支持

• 在 GitHub 上创建问题报告错误
• 查看示例了解使用模式
• 在 modelcontextprotocol.io 查阅 MCP 规范

使用

部署

要部署示例，您需要运行以下命令：

serverless deploy

部署后，您应该看到类似以下的输出：

正在部署 "serverless-http-api" 至阶段 "dev" (us-east-1)

✔ 服务已部署至堆栈 serverless-http-api-dev (91s)

端点: GET - https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/
函数:
  hello: serverless-http-api-dev-hello (1.6 kB)

注意：当前形式下，部署后您的 API 是公开的，任何人都可以调用。对于生产部署，您可能希望配置授权者。有关如何操作的详情，请参阅 HTTP API (API Gateway V2) 事件文档。

调用

成功部署后，您可以通过 HTTP 调用创建的应用程序：

curl https://xxxxxxx.execute-api.us-east-1.amazonaws.com/

这应该会产生类似以下的响应：

{ "message": "Go Serverless v4! 您的功能执行成功！" }

本地开发

最简单的开发和测试功能的方式是使用 dev 命令：

serverless dev

这将启动 AWS Lambda 的本地模拟器，并将您的请求隧道到 AWS Lambda，允许您像在云端一样与您的功能交互。

现在您可以像之前一样调用函数，但这次函数将在本地执行。现在您可以在本地开发功能，调用它，并立即看到结果，而无需重新部署。

完成开发后，别忘了运行 serverless deploy 将功能部署到云端。