<p align="center">
  <h1 align="center">🏆 Competitive Programming Mentor — MCP Server</h1>
  <p align="center">
    A production-grade <strong>Model Context Protocol (MCP)</strong> server that decomposes competitive programming expertise into 23 modular, provider-independent tools — orchestrated by any MCP-compatible client.
  </p>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white" />
  <img src="https://img.shields.io/badge/MCP-FastMCP_3.x-green?logo=data:image/svg+xml;base64,PHN2Zy8+" />
  <img src="https://img.shields.io/badge/LLM-OpenAI_%7C_Ollama-orange" />
  <img src="https://img.shields.io/badge/validation-Pydantic_v2-red?logo=pydantic" />
  <img src="https://img.shields.io/badge/cache-Two--Tier-purple" />
</p>

---


[![M8ven Score](https://m8ven.ai/badge/mcp/sami-codeai-mcp-server-for-competitive-programming-6880al)](https://m8ven.ai/mcp/sami-codeai-mcp-server-for-competitive-programming-6880al)

https://m8ven.ai/mcp/sami-codeai-mcp-server-for-competitive-programming-6880al?utm_source=new_listing&utm_medium=email&utm_campaign=new_listing
https://glama.ai/mcp/servers/SAMI-CODEAI/MCP-Server-For-Competitive-Programming
## 📋 Table of Contents

- [Why MCP?](#-why-mcp)
- [Architecture](#-architecture)
- [Tool Catalog](#-tool-catalog-23-tools)
- [Project Structure](#-project-structure)
- [Getting Started](#-getting-started)
- [Configuration](#-configuration)
- [Workflows](#-workflows)
- [How It Works](#-how-it-works-deep-dive)
- [Testing](#-testing)
- [Contributing](#-contributing)

---

## 🤔 Why MCP?

Traditional AI coding assistants force all reasoning through **one massive prompt**. This approach suffers from:

| Problem | Impact |
|---------|--------|
| Monolithic prompts | Impossible to test, cache, or reuse individual capabilities |
| Provider lock-in | Switching from OpenAI → Ollama requires rewriting everything |
| No structured output | Raw text responses require fragile regex parsing |
| Redundant LLM calls | Identical problems re-analyzed every time |

**This MCP server solves all four.** Each capability is an independent tool with its own schema, prompt template, cache key, and validation pipeline.

```
┌──────────────────┐     MCP Protocol      ┌──────────────────────────┐
│  Claude Desktop  │◄─────────────────────►│   CP Mentor MCP Server   │
│  Cursor IDE      │   JSON-RPC / stdio    │                          │
│  Claude CLI      │                       │  23 Tools · 3 Resources  │
│  Any MCP Client  │                       │  3 Prompts · 2-Tier Cache│
└──────────────────┘                       └────────────┬─────────────┘
                                                        │
                                           ┌────────────▼─────────────┐
                                           │   LLM Provider Layer     │
                                           │  ┌────────┐ ┌─────────┐ │
                                           │  │ OpenAI │ │  Ollama  │ │
                                           │  │gpt-4o  │ │llama3.1 │ │
                                           │  └────────┘ └─────────┘ │
                                           └──────────────────────────┘
```

---

## 🏗 Architecture

```mermaid
graph TD
    Client["MCP Client<br/>(Cursor · Claude Desktop · CLI)"]
    Server["FastMCP Server<br/>server.py"]
    Cache{"Two-Tier Cache<br/>Memory TTL + SQLite Disk"}
    Prompt["Jinja2 Prompt Manager<br/>prompts/*.md"]
    Provider["LLM Provider Factory<br/>OpenAI | Ollama"]
    Validator{"Self-Correcting Validator<br/>Pydantic v2 Schemas"}
    Formatter["Response Formatter<br/>+ _meta tracing"]

    Client -->|"tool call (JSON-RPC)"| Server
    Server -->|"check cache"| Cache
    Cache -->|"HIT"| Formatter
    Cache -->|"MISS"| Prompt
    Prompt -->|"rendered prompt"| Provider
    Provider -->|"raw JSON"| Validator
    Validator -->|"schema fail → retry prompt"| Provider
    Validator -->|"schema pass"| Cache
    Cache -->|"store result"| Formatter
    Formatter -->|"structured response"| Client
```

### Core Design Principles

| Principle | Implementation |
|-----------|---------------|
| **Tool-Service Decoupling** | Tools contain zero business logic — they delegate to `PromptManager → Provider → Validator → Cache → Formatter` |
| **Provider Independence** | `BaseLLMProvider` abstract class ensures zero OpenAI/Ollama imports in tool code |
| **Schema-First Validation** | Every tool has a dedicated Pydantic `BaseModel` — LLM outputs are validated and auto-corrected |
| **Two-Tier Caching** | In-memory `TTLCache` (μs latency) + persistent `diskcache` (survives restarts) |
| **Fail-Safe Registration** | Each tool module is `try/except` imported — one broken tool doesn't crash the server |

---

## 🔧 Tool Catalog (23 Tools)

### 🔍 Analysis (4 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `detect_patterns` | Identifies algorithmic patterns (DP, Graph, Greedy, Math, etc.) from problem text | `PatternResponse` |
| `extract_constraints` | Parses numeric bounds (N, M, K, Q) and system limits (time/memory) | `ConstraintResponse` |
| `estimate_difficulty` | Approximates competitive programming difficulty rating | `DifficultyResponse` |
| `identify_topics` | Tags primary/secondary topic categories | `TopicsResponse` |

### 📐 Planning (4 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `suggest_algorithms` | Recommends candidate algorithms based on constraints | `AlgorithmsListResponse` |
| `compare_algorithms` | Builds a trade-off comparison matrix across candidates | `AlgorithmsComparisonResponse` |
| `choose_best_algorithm` | Selects the optimal algorithm with justification | `BestAlgorithmResponse` |
| `estimate_runtime` | Calculates operation count vs. time budget feasibility | `RuntimeEstimateResponse` |

### 💻 Code Generation (3 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `generate_solution` | Produces optimized, contest-ready code in the target language | `SolutionResponse` |
| `generate_pseudocode` | Outputs language-agnostic structural pseudocode | `PseudocodeResponse` |
| `generate_multi_language` | Generates C++, Java, and Rust implementations simultaneously | `MultiLangResponse` |

### ✅ Verification (3 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `dry_run` | Traces variable states step-by-step through sample inputs | `DryRunResponse` |
| `prove_correctness` | Provides formal correctness proofs (loop invariants, induction) | `CorrectnessProofResponse` |
| `analyze_complexity` | Computes asymptotic time/space complexity with justification | `ComplexityResponse` |

### 🧪 Testing (3 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `generate_testcases` | Creates input/output test pairs covering standard scenarios | `TestcasesResponse` |
| `generate_edge_cases` | Targets boundary conditions, zero-cases, and overflow scenarios | `EdgeCasesResponse` |
| `stress_testing` | Generates randomized brute-force stress test configurations | `StressTestResponse` |

### 🔎 Code Review (3 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `review_solution` | Full code review with correctness, efficiency, and style feedback | `ReviewResponse` |
| `find_bug` | Pinpoints logical, runtime, or compile-time bugs | `BugResponse` |
| `optimize_solution` | Suggests constant-factor and algorithmic optimizations | `OptimizationResponse` |

### 📚 Learning (3 tools)

| Tool | Description | Schema |
|------|-------------|--------|
| `get_hint` | Progressive hint system (nudge → approach → partial solution) | `HintResponse` |
| `explain_algorithm` | Educational breakdown with examples, when-to-use heuristics | `ExplanationResponse` |
| `recommend_next_problem` | Suggests follow-up problems to reinforce learned concepts | `RecommendationResponse` |

---

## 📁 Project Structure

```
Competitive Programming Mentor MCP Server/
│
├── app.py                     # Entry point — mcp.run()
├── server.py                  # FastMCP app, tool/resource/prompt registration
├── config.py                  # Pydantic-settings configuration from .env
├── pyproject.toml             # Dependencies & build config
├── .env.example               # Environment template
│
├── services/                  # Core business logic layer
│   ├── llm/
│   │   ├── base_provider.py       # Abstract LLM interface
│   │   ├── openai_provider.py     # OpenAI gpt-4o-mini adapter
│   │   ├── ollama_provider.py     # Ollama local LLM adapter
│   │   └── provider_factory.py    # Factory: .env → Provider instance
│   ├── prompt_manager.py          # Jinja2 template renderer
│   ├── validator.py               # Pydantic validation + self-correcting retry
│   ├── cache.py                   # Two-tier cache (TTLCache + diskcache)
│   ├── problem_parser.py          # Regex constraint extractor (N, M, K, Q)
│   └── formatter.py               # Response normalization + _meta tags
│
├── tools/                     # MCP tool implementations (23 tools)
│   ├── analysis/                  # detect_patterns, extract_constraints, ...
│   ├── planning/                  # suggest_algorithms, compare_algorithms, ...
│   ├── generation/                # generate_solution, generate_pseudocode, ...
│   ├── verification/              # dry_run, prove_correctness, ...
│   ├── testing/                   # generate_testcases, generate_edge_cases, ...
│   ├── review/                    # review_solution, find_bug, optimize_solution
│   └── learning/                  # get_hint, explain_algorithm, recommend_problem
│
├── schemas/                   # Pydantic response models (one per tool)
├── prompts/                   # Jinja2 markdown templates (one per tool + personas)
├── resources/                 # Static knowledge base (Markdown files)
│   ├── algorithms/graphs/         # dijkstra.md
│   ├── data_structures/           # segment_tree.md
│   └── patterns/                  # sliding_window.md
│
├── tests/                     # Pytest test suite
│   ├── test_parser.py             # Constraint parsing tests
│   ├── test_cache.py              # Two-tier cache tests
│   └── test_validator.py          # Schema validation + retry tests
│
└── docs/
    ├── ARCHITECTURE.md            # System design documentation
    └── TOOLS.md                   # Tool reference catalog
```

---

## 🚀 Getting Started

### Prerequisites

- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** (recommended) or `pip`
- **OpenAI API key** _or_ **[Ollama](https://ollama.ai)** installed locally

### Installation

```bash
# Clone the repository
git clone https://github.com/your-username/competitive-programming-mcp.git
cd competitive-programming-mcp

# Install dependencies with uv
uv sync --all-extras

# Copy and configure environment
cp .env.example .env
# Edit .env with your API keys / Ollama settings
```

### Quick Start

```bash
# Start the MCP server (stdio transport)
uv run app.py

# Or run in development mode with auto-reload
fastmcp dev app.py

# Run tests
uv run pytest
```

---

## ⚙ Configuration

All settings are managed via `.env` and loaded through **Pydantic Settings**:

```ini
# ─── LLM Provider ────────────────────────────────────
LLM_PROVIDER=openai              # "openai" or "ollama"

# ─── OpenAI (when LLM_PROVIDER=openai) ───────────────
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini         # ~$0.15/1M input tokens
OPENAI_MAX_TOKENS=4096
OPENAI_TEMPERATURE=0.2           # Low = deterministic code

# ─── Ollama (when LLM_PROVIDER=ollama) ────────────────
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b         # Run: ollama pull llama3.1:8b

# ─── Cache ────────────────────────────────────────────
CACHE_ENABLED=true
CACHE_TTL_SECONDS=3600           # 1-hour TTL
CACHE_DISK_DIR=.cache            # SQLite-backed persistent cache

# ─── Server ──────────────────────────────────────────
LOG_LEVEL=INFO                   # DEBUG | INFO | WARNING | ERROR
```

---

## 📖 Workflows

### Workflow 1: Claude Desktop Integration

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cp-mentor": {
      "command": "uv",
      "args": [
        "--directory",
        "YOUR_ABSOLUTE_PATH\\Competitive Programming Mentor MCP Server",
        "run",
        "app.py"
      ]
    }
  }
}
```

> **Note on Config Locations:**
> - Standard Windows: `%APPDATA%\Claude\claude_desktop_config.json`
> - Windows Store App: `C:\Users\YOUR_NAME\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`

Restart Claude Desktop completely. 
*Note: In the latest versions of Claude Desktop, the plug (🔌) icon has been removed from the UI. MCP tools are simply loaded silently in the background. Just ask Claude to "Use your cp-mentor tools to solve X" and you will see an approval pop-up!*

### Workflow 2: Claude CLI Integration

If you use the `claude` terminal tool, run:
```bash
claude mcp add cp-mentor uv --directory "/path/to/project" run app.py
claude   # Start a session
```

> **Important for local models:** If you are using `ollama` with the Claude CLI, make sure you launch it with a **large enough model (e.g., 9B+ parameters)** that supports tool calling. Small models (like 4B or 1B) will crash or fail to invoke MCP tools properly.
> Example: `ollama launch claude --model qwen2.5:14b`

### Workflow 3: Cursor IDE Integration

1. Open **Cursor → Settings → Features → MCP**
2. Click **+ Add New MCP Server**
3. Set **Name**: `cp-mentor`
4. Set **Type**: `command`
5. Set **Command**: `uv --directory "/path/to/project" run app.py`

### Workflow 4: Full Problem-Solving Pipeline

```
User provides a problem (e.g., LeetCode / Codeforces)
        │
        ▼
  ┌─────────────┐
  │ Step 1       │  detect_patterns(problem)
  │ Analyze      │  extract_constraints(problem)
  │              │  identify_topics(problem)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │ Step 2       │  suggest_algorithms(problem)
  │ Plan         │  compare_algorithms(problem, candidates)
  │              │  choose_best_algorithm(problem, candidates)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │ Step 3       │  generate_solution(problem, approach, language)
  │ Generate     │  generate_pseudocode(problem)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │ Step 4       │  dry_run(problem, code)
  │ Verify       │  prove_correctness(problem)
  │              │  analyze_complexity(problem, code)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │ Step 5       │  generate_testcases(problem)
  │ Test         │  generate_edge_cases(problem)
  │              │  stress_testing(problem)
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │ Step 6       │  review_solution(problem, code)
  │ Review       │  optimize_solution(problem, code)
  └─────────────┘
```

---

## 🔬 How It Works (Deep Dive)

### 1. Request Flow

When a client invokes `detect_patterns(problem="...")`, the following pipeline executes:

```
1. FastMCP receives JSON-RPC call via stdio transport
2. Tool function in tools/analysis/detect_patterns.py is invoked
3. CacheService.get("detect_patterns", {problem: "..."}) → checks memory, then disk
4. On MISS: PromptManager renders prompts/detect_patterns.md with Jinja2
5. ProviderFactory returns OpenAIProvider or OllamaProvider
6. Provider.structured_output(prompt, PatternResponse) calls the LLM API
7. Validator checks response against PatternResponse Pydantic schema
8. On validation failure: auto-correcting retry with error feedback prompt
9. CacheService.set() stores result in both memory and disk tiers
10. Formatter wraps response with _meta (tool name, model, cache status, latency)
11. Structured JSON returned to client
```

### 2. Self-Correcting Validator

The validator implements a retry loop that feeds Pydantic validation errors back to the LLM:

```python
# Simplified flow
for attempt in range(max_retries):
    raw_json = await provider.structured_output(prompt, schema)
    try:
        return schema.model_validate_json(raw_json)  # Success
    except ValidationError as e:
        prompt = f"Fix these errors: {e.errors()}\nOriginal: {raw_json}"
        # Retry with corrective context
```

### 3. Two-Tier Cache

```
                    ┌─────────────────┐
  get(key) ────────►│  Memory (TTL)   │──── HIT ────► return value
                    │  ~256 entries   │
                    │  μs latency     │
                    └───────┬─────────┘
                            │ MISS
                    ┌───────▼─────────┐
                    │  Disk (SQLite)  │──── HIT ────► promote to memory
                    │  Persistent     │               + return value
                    │  ms latency     │
                    └───────┬─────────┘
                            │ MISS
                            ▼
                    Call LLM Provider
```

Cache keys are deterministic: `f"{tool_name}:{sha256(sorted_json(inputs))[:16]}"`

### 4. Provider Abstraction

```python
class BaseLLMProvider(ABC):
    @abstractmethod
    async def generate(self, prompt: str, system: str = "") -> str: ...

    @abstractmethod
    async def structured_output(self, prompt: str, response_model: type[T], system: str = "") -> T: ...

    @property
    @abstractmethod
    def model_name(self) -> str: ...
```

- **OpenAIProvider**: Uses `client.beta.chat.completions.parse()` for native JSON schema generation
- **OllamaProvider**: Uses `openai`-compatible endpoint with regex JSON extraction fallback

---

## 🧪 Testing

```bash
# Run all tests
$env:PYTHONPATH="."    # PowerShell
uv run pytest

# Run with verbose output
uv run pytest -v

# Test specific module
uv run pytest tests/test_parser.py
uv run pytest tests/test_cache.py
uv run pytest tests/test_validator.py
```

### Test Coverage

| Module | Tests | What's Verified |
|--------|-------|----------------|
| `problem_parser` | 2 | Constraint regex parsing (including `2 * 10^5` notation), default handling |
| `cache` | 2 | Memory/disk hit/miss, tier promotion, Windows file lock cleanup |
| `validator` | 2 | Schema compliance on first try, self-correcting retry on malformed JSON |

---

## 🛠 Tech Stack

| Component | Technology | Purpose |
|-----------|-----------|---------|
| MCP Framework | `fastmcp >= 2.0` | Server SDK, tool registration, stdio transport |
| LLM Client | `openai >= 1.30` | OpenAI + Ollama-compatible API calls |
| Validation | `pydantic >= 2.7` | Typed schemas for all 23 tool outputs |
| Configuration | `pydantic-settings >= 2.3` | `.env` → typed config singleton |
| Templating | `jinja2 >= 3.1` | Prompt template rendering |
| Memory Cache | `cachetools >= 5.3` | In-memory TTL cache |
| Disk Cache | `diskcache >= 5.6` | SQLite-backed persistent cache |
| Retry Logic | `tenacity >= 8.3` | Exponential backoff for LLM API calls |
| Testing | `pytest + pytest-asyncio` | Async-compatible test framework |

---

## 📄 License

This project is provided as-is for educational and competitive programming purposes.

---

<p align="center">
  Built with 🧠 by <strong>sami_codeai</strong> — Turning competitive programming into composable AI tools.
</p>