BradWebb101/serverless-rust-mcp-servers

Rust MCP Server

A high-performance Model Context Protocol (MCP) server built in Rust and deployed on AWS Lambda. This server provides product search capabilities through various tools, demonstrating a complete serverless MCP implementation.

📋 Table of Contents

• Infrastructure
• Logic
• Connections

🏗️ Infrastructure

Architecture Overview

This project uses AWS CDK (Cloud Development Kit) with TypeScript to deploy a Rust-based Lambda function with the following components:

• AWS Lambda Function: Serverless compute running the Rust MCP server
• Function URL: HTTP endpoint for direct access without API Gateway
• CORS Configuration: Cross-origin resource sharing for web clients
• ARM64 Architecture: Optimized for cost and performance on AWS Graviton processors

Deployment Stack

The infrastructure is defined in lib/rust-mcp-stack.ts and includes:

// Key infrastructure components:
- Runtime: PROVIDED_AL2023 (Amazon Linux 2023)
- Architecture: ARM_64 (AWS Graviton)
- Timeout: 30 seconds
- Memory: Default (128MB)
- Build Tool: cargo-zigbuild for cross-compilation

Build Process

The CDK stack handles cross-compilation from any platform to ARM64 Linux:

1. Local Bundling: Uses cargo-zigbuild for cross-compilation
2. Target: aarch64-unknown-linux-gnu for AWS Lambda ARM64
3. Binary: Creates a bootstrap executable for Lambda runtime
4. Deployment: Packages and deploys via CDK

CORS Configuration

cors: {
  allowedOrigins: ['*'],
  allowedMethods: [HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT, HttpMethod.DELETE],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
  maxAge: Duration.hours(1)
}

Prerequisites

• AWS CLI configured
• AWS CDK installed (npm install -g aws-cdk)
• Rust toolchain
• Zig compiler
• cargo-zigbuild (cargo install cargo-zigbuild)

Deployment Commands

# Install dependencies
npm install

# Build and deploy
cdk deploy

# Get the Function URL from outputs

🧠 Logic

MCP Protocol Implementation

The server implements the Model Context Protocol with full JSON-RPC 2.0 compliance:

Core Protocol Methods

1. Initialize: Establishes connection and returns server capabilities
2. Tools/List: Returns available tools for product search operations
3. Tools/Call: Executes specific tools with provided parameters

Available Tools

The server provides four main tools for product operations:

1. Search Products

{
  "name": "search_products",
  "description": "Search for products by name or keyword",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "Search query"},
      "limit": {"type": "integer", "description": "Max results (optional)"}
    },
    "required": ["query"]
  }
}

2. Filter by Price Range

{
  "name": "filter_by_price_range", 
  "description": "Filter products within a price range",
  "inputSchema": {
    "properties": {
      "min_price": {"type": "number", "description": "Minimum price"},
      "max_price": {"type": "number", "description": "Maximum price"}
    },
    "required": ["min_price", "max_price"]
  }
}

3. Search by Category

{
  "name": "search_by_category",
  "description": "Search products within a specific category", 
  "inputSchema": {
    "properties": {
      "category": {"type": "string", "description": "Product category"}
    },
    "required": ["category"]
  }
}

4. Get Categories

{
  "name": "get_categories",
  "description": "Retrieve all available product categories",
  "inputSchema": {"type": "object", "properties": {}}
}

Data Source

The server integrates with the DummyJSON API for product data:

• Products Endpoint: https://dummyjson.com/products
• Search Endpoint: https://dummyjson.com/products/search
• Category Endpoints: https://dummyjson.com/products/category/{category}
• Categories List: https://dummyjson.com/products/categories

Error Handling

Comprehensive error handling with proper MCP error responses:

• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error
• HTTP errors: Proper propagation from external API calls

Session Management

Basic session management capabilities:

• Session information storage
• User preferences (extensible)
• Thread-safe session handling with Arc<Mutex<HashMap>>

🔗 Connections

MCP Inspector (Recommended)

The easiest way to test and interact with your MCP server is using the MCP Inspector:

1. Install MCP Inspector:

   npm install -g @anthropic-ai/mcp-inspector
   

2. Connect to your deployed server:

   mcp-inspector https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws
   

3. Interactive Testing:

   • View available tools
   • Test tool calls with parameters
   • Inspect request/response formats
   • Validate MCP protocol compliance

Direct HTTP/cURL Testing

You can test the server directly using cURL commands:

1. Initialize Connection

curl -X POST https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize", 
    "params": {}
  }'

2. List Available Tools

curl -X POST https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

3. Search Products

curl -X POST https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_products",
      "arguments": {
        "query": "smartphone",
        "limit": 5
      }
    }
  }'

4. Filter by Price Range

curl -X POST https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", 
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "filter_by_price_range",
      "arguments": {
        "min_price": 100,
        "max_price": 500
      }
    }
  }'

5. Search by Category

curl -X POST https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5, 
    "method": "tools/call",
    "params": {
      "name": "search_by_category",
      "arguments": {
        "category": "smartphones"
      }
    }
  }'

6. Get Categories

curl -X POST https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call", 
    "params": {
      "name": "get_categories",
      "arguments": {}
    }
  }'

CORS Preflight

curl -X OPTIONS https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type"

Integration with MCP Clients

This server is compatible with any MCP client implementation:

• Claude Desktop: Can be configured to use this server
• Custom MCP Clients: Use the Function URL as the server endpoint
• Web Applications: Direct HTTP integration with CORS support

Response Format

All responses follow the JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    // Tool result data
  }
}

Error responses:

{
  "jsonrpc": "2.0", 
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Additional error details"
  }
}

🚀 Quick Start

1. Deploy the infrastructure:

   cdk deploy
   

2. Get your Function URL from the CDK output

3. Test with MCP Inspector:

   mcp-inspector https://YOUR_FUNCTION_URL.lambda-url.us-east-1.on.aws
   

4. Start building MCP applications that leverage product search capabilities!

🧪 Testing

The project includes comprehensive test coverage:

• Unit tests: cargo test
• Integration tests: Full MCP protocol compliance
• 68 total tests covering all functionality

📄 License

This project is provided as-is for educational and development purposes.