Template MCP Server

Description

A production-ready template for developing Model Context Protocol (MCP) servers using Python and FastMCP. This server provides a foundation for creating MCP-compliant servers with comprehensive examples of tools, structured logging, configuration management, and containerized deployment.

The template includes three example MCP tools: a multiply calculator, a code review prompt generator, and a Red Hat logo resource handler. It demonstrates best practices for MCP server development including proper error handling, health checks, multiple transport protocols (HTTP, SSE, streamable-HTTP), SSL support, and comprehensive development tooling.

Architecture

System Architecture

Control Flow

Code Structure

Key Components

• main.py: Application entry point with configuration validation, error handling, and uvicorn server startup

• api.py: FastAPI application setup with transport protocol selection (HTTP/SSE/streamable-HTTP) and health endpoints

• mcp.py: Core MCP server class that registers tools using FastMCP decorators

• settings.py: Environment-based configuration using Pydantic BaseSettings with validation

• tools/: MCP tool implementations demonstrating arithmetic, prompts, and resource access patterns

• utils/pylogger.py: Structured JSON logging using structlog with comprehensive processors

Current MCP Tools

1. multiply_numbers: Demonstrates basic arithmetic operations with error handling

2. read_redhat_logo_content: Shows resource access patterns with base64 encoding

3. get_code_review_prompt: Illustrates prompt generation for code analysis

How to Run the Code Locally

Prerequisites

• Python 3.12 or higher

• uv (fast Python package installer and resolver)

Setup

1. Install uv (if not already installed):

   # On macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh # On MacOS using brew brew install uv # On Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Or with pip: pip install uv

2. Clone the repository:

   git clone https://github.com/redhat-data-and-ai/template-mcp-server cd template-mcp-server

3. Create and activate a virtual environment with uv:

   uv venv # Activate the virtual environment: # On macOS/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate

4. Install the package and dependencies:

   # Install in editable mode with all dependencies uv pip install -e .

5. Configure environment variables:

   cp .env.example .env # Edit .env file with your configuration

6. Run the server:

   # Using the installed console script template-mcp-server # Or directly with Python module python -m template_mcp_server.src.main # Or using uv to run directly uv run python -m template_mcp_server.src.main

Configuration Options

The server configuration is managed through environment variables:

Using Podman

1. Build and run with Podman Compose:

   podman-compose up --build

2. Or build manually:

   podman build -t template-mcp-server . podman run -p 3000:3000 --env-file .env template-mcp-server

Verify Installation

1. Health check:

   curl http://localhost:3000/health

2. Test MCP tools:

   # Test multiply tool via MCP endpoint curl -X POST "http://localhost:3000/mcp" \ -H "Content-Type: application/json" \ -d '{"method": "tools/call", "params": {"name": "multiply_numbers", "arguments": {"a": 5, "b": 3}}}'

How to Test the Code Locally

Development Environment Setup

1. Install development dependencies:

   uv pip install -e ".[dev]"

2. Install pre-commit hooks:

   pre-commit install

Running Tests

The project includes a comprehensive test suite with 81+ tests covering unit tests, integration tests, and various edge cases.

1. Run all tests:

   pytest

2. Run tests with coverage reporting:

   pytest --cov=template_mcp_server --cov-report=html --cov-report=term

3. Run tests by category:

   # Unit tests only pytest -m unit # Integration tests only pytest -m integration # Slow running tests pytest -m slow # Tests requiring network access pytest -m network

4. Run specific test modules:

   # Test individual components pytest tests/test_multiply_tool.py -v pytest tests/test_redhat_logo.py -v pytest tests/test_code_review_prompt.py -v pytest tests/test_settings.py -v pytest tests/test_mcp_server.py -v # Run integration tests pytest tests/test_integration.py -v

5. Run tests with different output formats:

   # Verbose output with detailed test names pytest -v # Short traceback format pytest --tb=short # Quiet output (minimal) pytest -q

Code Quality Checks

1. Linting and formatting with Ruff:

   # Check for issues ruff check . # Auto-fix issues ruff check . --fix # Format code ruff format .

2. Type checking with MyPy:

   mypy template_mcp_server/

3. Docstring validation:

   pydocstyle template_mcp_server/ --convention=google

4. Run all pre-commit checks:

   pre-commit run --all-files

Test Suite Overview

The project includes a comprehensive test suite with the following structure:

Test Files:

• test_multiply_tool.py - 12 tests covering arithmetic operations, edge cases, error handling

• test_redhat_logo.py - 10 tests covering async file operations, base64 encoding, error scenarios

• test_code_review_prompt.py - 14 tests covering prompt generation, multiple languages, formatting

• test_settings.py - 20 tests covering configuration, environment variables, validation

• test_mcp_server.py - 15 tests covering server initialization, tool registration, error handling

• test_integration.py - 10 tests covering complete workflows and system integration

Test Features:

• ✅ Comprehensive error handling validation

• ✅ Async function testing support

• ✅ Mock external dependencies

• ✅ Environment isolation with fixtures

• ✅ Performance testing for large data

• ✅ Concurrent usage simulation

• ✅ Configuration validation testing

Manual Testing

1. Container testing:

   docker-compose up -d curl -f http://localhost:3000/health docker-compose down

2. SSL testing (if configured):

   curl -k https://localhost:3000/health

Continuous Integration & Deployment

This project uses GitHub Actions for automated CI/CD workflows to ensure code quality, security, and reliability.

CI/CD Workflows

CI Pipeline Features

✅ Code Quality Assurance:

• Multi-Python version testing (3.12, 3.13)

• Comprehensive test suite execution (81+ tests)

• Code coverage reporting (80%+ requirement)

• Ruff linting and formatting validation

• MyPy type checking

• Docstring validation with pydocstyle

✅ Security & Compliance:

• Bandit security linting

• Safety dependency vulnerability scanning

✅ Automation & Maintenance:

• Dependabot configuration for automated dependency updates

• Pre-commit hook automation

• Weekly security audits

• Automated PR creation for dependency updates

Running CI Checks Locally

Before pushing code, run the same checks that CI runs:

Branch Protection

The main branch is protected with the following requirements:

• All CI checks must pass

• Pull request reviews required

• Up-to-date branches required

• No direct pushes to main

How to Contribute

Development Workflow

1. Fork and clone:

   git fork <repository-url> git clone <your-fork-url> cd template-mcp-server

2. Create feature branch:

   git checkout -b feature/your-feature-name

3. Set up development environment:

   uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ".[dev]" pre-commit install

4. Make changes following our standards

5. Run comprehensive testing:

   # Code quality ruff check . --fix ruff format . mypy template_mcp_server/ # Tests pytest --cov=template_mcp_server # Pre-commit validation pre-commit run --all-files

6. Commit and push:

   git add . git commit -m "feat: descriptive commit message" git push origin feature/your-feature-name

7. Create Pull Request

Coding Standards

• Python Style: Follow PEP 8 (enforced by Ruff)

• Type Annotations: Required for all public functions and methods

• Documentation: Google-style docstrings for all public APIs

• Testing: Write tests for new functionality with pytest

• Commits: Use conventional commit format (feat:, fix:, docs:, etc.)

• Error Handling: Use structured logging and proper exception handling

Adding New MCP Tools

1. Create tool module:

   # template_mcp_server/src/tools/your_tool.py async def your_tool_function(param: str) -> dict: """Your tool description. Args: param: Parameter description. Returns: dict: Result dictionary. """ # Implementation here return {"result": "success"}

2. Register in MCP server:

   # In template_mcp_server/src/mcp.py from template_mcp_server.src.tools.your_tool import your_tool_function def _register_mcp_tools(self) -> None: self.mcp.tool()(your_tool_function) # Add this line

3. Add tests:

   # tests/test_your_tool.py import pytest from template_mcp_server.src.tools.your_tool import your_tool_function @pytest.mark.asyncio async def test_your_tool(): result = await your_tool_function("test_param") assert result["result"] == "success"

4. Update documentation

Adding New Resources

1. Place assets in: template_mcp_server/src/tools/assets/

2. Create resource handler in: template_mcp_server/src/tools/

3. Register in: template_mcp_server/src/mcp.py

4. Add tests and documentation

Code Review Guidelines

• All changes require pull request review

• Automated checks must pass (tests, linting, type checking)

• Documentation should be updated for user-facing changes

• Breaking changes require discussion and versioning consideration

Getting Help

• Issues: Open GitHub issues for bugs or feature requests

• Discussions: Use GitHub Discussions for questions

• Documentation: Check existing docs and code examples

• Testing: Provide minimal reproduction cases for bugs