MCP Hello World

MCP Hello World

A minimal MCP (Model Context Protocol) server that responds with "Hello, World" via Streamable HTTP. This project serves as a reference implementation and integration testing baseline for MCP client development.

Features

• Streamable HTTP MCP endpoint at /mcp that returns "Hello, World"
• Health check endpoint at /healthz for monitoring
• Prometheus metrics at /metrics for observability
• Production-ready with proper error handling, logging, and security
• TypeScript codebase with comprehensive test coverage
• Docker support for containerized deployment
• Cloud Run ready for serverless deployment

Quick Start

Prerequisites

• Node.js 20+
• npm or yarn

Local Development

1. Install dependencies
   npm install
2. Start development server
   npm run dev
3. Test the endpoints
   # Health check curl http://localhost:8080/healthz # Metrics curl http://localhost:8080/metrics # MCP endpoint (POST request) curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"initialize","id":1}'

Using with MCP Inspector

The primary use case is connecting via MCP Inspector for integration testing:

1. Deploy or run locally (see deployment options below)
2. Open MCP Inspector in your browser
3. Connect to your MCP server
   • Local development: http://localhost:8080/mcp
   • Cloud Run: https://your-service-url.run.app/mcp
4. Verify connection
   • You should see "Hello, World" message
   • Connection status should show as connected
   • Response time should be < 300ms (excluding cold starts)

API Endpoints

POST /mcp - MCP Streamable HTTP

Main MCP endpoint that implements the Streamable HTTP protocol.

Request:

Response: Server-Sent Events stream

Headers:

• Content-Type: text/event-stream
• Cache-Control: no-store
• Access-Control-Allow-Origin: *

GET /healthz - Health Check

Returns server health status and uptime.

Response:

GET /metrics - Prometheus Metrics

Returns metrics in Prometheus text exposition format.

Key Metrics:

• mcp_hello_world_http_requests_total - HTTP request counter
• mcp_hello_world_handshake_total - MCP handshake counter
• mcp_hello_world_handshake_duration_seconds - MCP handshake latency
• mcp_hello_world_uptime_seconds - Server uptime
• mcp_hello_world_cold_start_total - Cold start counter (Cloud Run)

Development

Scripts

Testing

The project has comprehensive test coverage with 38 tests covering:

• Core MCP functionality - handshake, response format, error handling
• HTTP endpoints - health checks, metrics, CORS
• Error scenarios - malformed requests, method validation
• Metrics collection - counters, histograms, gauges
• Logging - structured logs, request IDs

Run tests with coverage:

Code Quality

• ESLint for code linting with TypeScript rules
• Prettier for code formatting
• TypeScript with strict configuration
• Vitest for testing with coverage reporting
• Conventional Commits for commit messages

Deployment

Docker

1. Build the image
   docker build -t mcp-hello-world .
2. Run the container
   docker run -p 8080:8080 mcp-hello-world

Google Cloud Platform (Automated)

This project uses GCP Cloud Build for automated CI/CD. Every push to the main branch triggers:

1. Automated Build Pipeline (via cloudbuild.yaml):
   • Code quality checks (TypeScript, ESLint)
   • Test execution with coverage
   • Docker image build and push to Artifact Registry
   • SBOM generation and security scanning
   • Automatic deployment to Cloud Run
   • Health checks and endpoint testing
2. Setup GCP Cloud Build Trigger:
   # Enable required APIs gcloud services enable cloudbuild.googleapis.com gcloud services enable run.googleapis.com gcloud services enable artifactregistry.googleapis.com # Create Artifact Registry repository gcloud artifacts repositories create mcp-servers \ --repository-format=docker \ --location=us-central1 # Set up Cloud Build trigger (via Console or CLI) gcloud alpha builds triggers create github \ --repo-name=mcp-hello-world \ --repo-owner=MillCityAI \ --branch-pattern=^main$ \ --build-config=cloudbuild.yaml
3. Manual Deployment (if needed):
   gcloud builds submit --config cloudbuild.yaml
4. Get the service URL:
   gcloud run services describe mcp-hello-world \ --platform managed \ --region us-central1 \ --format 'value(status.url)'

Environment Variables

Architecture

Technology Stack

• Runtime: Node.js 20 LTS
• Framework: Fastify (high performance HTTP server)
• Language: TypeScript with strict configuration
• Logging: Pino (structured JSON logging)
• Metrics: prom-client (Prometheus metrics)
• Testing: Vitest + @vitest/coverage-v8
• Container: Multi-stage Docker build with Alpine Linux

Security

• OWASP ASVS Level 1 compliance
• CORS properly configured for MCP Inspector
• Rate limiting (100 requests/minute)
• Security headers via Helmet
• Input validation and request size limits
• Secrets management via environment variables
• Non-root container execution
• Log sanitization (redacts auth headers)

Performance

• Target latency: p95 < 300ms (excluding cold starts)
• Cold start tracking for Cloud Run deployments
• Connection pooling and keep-alive
• Efficient JSON parsing and SSE streaming
• Graceful shutdown handling

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run the test suite (npm test)
5. Run linting (npm run lint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

Apache-2.0 License - see the LICENSE file for details.

Related Projects

• Model Context Protocol - The MCP specification
• MCP Inspector - MCP client testing tool
• Fastify - Fast and low overhead web framework

Support

• Documentation: See the /Documentation folder for detailed specs
• Issues: Report bugs via GitHub Issues
• Community: Join the MCP community discussions

🤖 Generated with Claude Code