Competitive Programming Mentor MCP Server

┌──────────────────┐     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 │ │
                                           │  └────────┘ └─────────┘ │
                                           └──────────────────────────┘

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

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

# 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

# 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

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

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

claude mcp add cp-mentor uv --directory "/path/to/project" run app.py
claude   # Start a session

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)
  └─────────────┘

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

# 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

                    ┌─────────────────┐
  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

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

# 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