aviciot/mcp-server-template-base

Modular MCP Server Template

This repository provides a batteries-included starting point for building Model Context Protocol (MCP) services with FastMCP. It ships with a production-style server, automatic module discovery, an opinionated configuration system, and a sample client that exercises the stack end to end.

Highlights

• FastMCP HTTP server powered by Starlette and Uvicorn.
• Automatic discovery of tools, resources, and prompts inside the server package (toggle with AUTO_DISCOVER).
• Environment driven configuration backed by server/config/settings.yaml with sensible defaults.
• Graceful shutdown and optional JSON logging for container friendly deployments.
• Sample Oracle tuning prompt and resources that demonstrate structured prompt construction.
• Client example (client/check_query.py) that calls the server, fetches resources, invokes prompts, and streams results through Groq.
• Docker ready: compose stack brings up the server and demo client with a single command.

Project Layout

.
|-- client/
|   |-- check_query.py          # Example FastMCP client + Groq workflow
|   |-- requirements.txt        # Client dependencies
|   |-- Dockerfile              # Client container
|   `-- query_reports/          # Generated analysis artifacts
|-- server/
|   |-- server.py               # Entrypoint, HTTP app, auto-discovery
|   |-- mcp_app.py              # Shared FastMCP instance
|   |-- config.py               # Settings loader (env + YAML)
|   |-- config/settings.yaml    # Default configuration template
|   |-- tools/                  # Example tools (hello, math, remote bridge)
|   |-- resources/              # Example resources (server info, documents)
|   |-- prompts/                # Example prompts (Oracle tuning)
|   |-- requirements.txt        # Server dependencies
|   `-- Dockerfile              # Server container
|-- docker-compose.yml          # Local orchestration for server + client
|-- .env                        # Runtime configuration (not committed)
`-- .gitignore

Prerequisites

• Docker and Docker Compose (for the quickest start)
• Python 3.11+ if you plan to run the server or client directly on your machine
• Groq API access (only required for the demo client)

Getting Started with Docker

1. Copy .env.example to .env (or create .env) and fill in the relevant values, notably GROQ_API_KEY if you plan to run the sample client.
2. Build and launch the stack:

   docker-compose up --build
   

3. Once both services are healthy, explore the server:

   curl http://localhost:9002/healthz
   curl http://localhost:9002/_info
   

4. In another terminal, execute the demo client inside its container:

   docker-compose exec client python check_query.py
   

   The client fetches tuning rules from the MCP server, generates prompts, calls Groq for analysis, and writes summaries to client/query_summary.csv plus detailed markdown reports in client/query_reports/.

Stop the stack with docker-compose down when you are finished.

Running Locally (Optional)

If you prefer to run the components without Docker:

# Server
cd server
python -m venv .venv && .venv\Scripts\activate  # adjust for your shell
pip install -r requirements.txt
uvicorn server:app --host 0.0.0.0 --port 9002

# Client (new terminal)
cd client
python -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt
python check_query.py

Make sure the .env file is available in both directories so the scripts can read matching configuration.

Configuration

The server reads its settings from environment variables (optionally expanded through server/config/settings.yaml). Key values include:

Update .env (or your deployment secrets manager) before running the stack. The configuration loader falls back to environment values if the YAML file is missing.

Adding New MCP Components

1. Tools – drop a new function in server/tools/ and decorate it with @mcp.tool(). When AUTO_DISCOVER is enabled, the module is picked up automatically on restart.

   # server/tools/hello_tool.py
   from mcp_app import mcp
   
   @mcp.tool()
   def hello(name: str) -> str:
       return f"Hello, {name}!"
   

2. Resources – define read-only data sources with @mcp.resource("protocol://path") inside server/resources/.

3. Prompts – return formatted strings (or message structures) using @mcp.prompt() in server/prompts/. The included Oracle tuning prompt is a good starting point for structured LLM interactions.

Restart the server (or let Uvicorn reload) and the new components are available immediately to connected clients.

Demo Client Workflow

client/check_query.py illustrates how to:

• Connect to the server using fastmcp.Client over HTTP.
• Retrieve server resources (oracle://tuning/rules).
• Request prompts (oracle_query_tuning_prompt) and forward them to Groq.
• Parse model output, summarise key findings, and write reports.

Use it as a reference when wiring the server into your own applications or agent frameworks.

Extending the Template

• Replace the sample prompt/resource logic with your own domain knowledge.
• Mount or proxy additional MCP services by enabling the remote server block in settings.yaml.
• Add authentication middleware to server/server.py to protect endpoints in production.
• Instrument logging/metrics exporters as needed for your deployment environment.

License

Released under the MIT License. See LICENSE (add one if required) for details.