MCP Python Server & Client

A comprehensive implementation of the Model Context Protocol (MCP) in Python, demonstrating all core MCP components including tools, resources, prompts, and transports. This project serves as both a reference implementation and a learning resource for building MCP-based applications.

---

Table of Contents

• Project Overview
• Architecture
• Project Structure
• Dependencies
• Deployment
  • Prerequisites
  • Installation
  • Running the Server
  • Running the Client
  • Running Tests
• External Configuration
  • Settings File
  • Environment Variable Overrides
  • Logging Configuration
• End-to-End Flow Diagram
• Components Reference
  • Tools
  • Resources
  • Prompts
• Security
• Contributing

---

Project Overview

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). This project implements:

• MCP Server — Exposes tools (executable functions), resources (data endpoints), and prompts (reusable templates) via the MCP protocol over stdio transport
• MCP Client — Connects to the server, discovers capabilities, and invokes tools/resources/prompts
• Full Infrastructure — Configuration management, structured logging, input validation, rate limiting, and comprehensive error handling

Key Features

• 3 tools: Calculator, String Utilities, Weather (simulated)
• 4 resources: File Reader (secure), System Info, Platform Info, File Listing
• 2 prompts: Code Review, Text Summarization
• Configurable via external YAML with environment variable overrides
• Log levels (DEBUG/INFO/WARNING/ERROR/CRITICAL) controllable via settings file
• Security hardening: path traversal prevention, input sanitization, rate limiting
• 230 automated tests (unit + integration) with pytest

---

Architecture

The project follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│  (connects via stdio, calls tools/resources/prompts)    │
└─────────────────────┬───────────────────────────────────┘
                      │ stdio transport
┌─────────────────────▼───────────────────────────────────┐
│                    MCP Server (FastMCP)                  │
├─────────────┬───────────────────┬───────────────────────┤
│   Tools     │    Resources      │      Prompts          │
│ ─────────── │ ───────────────── │ ───────────────────── │
│ Calculator  │ File Reader       │ Code Review           │
│ String Ops  │ System Info       │ Summarization         │
│ Weather     │                   │                       │
├─────────────┴───────────────────┴───────────────────────┤
│              Core Infrastructure                         │
│  Config Loader │ Logger │ Validator │ Rate Limiter      │
├─────────────────────────────────────────────────────────┤
│              Exception Hierarchy                         │
└─────────────────────────────────────────────────────────┘

---

Project Structure

ai-genai-mcp/
├── config/
│   └── settings.yaml              # All environment-specific configuration
├── src/
│   ├── __init__.py                # Package root
│   ├── config/
│   │   ├── __init__.py
│   │   └── config_loader.py       # YAML loading + Pydantic validation + env overrides
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── exceptions.py          # Custom exception hierarchy (7 types)
│   │   ├── logger.py              # Rotating file + console logging with sanitization
│   │   ├── validator.py           # Input validation and security sanitization
│   │   └── rate_limiter.py        # Token bucket rate limiter
│   ├── server/
│   │   ├── __init__.py
│   │   ├── main.py                # Server entry point and assembly
│   │   ├── tools/
│   │   │   ├── __init__.py
│   │   │   ├── calculator.py      # Math operations tool
│   │   │   ├── string_utils.py    # Text manipulation tool
│   │   │   └── weather.py         # Simulated weather API tool
│   │   ├── resources/
│   │   │   ├── __init__.py
│   │   │   ├── file_reader.py     # Secure file reading resource
│   │   │   └── system_info.py     # System metrics resource
│   │   └── prompts/
│   │       ├── __init__.py
│   │       ├── code_review.py     # Code review prompt template
│   │       └── summarization.py   # Text summarization prompt template
│   └── client/
│       ├── __init__.py
│       ├── main.py                # Client entry point
│       ├── mcp_client.py          # High-level client wrapper
│       └── interactive_demo.py    # Feature demonstration runner
├── tests/
│   ├── conftest.py                # Shared test fixtures
│   ├── unit/                      # 223 unit tests
│   │   ├── test_calculator.py
│   │   ├── test_string_utils.py
│   │   ├── test_weather.py
│   │   ├── test_file_reader.py
│   │   ├── test_system_info.py
│   │   ├── test_code_review_prompt.py
│   │   ├── test_summarization_prompt.py
│   │   ├── test_config_loader.py
│   │   ├── test_logger.py
│   │   ├── test_validator.py
│   │   ├── test_rate_limiter.py
│   │   └── test_exceptions.py
│   └── integration/               # 7 integration tests
│       └── test_client_server.py
├── pyproject.toml                 # Project metadata and dependencies
├── requirements.txt               # Production dependencies
├── requirements-dev.txt           # Development dependencies
├── .gitignore                     # Git ignore patterns
└── README.md                      # This file

---

Dependencies

Package	Version	Purpose
mcp	>=1.27.2	Official MCP SDK (server + client + transports)
pyyaml	>=6.0.2	YAML configuration file parsing
pydantic	>=2.7.0	Configuration validation and type safety
pytest	>=8.2.0	Testing framework (dev)
pytest-asyncio	>=0.23.0	Async test support (dev)
pytest-cov	>=5.0.0	Test coverage reporting (dev)
ruff	>=0.4.0	Linting and formatting (dev)

---

Deployment

Prerequisites

• Python 3.10 or higher
• pip package manager
• git (for cloning the repository)

Verify your Python version:

python --version  # Must be 3.10+

Installation

1. Clone the repository:

git clone <repository-url>
cd ai-genai-mcp

2. Create a virtual environment (recommended):

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

3. Install the package with dependencies:

# Production only
pip install -e .

# With development tools (testing, linting)
pip install -e ".[dev]"

Running the Server

Start the MCP server using stdio transport (default):

# Using the installed entry point
mcp-server

# Or using Python module syntax
python -m src.server.main

# With custom config file
python -m src.server.main --config /path/to/settings.yaml

The server will listen on stdio and is ready to accept MCP client connections.

Running the Client

The client connects to the server via stdio and runs an interactive demo:

# Using the installed entry point
mcp-client

# Or using Python module syntax
python -m src.client.main

# With custom config file
python -m src.client.main --config /path/to/settings.yaml

Running Tests

# Run all tests
python -m pytest

# Run only unit tests
python -m pytest tests/unit/ -v

# Run only integration tests
python -m pytest tests/integration/ -v

# Run with coverage report
python -m pytest tests/unit/ --cov=src --cov-report=term-missing

# Run linting
ruff check src/ tests/

---

External Configuration

Settings File

All environment-specific configuration is in config/settings.yaml. This is the single source of truth for runtime behavior. Key sections:

Section	Purpose
server	Host, port, name, transport, timeouts
client	Server URL, retries, timeouts
logging	Level, file path, rotation, format
security	Rate limits, payload limits, CORS origins
tools	Calculator precision, API URLs/keys, string limits
resources	Base directory, file size limits, allowed extensions

Environment Variable Overrides

Any YAML setting can be overridden via environment variables using the convention:

MCP_<SECTION>_<KEY>=value

Examples:

# Override log level
export MCP_LOGGING_LEVEL=DEBUG

# Override server port
export MCP_SERVER_PORT=9090

# Override rate limit
export MCP_SECURITY_RATE_LIMIT_PER_MINUTE=120

# Set weather API key (secrets should always use env vars)
export MCP_TOOLS_WEATHER_API_KEY=your-real-key-here

Environment variables take precedence over YAML file values.

Logging Configuration

Log levels are controlled via config/settings.yaml under the logging section:

logging:
  level: "INFO"          # DEBUG, INFO, WARNING, ERROR, CRITICAL
  file_path: "logs/mcp_application.log"
  max_file_size_bytes: 10485760  # 10 MB rotation
  backup_count: 5        # Keep 5 rotated files
  console_output: true   # Also print to stderr

Or override at runtime:

MCP_LOGGING_LEVEL=DEBUG python -m src.server.main

Log output is automatically sanitized — passwords, API keys, tokens, and secrets are replaced with [REDACTED] in log files.

---

End-to-End Flow Diagram

sequenceDiagram
    participant Client as MCP Client
    participant Transport as Stdio Transport
    participant Server as MCP Server
    participant Tools as Tool Handlers
    participant Resources as Resource Handlers
    participant Prompts as Prompt Handlers
    participant Config as Config Loader
    participant Validator as Input Validator
    participant RateLimiter as Rate Limiter

    Note over Config: Application Startup
    Config->>Config: Load settings.yaml
    Config->>Config: Apply env var overrides
    Config->>Config: Validate with Pydantic

    Note over Server: Server Initialization
    Server->>Config: Get server config
    Server->>Tools: Register calculator, string, weather
    Server->>Resources: Register file reader, system info
    Server->>Prompts: Register code review, summarization

    Note over Client,Server: Client Connection
    Client->>Transport: Connect via stdio
    Transport->>Server: Initialize protocol
    Server-->>Client: Server capabilities

    Note over Client,Tools: Tool Invocation
    Client->>Server: call_tool("calculate", {op: "add", a: 5, b: 3})
    Server->>RateLimiter: Check rate limit
    RateLimiter-->>Server: Allowed
    Server->>Validator: Validate inputs
    Validator-->>Server: Valid
    Server->>Tools: Execute calculator.add(5, 3)
    Tools-->>Server: Result: 8.0
    Server-->>Client: "Result: 8.0"

    Note over Client,Resources: Resource Reading
    Client->>Server: read_resource("system://info")
    Server->>Resources: Get system information
    Resources-->>Server: JSON system data
    Server-->>Client: System info JSON

    Note over Client,Prompts: Prompt Retrieval
    Client->>Server: get_prompt("code_review", {code: "...", language: "python"})
    Server->>Validator: Validate code input
    Validator-->>Server: Valid
    Server->>Prompts: Build prompt messages
    Prompts-->>Server: [system_msg, user_msg]
    Server-->>Client: Structured prompt messages

---

Components Reference

Tools

Tool	Operation	Description
calculate	add	Add two numbers
calculate	subtract	Subtract second from first
calculate	multiply	Multiply two numbers
calculate	divide	Divide first by second (guards against /0)
calculate	power	Raise base to exponent
calculate	sqrt	Square root (non-negative only)
calculate	modulo	Remainder of division
string_operation	reverse	Reverse character order
string_operation	count_words	Count words in text
string_operation	uppercase	Convert to uppercase
string_operation	lowercase	Convert to lowercase
string_operation	title_case	Capitalize first letters
string_operation	count_chars	Count letters, digits, spaces
string_operation	replace	Replace substring (extra: "old|new")
string_operation	truncate	Truncate to length with suffix
get_weather	current	Get current weather for a city
get_weather	forecast	Get 1-7 day forecast

Resources

URI	Description
system://info	Full system info (platform, Python, memory, disk, CPU)
system://platform	OS and platform details only
file://list	List available files in data directory
file://read/{path}	Read a file by relative path (security validated)

Prompts

Name	Arguments	Description
code_review	code, language, focus_areas	Generates a structured code review prompt
summarize_text	text, max_length, style	Generates a text summarization prompt

---

Security

This implementation includes multiple security layers:

• Path Traversal Prevention — File paths are resolved and validated against the base directory; ../ sequences and null bytes are blocked
• Input Sanitization — Control characters and null bytes are stripped from all external input
• Input Length Limits — Configurable maximum lengths prevent memory exhaustion
• Rate Limiting — Token bucket algorithm limits requests per client per minute
• Extension Whitelist — Only configured file extensions can be accessed
• Payload Size Limits — Maximum request payload size is enforced
• Log Sanitization — Passwords, API keys, and tokens are automatically redacted in logs
• No Dynamic Code Execution — No eval(), exec(), or dynamic imports

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (python -m pytest)
5. Ensure code passes linting (ruff check src/ tests/)
6. Commit your changes
7. Push to the branch
8. Open a Pull Request