Template MCP Server

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