MCP服务器基础设施

Extensible MCP Server infra - Complete Guide

Project Structure

generic-mcp/
├── pet_store_mcp/              # MCP server package
│   ├── Dockerfile              # Container definition
│   ├── requirements.txt        # Python dependencies
│   ├── src/
│   │   ├── __init__.py
│   │   └── petstore_mcp_server.py  # Main server code
│   └── env.example             # Environment variables template
├── docker-compose.yml          # Production deployment config
├── scripts/
│   ├── setup_pet_store.sh      # Quick setup & build
│   └── test-docker-cursor.sh   # Test both modes
├── specs/
│   └── pet-store-openapi.json  # API specification
└── docs/
    └── GUIDE.md                # This file

Two Modes, One Docker Image

The MCP server runs in Docker and supports two transport modes:

stdio Mode (For Cursor)

• What: Direct process communication via stdin/stdout
• When: Local development with Cursor
• How: Cursor spawns the Docker container and pipes JSON-RPC messages
• Default: Dockerfile defaults to stdio mode

HTTP Mode (For Coolify/Production)

• What: Web server with HTTP/SSE transport
• When: Remote deployments, multiple clients
• How: Runs as a service on port 8000 with health checks
• Switch: Set TRANSPORT_MODE=http environment variable

Quick Start

1. Build the Image

# From project root
./scripts/setup_pet_store.sh

This builds: docker build -t petstore-mcp-server -f pet_store_mcp/Dockerfile pet_store_mcp/

2. Configure Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "petstore-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "petstore-mcp-server"]
    }
  }
}

Restart Cursor (fully quit and reopen)

3. Test It

Ask Cursor: "List the top 10 pets from the petstore"

Deployment to Coolify

Using docker-compose

docker-compose up -d

The docker-compose.yml automatically:

• Sets TRANSPORT_MODE=http
• Exposes port 8000 (adjustable as you'll need free ports for each MCP)
• Configures health checks (/health endpoint)
• Sets resource limits
• Enables auto-restart

Important: For multiple MCPs on Coolify, change the port:

ports:
  - "8001:8001"  # Use a free port
environment:
  - PORT=8001

Health Check

curl http://localhost:8000/health
# Returns: OK

Testing HTTP Mode

When the server is running in HTTP mode, you can test it manually:

1. Start the server:

docker-compose up -d

2. Check health endpoint:

curl http://localhost:8000/health
# Should return: OK

3. Verify server logs:

docker-compose logs petstore-mcp
# Should show: "Petstore MCP Server starting in HTTP mode on 0.0.0.0:8000..."

4. Monitor in real-time:

docker-compose logs -f petstore-mcp

5. Stop the server:

docker-compose down

Note: The /sse endpoint is for MCP clients only and requires a proper SSE handshake - it won't work with simple curl commands. To verify HTTP mode is working:

• ✅ Health endpoint returns OK
• ✅ Server logs show "HTTP mode"
• ✅ No errors in docker-compose logs

For actual MCP client testing, you'd need an MCP-compatible tool that supports HTTP/SSE transport.

Available Scripts

scripts/setup_pet_store.sh

What it does:

• Builds the Docker image from pet_store_mcp/
• Shows Cursor configuration
• Fast way to get started

Run it:

./scripts/setup_pet_store.sh

scripts/test-docker-cursor.sh

What it does:

• Builds the image
• Tests stdio mode (Cursor compatibility)
• Tests HTTP mode (Coolify compatibility)
• Validates health checks
• Cleans up after itself

Run it:

./scripts/test-docker-cursor.sh

How the Dockerization Works

Dockerfile Breakdown

FROM python:3.11-slim
WORKDIR /app

# Install curl for health checks
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    apt-get clean

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY src/ ./src/

# Environment setup
ENV PYTHONUNBUFFERED=1
ENV TRANSPORT_MODE=stdio    # Default to stdio
ENV HOST=0.0.0.0
ENV PORT=8000

EXPOSE 8000

ENTRYPOINT ["python", "src/petstore_mcp_server.py"]

Key Points

1. Single Image: One image works for both Cursor and Coolify
2. Mode Switching: Environment variable TRANSPORT_MODE controls behavior
3. No Python Required: Everything bundled in Docker
4. Consistent: Same environment everywhere

MCP Server Tools

The server exposes 3 tools from the Petstore API:

Environment Variables

Troubleshooting

Cursor Not Connecting

1. Check ~/.cursor/mcp.json syntax is valid
2. Verify image exists: docker images | grep petstore-mcp-server
3. Restart Cursor completely
4. Check Cursor MCP logs: Command Palette → "MCP: Show Logs"

Docker Build Fails

# Clean rebuild
docker build --no-cache -t petstore-mcp-server -f pet_store_mcp/Dockerfile pet_store_mcp/

Port Already in Use (HTTP mode)

# Check what's using port 8000
lsof -i :8000

# Use different port in docker-compose.yml
ports:
  - "8080:8000"

From Example to Generic

This petstore example demonstrates the pattern for generating MCP servers from any OpenAPI spec:

1. Parse OpenAPI → Extract operations, parameters, schemas
2. Generate Server → Create tool definitions and HTTP handlers
3. Dockerize → Package with dependencies
4. Deploy → Same image for dev (Cursor) and prod (Coolify)

Next step: Build a generator that does this automatically for any OpenAPI spec.