AWS AppRunner MCP Server

# MCP Server for AWS AppRunner A boilerplate Model Context Protocol (MCP) server implementation using TypeScript, Express.js, and the `@modelcontextprotocol/sdk`. This server is designed to be deployed to AWS AppRunner. ## Overview This server implements the Model Context Protocol, enabling AI assistants and applications to securely connect to external tools, data sources, and resources. The server provides: - **Tool Integration**: Define and expose tools that AI can use to perform actions - **Resource Access**: Control access to files and other resources - **Prompt Templates**: Provide standardized prompt templates for consistent interactions ## Features - MCP Server implementation with TypeScript and Express.js - Streamable HTTP transport supporting both JSON-RPC and SSE - Sample tools, resources, and prompts - AWS AppRunner deployment configuration - Docker containerization with production and development configurations - Docker Compose for local development with hot reloading - GitHub Actions CI/CD workflow - Environment configuration management - Structured logging with Pino - MCP Inspector integration for testing and debugging ## Requirements - Node.js 20+ - npm or yarn - Docker (for containerization) - Docker Compose (for local development) - AWS account (for deployment) ## Getting Started ### Installation 1. Clone this repository: ```bash git clone https://github.com/yourusername/mcp-server.git cd mcp-server ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env` file based on the example: ```bash cp .env.example .env ``` ### Development #### Local Development 1. Start the development server: ```bash npm run dev ``` 2. The server will be available at http://localhost:3000 #### Docker Compose Development (Recommended) This method provides a consistent development environment with hot reloading: 1. Optional: Configure npm registry for development: The project is configured to work with both public and private npm registries: - **Using public registry (default)**: No action needed. - **Using private/corporate registry**: Create a `.npmrc` file in the project root with your registry configuration: ``` registry=https://your-private-registry.com/ strict-ssl=true|false ``` 2. Start the Docker development environment: ```bash docker-compose up -d ``` 3. View logs in real-time: ```bash docker-compose logs -f ``` 4. The server will be available at http://localhost:3000 5. Changes to source files will be automatically reflected in the running container thanks to volume mounts and hot reloading 6. Stop the development container: ```bash docker-compose down ``` #### Using the Makefile This project includes a Makefile to simplify common development tasks: 1. Start the MCP server with Docker Compose: ```bash make mcp ``` 2. Start the MCP Inspector for testing and debugging: ```bash make inspector ``` 3. Start both the MCP server and Inspector together: ```bash make start ``` 4. Start both services using Docker Compose: ```bash make compose ``` 5. Stop all running containers: ```bash make stop ``` 6. Clean up containers and images: ```bash make clean ``` #### Using the MCP Inspector The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a tool for testing and debugging MCP implementations: 1. Start the Inspector using one of these methods: ```bash # Stand-alone Inspector make inspector # Both MCP server and Inspector with Docker Compose make compose ``` 2. Access the Inspector web UI at http://localhost:6274 3. Connect to your local MCP server at http://localhost:3000 4. Use the Inspector to: - Test MCP initialization and session management - Discover available tools, resources, and prompts - Make tool calls and view responses - Debug protocol communication issues ### Testing Your MCP Server You can test the MCP server using cURL: ```bash # Health check curl http://localhost:3000/health # Initialize MCP connection (POST request) curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"protocolVersion":"1.0"},"id":1}' # After initialization, use the returned Mcp-Session-Id for subsequent requests # Example (replace SESSION_ID with the actual session ID from the response): curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: SESSION_ID" \ -d '{"jsonrpc":"2.0","method":"tool/call","params":{"name":"tool-name","args":{}},"id":2}' # Connect to SSE stream (GET request) with session ID curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: SESSION_ID" # Terminate session (DELETE request) curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: SESSION_ID" ``` ## Project Structure ``` ├── src/ │ ├── mcp/ # MCP implementation │ │ ├── tools.ts # Tool handlers │ │ ├── resources.ts # Resource handlers │ │ ├── prompts.ts # Prompt handlers │ │ └── server.ts # MCP server setup with Streamable HTTP transport │ ├── utils/ # Utilities │ │ ├── config.ts # Configuration │ │ └── logger.ts # Logging │ ├── app.ts # Express app setup │ └── index.ts # Application entry point ├── Dockerfile # Production Docker configuration ├── Dockerfile.dev # Development Docker configuration with hot reloading ├── docker-compose.yml # Docker Compose for local development ├── apprunner.yaml # AWS AppRunner configuration ├── Makefile # Makefile with development commands ├── .github/ # GitHub Actions workflows ├── CLAUDE.md # Implementation notes and guidance for Claude Code └── ... # Project configuration files ``` ## Docker Configuration The project includes two Docker configurations: ### Development Docker (Dockerfile.dev) - Based on Node.js 20 Alpine - Supports both public and private npm registries - Mounts source code for hot reloading - Uses tsx for TypeScript execution without compilation - Configured to work with or without an `.npmrc` file ### Production Docker (Dockerfile) - Multi-stage build for optimized image size - First stage builds the TypeScript application - Second stage contains only the compiled JavaScript and production dependencies - Uses public npm registry for AWS AppRunner deployment - Optimized for security and performance ## Deployment to AWS AppRunner ### Prerequisites - AWS account with appropriate permissions - AWS CLI configured - ECR repository created for the container image - AppRunner service role with permissions to pull from ECR ### Manual Deployment 1. Build and tag the Docker image: ```bash docker build -t your-ecr-repo/mcp-server:latest . ``` 2. Push the image to ECR: ```bash aws ecr get-login-password --region your-region | docker login --username AWS --password-stdin your-account-id.dkr.ecr.your-region.amazonaws.com docker push your-ecr-repo/mcp-server:latest ``` 3. Create or update the AppRunner service: ```bash aws apprunner create-service --cli-input-json file://apprunner-config.json ``` ### GitHub Actions Deployment This repository includes a GitHub Actions workflow in `.github/workflows/deploy.yml` that automates the deployment process when you push to the main branch. To use it, set up the following GitHub secrets: - `AWS_ACCESS_KEY_ID`: AWS access key with appropriate permissions - `AWS_SECRET_ACCESS_KEY`: AWS secret access key - `AWS_REGION`: AWS region for deployment - `ECR_REPOSITORY`: Name of your ECR repository - `APPRUNNER_SERVICE`: Name of your AppRunner service - `APPRUNNER_SERVICE_ROLE_ARN`: ARN of the service role for AppRunner ## Customization ### Adding New Tools Edit `src/mcp/tools.ts` to add new tool definitions and handlers: ```typescript // Add to tool list { name: 'your-tool-name', description: 'Description of your tool', inputSchema: yourToolSchema } // Add to tool call handler case 'your-tool-name': return { content: [ { type: 'text', text: `Result from your tool with args: ${JSON.stringify(args)}` } ] }; ``` ### Adding New Resources Edit `src/mcp/resources.ts` to add new resource definitions and content. ### Adding New Prompts Edit `src/mcp/prompts.ts` to add new prompt templates. ## License MIT