Serverless Web

A Model Context Protocol (MCP) server implementation for deploying web applications to AWS serverless infrastructure.

Overview

This project implements an MCP server that enables LLM coding agents to deploy web applications to AWS serverless services. It follows the Model Context Protocol specification to provide a standardized interface for AI agents to interact with AWS deployment capabilities.

The server supports deploying:

• Backend services using API Gateway, Lambda with Web Adapter, and DynamoDB/Aurora Serverless
• Frontend applications using S3 and CloudFront
• Fullstack applications combining both backend and frontend components

MCP Implementation

This server implements the Model Context Protocol with the following features:

Resources

Provides contextual information about:

• Available deployment templates (template:list, template:{name})
• Existing deployments and their status (deployment:list, deployment:{project-name})

Tools

Exposes deployment capabilities as tools:

• deploy: Deploy web applications to AWS serverless infrastructure
• get_logs: Retrieve application logs from CloudWatch
• get_metrics: Fetch performance metrics for deployed applications
• deployment_help: Get help with deployment requirements and troubleshooting
• update_frontend: Update frontend assets without redeploying the entire infrastructure

Architecture

The server consists of these core components:

1. MCP Protocol Handler: Implements the JSON-RPC interface and message handling
2. Unified Deployment Service: Manages deployments across different types (backend, frontend, fullstack)
3. AWS Integration Layer: Interfaces with AWS SAM CLI and AWS services

Deployment Types

The server supports a unified approach to deployments with different types:

• Backend Deployment: Backend services using Lambda + API Gateway
• Frontend Deployment: Frontend applications using S3 + CloudFront
• Fullstack Deployment: Combined backend and frontend deployment

AWS Lambda Web Adapter

For backend and fullstack deployments, the server uses AWS Lambda Web Adapter to run web applications on AWS Lambda. This allows developers to use familiar web frameworks without any code changes.

Getting Started

Prerequisites

• Node.js 18 or higher
• AWS SAM CLI
• AWS credentials configured

Installation

# Install globally from npm
npm install -g serverless-web-mcp-server

# Or clone the repository
git clone https://github.com/bnusunny/serverless-web-mcp-server.git
cd serverless-web-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Usage

Using as a Local MCP Server

To use with Claude for Desktop or other MCP clients, add the server to your client configuration:

For Claude for Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "serverless-web": {
      "command": "serverless-web-mcp"
    }
  }
}

After configuring, restart Claude for Desktop. You should see the serverless-web tools available in the Claude interface.

Command Line Options

Usage:
  serverless-web-mcp [options]

Options:
  --debug, -d                 Enable debug logging
  --templates, -t <path>      Specify templates directory path
  --transport, -m <mode>      Transport method (stdio or http, default: stdio)
  --port, -p <number>         HTTP server port (default: 3000, only used with http transport)
  --help, -h                  Show this help message
  
Environment Variables:
  MCP_TRANSPORT               Transport method (stdio or http, default: stdio)
  PORT                        HTTP server port (default: 3000)
  TEMPLATES_PATH              Path to templates directory

Resource Discovery

To discover available resources and tools, use the following methods:

List Resources

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resource/list",
  "params": {}
}

This will return a list of all available resources with their patterns and descriptions.

List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tool/list",
  "params": {}
}

This will return a list of all available tools with their descriptions and parameter schemas.

Example Tool Invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool/invoke",
  "params": {
    "name": "deploy",
    "parameters": {
      "deploymentType": "backend",
      "projectName": "my-api",
      "projectRoot": "/path/to/project",
      "region": "us-east-1",
      "backendConfiguration": {
        "builtArtifactsPath": "backend/dist",
        "runtime": "nodejs18.x",
        "startupScript": "bootstrap",
        "memorySize": 512,
        "timeout": 30,
        "environment": {
          "NODE_ENV": "production"
        }
      }
    }
  }
}

Example Resource Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resource/get",
  "params": {
    "uri": "deployment:my-api"
  }
}

Deployment Parameters

Backend Deployment

{
  "deploymentType": "backend",
  "projectName": "my-api",
  "projectRoot": "/path/to/project",
  "region": "us-east-1",
  "backendConfiguration": {
    "builtArtifactsPath": "backend/dist",
    "runtime": "nodejs18.x",
    "startupScript": "bootstrap",
    "memorySize": 512,
    "timeout": 30,
    "environment": {
      "NODE_ENV": "production"
    },
    "databaseConfiguration": {
      "tableName": "Users",
      "attributeDefinitions": [
        { "name": "id", "type": "S" }
      ],
      "keySchema": [
        { "name": "id", "type": "HASH" }
      ]
    }
  }
}

Frontend Deployment

{
  "deploymentType": "frontend",
  "projectName": "my-website",
  "projectRoot": "/path/to/project",
  "region": "us-east-1",
  "frontendConfiguration": {
    "builtAssetsPath": "frontend/build",
    "indexDocument": "index.html"
  }
}

Fullstack Deployment

{
  "deploymentType": "fullstack",
  "projectName": "my-fullstack-app",
  "projectRoot": "/path/to/project",
  "region": "us-east-1",
  "backendConfiguration": {
    "builtArtifactsPath": "backend/dist",
    "runtime": "nodejs18.x",
    "environment": {
      "NODE_ENV": "production"
    }
  },
  "frontendConfiguration": {
    "builtAssetsPath": "frontend/build",
    "indexDocument": "index.html"
  }
}

Development

Project Structure

/
├── src/
│   ├── mcp/              # MCP protocol implementation
│   │   ├── tools/        # Tool implementations
│   │   │   └── index.ts  # Tool registration
│   │   ├── resources/    # Resource implementations
│   │   │   └── index.ts  # Resource registration
│   │   └── server.ts     # MCP server setup
│   ├── deployment/       # Deployment service
│   ├── cli/              # Command line interface
│   └── index.ts          # Main server entry point
├── templates/            # Deployment templates
├── examples/             # Example applications
├── docs/                 # Documentation
├── config.json           # Server configuration
├── DESIGN.md             # Detailed design document
└── README.md             # This file

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.