# Python Excellence Prover MCP

> Python Excellence Prover is a code review gate that stops AI agents from shipping broken Python. It mandates industry best practices—things like using Pydantic for data validation, enforcing async I/O, and writing type-hinted code. If your agent writes something that works but violates modern standards (like using os.path or bare except), this tool catches it before you run it in production.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** python, pydantic, type-hints, code-quality, structured-reasoning, decision-pivots, async, agentic-pipeline

## Description

**validate_python_excellence** forces your agent to write Python that actually works in the real world. It acts as a mandatory gatekeeper for any AI-generated code, making sure you don't ship anything brittle or outdated just because it *looks* like it runs. You won't have to babysit your agent's output anymore; this tool handles the hard parts of keeping modern standards in place.

## Tools

### validate_python_excellence
Forces AI-generated Python to conform to modern standards: type hints, Pydantic validation, async I/O, pathlib usage, and structured error handling.

## Prompt Examples

**Prompt:** 
```
I'll parse the API response with a dict, validate manually with if-statements, catch any errors with except Exception: pass, and log with print().
```

**Response:** 
```
Verdict: TYPE_UNSAFE. Use Pydantic BaseModel for API response validation — not manual if-checks on dicts. except Exception: pass silently swallows ALL errors including SystemExit. Use specific exceptions with structlog/loguru, not print().
```

**Prompt:** 
```
OrderSchema (Pydantic) validates input. OrderService.create() uses asyncpg with DB transaction. Custom OrderError hierarchy. structlog with request context. async httpx for payment API. Generators for batch export. mypy --strict in CI.
```

**Response:** 
```
Verdict: CODE_PROVEN. Types strict (Pydantic + mypy). No workarounds. Errors typed (OrderError hierarchy + structlog). Architecture clean (Service layer + DI). Performance optimized (asyncpg, httpx async, generators). Ship it.
```

**Prompt:** 
```
I'll use os.path.join for file paths, def process(items=[]) with a mutable default, string concatenation for SQL queries, and requests.get inside an async function.
```

**Response:** 
```
Verdict: WORKAROUND_DETECTED. Four violations: (1) os.path → use pathlib.Path. (2) def f(items=[]) shares list across calls → use None default. (3) String concat for SQL → use parameterized queries. (4) requests.get blocks async → use httpx.AsyncClient.
```

## Capabilities

### Validate Data Structure Integrity
It forces external inputs (from APIs or files) through Pydantic validation models before they reach your logic.

### Enforce Type Hinting Across Codebase
The tool verifies that every function, parameter, and return value has explicit Python type hints using mypy standards.

### Audit I/O for Asynchronous Compliance
It checks that all network calls (HTTP requests, database queries) use async clients (`httpx.AsyncClient`, `asyncpg`) to prevent blocking the event loop.

### Detect Anti-Patterns and Workarounds
The tool flags common Python mistakes, like using `os.path` instead of `pathlib`, or mutable default arguments in function signatures.

### Verify Structured Error Handling
It checks for specific exception handling and structured logging, ensuring that failures are logged with context rather than being swallowed by generic `except Exception:` blocks.

## Use Cases

### Handling a complex API request
A backend engineer asks their agent to process payment data. The agent initially returns raw dictionary parsing and uses `os.path` for config files. Running the code through `validate_python_excellence` fails immediately, forcing the agent to adopt Pydantic models for validation and use `pathlib.Path` instead of manual path joining.

### Building a high-throughput data service
An ML ops engineer needs an endpoint that calls three external services (user lookup, payment gateway, inventory check). The initial code uses synchronous `requests.get()`. The Prover detects this blocking I/O and forces the agent to rewrite the entire function using `async with httpx.AsyncClient()` to handle all three calls concurrently.

### Refactoring a legacy data model
A team is integrating old code that uses global mutable state and has poorly typed functions. The Prover detects the lack of type hints and forces the agent to refactor the logic into clean, isolated Service classes with proper dependency injection (Protocol-based DI), eliminating global variables.

### Creating a robust transaction handler
The team writes payment logic that uses `try: ... except Exception: pass`. The Prover catches this error swallowing. It forces the agent to implement specific exception hierarchy (e.g., `PaymentDeclined`, `ServiceUnavailable`) and structured logging, so failures are tracked accurately.

## Benefits

- Stops runtime errors from mutable defaults. The tool flags function signatures like `def f(items=[])` because the default list gets shared across all calls, which is a major bug waiting to happen.
- Mandates structured data validation (Pydantic). Instead of manually checking if an API payload has a field, you define it once with Pydantic and gain compile-time safety checks.
- Guarantees high concurrency. It forces the use of async I/O (`httpx`, `asyncpg`) instead of blocking calls, meaning 100 requests run simultaneously instead of sequentially.
- Improves readability instantly. By enforcing `pathlib` over `os.path` and f-strings over concatenation, every future developer reading your code understands the intent immediately.
- Closes security gaps. It eliminates 'bare except' blocks that silently catch critical errors (like network timeouts or system exits), ensuring failures are logged with context.

## How It Works

The bottom line is that it acts as an automated, high-bar peer review, ensuring generated code meets professional industry standards for reliability and performance.

1. Connect your preferred AI client (Claude, Cursor, etc.) to the Python Excellence Prover MCP Server.
2. Provide the agent with a block of generated Python code that needs review. The tool then executes five distinct 'decision pivots' against this code.
3. The server returns a detailed verdict: either `CODE_PROVEN` (it passed all standards) or a list of specific violations, requiring you to fix the gaps before shipping.

## Frequently Asked Questions

**What data types does the Python Excellence Prover MCP Server validate?**
It mandates Pydantic for external data (APIs, forms) and dataclasses for internal structures. This forces you to use specific types like Decimal or UUID instead of generic strings.

**Does the validate_python_excellence tool check for async compatibility?**
Yes. It's critical for performance. The server flags any synchronous I/O (like standard `requests` calls) found inside an asynchronous function and forces the use of async libraries like `httpx`.

**How do I fix errors using the Python Excellence Prover MCP Server?**
The tool doesn't just say 'fail.' It provides a detailed report listing every violation—like missing type hints or bare except blocks. You then pass the corrected code back to your agent and try again.

**Can I use validate_python_excellence for general scripting?**
While you *can*, it's overkill if you just need a quick script. This tool is designed for complex, production-grade services where reliability and maintainability are paramount.

**How does running `validate_python_excellence` ensure my code handles large datasets without crashing due to memory limits?**
It mandates the use of generators and iterators. This mechanism ensures you process data streams chunk by chunk, keeping your memory footprint low. Never read a million rows into a list; stream the results instead.

**Does `validate_python_excellence` help prevent runtime errors from external inputs or API calls?**
Absolutely. It requires Pydantic validation for all external data sources—whether that's an API response, a form submission, or a file read. This forces type safety and catches bad input before your code even runs.

**What architectural standards does `validate_python_excellence` enforce to make my service layer clean?**
It pushes you toward solid patterns like Repository/Service layers using Protocol-based Dependency Injection. This keeps all components decoupled, making your code much easier to test and maintain over time.

**When I use `validate_python_excellence`, what specific logging standards should I follow instead of basic print() statements?**
You must implement structured logging using tools like `structlog` or `loguru`. This means every error log includes context (like user IDs or request contexts), allowing you to debug exactly what went wrong in production.

**Does it generate Python code?**
No. The agent writes the code. The tool VALIDATES that it meets senior Python standards — type hints + Pydantic, structured error handling, clean architecture, and optimized async patterns. It catches five failure modes before code is committed.

**Why is type safety checked first?**
Because untyped Python is a shell script. Without type hints, mypy can't catch bugs, IDEs can't autocomplete, and Pydantic can't validate data boundaries. Type safety is the foundation — error handling, architecture, and performance all depend on knowing what types flow through the code.

**What Python-specific anti-patterns does it catch?**
23 consistency rules catching: bare except (catches SystemExit), mutable default args (def f(x=[])), os.path instead of pathlib, string concatenation instead of f-strings, print() instead of structured logging, open() without context manager, sync I/O in async context, global mutable state, blanket # type: ignore, and magic values.