MCP 服务器

MCP Hello World

A minimal reference implementation of an MCP server that responds with "Hello, World" via Streamable HTTP. Serves as a baseline for integration testing and MCP client development with production-ready features including health checks, metrics, and containerized deployment.

README

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

Install dependencies
```
npm install
```
Start development server
```
npm run dev
```

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:

Deploy or run locally (see deployment options below)
Open MCP Inspector in your browser
Connect to your MCP server
- Local development: http://localhost:8080/mcp
- Cloud Run: https://your-service-url.run.app/mcp
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:

{
  "jsonrpc": "2.0", 
  "method": "initialize",
  "id": 1
}

Response: Server-Sent Events stream

data: {"jsonrpc":"2.0","id":1,"result":{"message":"Hello, World","timestamp":"2025-08-28T...","server":"mcp-hello-world","version":"0.1.0"}}

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:

{
  "status": "ok",
  "uptime_s": 120,
  "timestamp": "2025-08-28T...",
  "version": "0.1.0"
}

`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

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Type check
npm run typecheck

# Docker build
npm run docker:build

# Docker run
npm run docker:run

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:

npm test

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

Build the image
```
docker build -t mcp-hello-world .
```

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:

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

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

Manual Deployment (if needed):

gcloud builds submit --config cloudbuild.yaml

Get the service URL:

gcloud run services describe mcp-hello-world \
  --platform managed \
  --region us-central1 \
  --format 'value(status.url)'

Environment Variables

Variable	Required	Default	Description
`PORT`	No	8080	Server port
`NODE_ENV`	No	development	Environment (development/production)
`LOG_LEVEL`	No	info/debug	Logging level
`REGION`	No	unknown	Deployment region
`BUILD_SHA`	No	dev	Build/commit SHA
`INSTANCE_ID`	No	local	Instance identifier