# 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.

## Objectives

- Understand the Model Context Protocol (MCP) architecture and how it standardizes LLM-application integration
- Build MCP servers that expose tools, resources, and prompts through a unified protocol interface
- Implement MCP clients that discover server capabilities and invoke them programmatically
- Design tool integrations that allow LLMs to execute functions with validated inputs and structured outputs
- Apply the server/client communication pattern using stdio transport for inter-process MCP messaging
- Create shared context resources that provide LLMs with access to files, system data, and dynamic information
- Develop reusable prompt templates that structure LLM interactions for consistent, high-quality outputs
- Implement security best practices including input validation, rate limiting, and path traversal prevention in MCP servers
- Configure MCP applications externally using YAML settings with environment variable overrides for deployment flexibility
- Write comprehensive test suites for MCP components covering unit, integration, and async patterns

---

## Table of Contents

- [Project Overview](#project-overview)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Dependencies](#dependencies)
- [Deployment](#deployment)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Running the Server](#running-the-server)
  - [Running the Client](#running-the-client)
  - [Running Tests](#running-tests)
- [External Configuration](#external-configuration)
  - [Settings File](#settings-file)
  - [Environment Variable Overrides](#environment-variable-overrides)
  - [Logging Configuration](#logging-configuration)
- [End-to-End Flow Diagram](#end-to-end-flow-diagram)
- [Components Reference](#components-reference)
  - [Tools](#tools)
  - [Resources](#resources)
  - [Prompts](#prompts)
- [Security](#security)
- [Contributing](#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:

```bash
python --version  # Must be 3.10+
```

### Installation

1. **Clone the repository:**

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

2. **Create a virtual environment (recommended):**

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

3. **Install the package with dependencies:**

```bash
# 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):

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
# 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:

```yaml
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:

```bash
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

```mermaid
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