├── src/
│   ├── mcp_app.py                      # FastMCP instance — import `mcp` from here
│   ├── server.py                       # Entry point: Starlette app, middleware, routing
│   ├── tools/
│   │   ├── example_tools.py            # echo_message, greet, calculate
│   │   └── knowledgebase_tools.py      # search_knowledgebase, get_knowledgebase_topic
│   ├── prompts/
│   │   └── example_prompts.py          # general_assistant, task_helper, analysis_mode
│   ├── resources/
│   │   ├── help_resources.py           # help://<name>/capabilities, quick-reference
│   │   └── server_info.py              # data://server/info
│   └── utils/
│       └── logging_middleware.py       # HTTP logging with correlation IDs
├── config/
│   ├── config.py                       # Config loader (YAML + env vars)
│   ├── settings.yaml                   # Base configuration
│   ├── settings.dev.yaml               # Overrides for ENV=dev
│   └── settings.prod.yaml              # Overrides for ENV=prod
├── knowledgebase/
│   ├── loader.py                       # Loads topics.yaml (no caching)
│   └── topics.yaml                     # Knowledgebase topic definitions
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── .env.example
├── requirements.txt
├── README.md
└── CLAUDE.md

python -m venv .venv

# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

pip install -r requirements.txt

# Default (port 8000, no auth, INFO logging):
python src/server.py

# Development mode (DEBUG logging):
ENV=dev python src/server.py

# Custom port:
MCP_PORT=9000 python src/server.py

# With authentication:
AUTH_ENABLED=true AUTH_TOKEN=my-secret python src/server.py

# Production mode (auth on, WARNING logging):
ENV=prod AUTH_TOKEN=my-secret python src/server.py

# Build and start:
docker compose up --build

# With auth enabled:
AUTH_ENABLED=true AUTH_TOKEN=my-secret docker compose up --build

# Detached:
docker compose up -d

# Stop:
docker compose down

Authorization: Bearer <your-token>

# src/tools/my_tool.py
from mcp_app import mcp

@mcp.tool(name="my_tool", description="Does something useful.")
def my_tool(input: str) -> dict:
    return {"result": input.upper()}

# src/prompts/my_prompt.py
from mcp_app import mcp

@mcp.prompt(name="my_prompt", description="A focused system prompt.")
def my_prompt(context: str = "") -> str:
    return f"You are a helpful assistant. Context: {context}"

# src/resources/my_resource.py
from mcp_app import mcp

@mcp.resource("data://my-domain/my-resource")
def my_resource() -> dict:
    return {"data": "your payload here"}

topics:
  my_topic:
    title: "My Topic"
    tags: [example]
    content: |
      Topic content goes here.

# Health check:
curl http://localhost:8000/healthz

# Version:
curl http://localhost:8000/version

# With auth:
curl -H "Authorization: Bearer my-secret" http://localhost:8000/healthz

git clone <this-repo> my-mcp-server
cd my-mcp-server
claude

@CLAUDE.md Build me an MCP server that does X, Y, Z.