Serverless MCP

A modern TypeScript package implementing the Model Context Protocol (MCP) with modular architecture and AWS Lambda streaming support.

Features

• 🎯 Full MCP Protocol Support - Complete implementation of MCP 2024-11-05 specification
• 🧩 Modular Architecture - Independent slices for prompts, resources, tools, and roots
• 🚀 AWS Lambda Ready - Built-in support for Lambda streaming responses
• 📡 Multiple Transports - stdio, HTTP streaming, and Lambda transports
• 🔧 TypeScript First - Full type safety with comprehensive schemas
• 🧪 Well Tested - Comprehensive test suite with high coverage
• ⚡ High Performance - Optimized for serverless and edge environments
• 🎨 Decorator Support - Optional decorators for clean API design

Installation

npm install serverless-mcp
# or
pnpm add serverless-mcp
# or
yarn add serverless-mcp

Quick Start

Basic Server

import{McpServer,StdioTransport,McpToolProvider,McpResourceProvider,}from'serverless-mcp';// Create transport and serverconsttransport=newStdioTransport();constserver=newMcpServer(transport,{name: 'my-mcp-server',version: '1.0.0',});// Setup toolsconsttoolProvider=newMcpToolProvider();toolProvider.registerTool({name: 'hello',description: 'Say hello',inputSchema: {type: 'object',properties: {name: {type: 'string',description: 'Name to greet'}},required: ['name']},handler: async(args)=>`Hello, ${args.name}!`});server.setToolProvider(toolProvider);

AWS Lambda Server

import{LambdaMcpHandler}from'serverless-mcp';exportconsthandler=LambdaMcpHandler.create({name: 'lambda-mcp-server',version: '1.0.0',transport: {cors: {origin: '*'},enableLogs: true,},},(server)=>{// Configure your server hereconsttoolProvider=newMcpToolProvider();// ... setup tools, resources, promptsserver.setToolProvider(toolProvider);});

Core Concepts

Slices

The library is organized into modular slices, each handling a specific aspect of the MCP protocol:

• Prompts - Template messages and conversation patterns
• Resources - Data sources and content providers
• Tools - Functions that can be executed by AI models
• Roots - File system and URI boundary definitions

Transports

Multiple transport mechanisms are supported:

• StdioTransport - For subprocess communication
• HttpStreamingTransport - For HTTP with Server-Sent Events
• LambdaStreamingTransport - For AWS Lambda with response streaming

API Reference

Tools

import{McpToolProvider}from'serverless-mcp';consttoolProvider=newMcpToolProvider();// Simple tooltoolProvider.registerTool(McpToolProvider.createSimpleTool('current-time','Get current timestamp',()=>newDate().toISOString()));// Parameterized tooltoolProvider.registerTool(McpToolProvider.createParameterizedTool('calculate','Perform calculations',[{name: 'operation',type: 'string',required: true},{name: 'a',type: 'number',required: true},{name: 'b',type: 'number',required: true},],async(args)=>{// Tool implementation}));

Resources

import{McpResourceProvider}from'serverless-mcp';constresourceProvider=newMcpResourceProvider();// Static resourceresourceProvider.registerResource(McpResourceProvider.createStaticResource('memory://config','Configuration',JSON.stringify({setting: 'value'}),'application/json'));// Dynamic resourceresourceProvider.registerResource(McpResourceProvider.createDynamicResource('memory://stats','Live Statistics',()=>JSON.stringify({timestamp: Date.now()}),'application/json'));

Prompts

import{McpPromptProvider,PromptUtils}from'serverless-mcp';constpromptProvider=newMcpPromptProvider();promptProvider.registerPrompt({name: 'greeting',description: 'Generate personalized greetings',arguments: [{name: 'name',required: true},{name: 'formal',required: false}],handler: async(args)=>{constgreeting=args.formal ? `Good day, ${args.name}`
: `Hi ${args.name}!`;return[PromptUtils.createUserMessage(greeting)];}});

Middleware

Add middleware to tools for cross-cutting concerns:

import{createTimingMiddleware,createLoggingMiddleware,createTimeoutMiddleware,createRateLimitMiddleware,}from'serverless-mcp';consttoolProvider=newMcpToolProvider();toolProvider.use(createTimingMiddleware()).use(createLoggingMiddleware()).use(createTimeoutMiddleware(5000)).use(createRateLimitMiddleware(10,60000));// 10 calls per minute

Examples

See the examples directory for complete working examples:

• Basic Server - Complete stdio server with all features
• Lambda Server - AWS Lambda deployment example

Development

# Install dependencies
pnpm install
# Run tests
pnpm test# Build the package
pnpm build
# Lint and format
pnpm lint
pnpm format

Architecture

src/
├── core/ # Core JSON-RPC and MCP protocol
├── prompts/ # Prompt management and templates
├── resources/ # Resource providers and caching
├── tools/ # Tool execution and middleware
├── roots/ # Root directory management
├── transports/ # Transport implementations
└── lambda/ # AWS Lambda integration

Each slice is independently testable and can be used separately if needed.

TypeScript Support

The library is built with TypeScript and provides comprehensive type definitions:

importtype{McpTool,McpResource,McpPrompt,JsonRpcMessage,ToolDefinition,ResourceDefinition,PromptDefinition,}from'serverless-mcp';

License

MIT - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions