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
Clone this repository:
git clone https://github.com/yourusername/mcp-server.git cd mcp-serverInstall dependencies:
npm installCreate a
.env
file based on the example:cp .env.example .env
Development
Local Development
Start the development server:
npm run devThe server will be available at http://localhost:3000
Docker Compose Development (Recommended)
This method provides a consistent development environment with hot reloading:
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
Start the Docker development environment:
docker-compose up -dView logs in real-time:
docker-compose logs -fThe server will be available at http://localhost:3000
Changes to source files will be automatically reflected in the running container thanks to volume mounts and hot reloading
Stop the development container:
docker-compose down
Using the Makefile
This project includes a Makefile to simplify common development tasks:
Start the MCP server with Docker Compose:
make mcpStart the MCP Inspector for testing and debugging:
make inspectorStart both the MCP server and Inspector together:
make startStart both services using Docker Compose:
make composeStop all running containers:
make stopClean up containers and images:
make clean
Using the MCP Inspector
The MCP Inspector is a tool for testing and debugging MCP implementations:
Start the Inspector using one of these methods:
# Stand-alone Inspector make inspector # Both MCP server and Inspector with Docker Compose make composeAccess the Inspector web UI at http://localhost:6274
Connect to your local MCP server at http://localhost:3000
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:
Project Structure
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
Build and tag the Docker image:
docker build -t your-ecr-repo/mcp-server:latest .Push the image to ECR:
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:latestCreate or update the AppRunner service:
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 permissionsAWS_SECRET_ACCESS_KEY
: AWS secret access keyAWS_REGION
: AWS region for deploymentECR_REPOSITORY
: Name of your ECR repositoryAPPRUNNER_SERVICE
: Name of your AppRunner serviceAPPRUNNER_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:
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
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A boilerplate TypeScript MCP server with Express.js designed for AWS AppRunner deployment. Provides sample tools, resources, and prompts with Docker containerization and GitHub Actions CI/CD workflow.