DPSCoach MCP Server

DPSCoach – AI-Powered Combat Log Analyzer for Throne & Liberty

DPSCoach is a desktop application and MCP toolkit that parses Throne & Liberty combat logs into actionable DPS metrics, powered by a local AI coach that answers natural-language questions about your performance using SQL-first planning and DuckDB analytics. Prototype note: class-specific context is not wired yet; the class dropdown is intentionally disabled until backend class filtering is implemented. Fair-play disclaimer: This app only reads your exported text combat logs; it does not hook, modify, or automate the game client and does not confer any in-game advantage beyond offline analytics.

🎬 Demo

TODO: Record a 30-second GIF showing: log analysis → coach question → SQL trace → answer. See docs/DEMO.md for recording instructions.

✨ Features

• AI Coach with Intent Routing: Ask "Why did my crit rate drop?" and the coach detects intent (CRIT_BUCKET_TREND, SKILL_DELTA, RUNS, etc.) and routes to deterministic handlers or LLM-planned SQL queries.
• Single-Call MCP Analysis Packet: All metrics (run summary, top skills, timeline buckets, skill deltas, windows, action levers) returned in one get_analysis_packet call—no iterative prompting required.
• DuckDB Event Store: Combat events loaded into an in-memory DuckDB table for fast, safe, read-only SQL queries via MCP tools (query_dps, get_events_schema).
• Strict Model Verification: GGUF model integrity enforced via SHA-256 hash and minimum file size checks; models downloaded on-demand to user app data (never bundled).
• Read-Only Safety: All tools are SELECT-only; no INSERT/UPDATE/DELETE/file writes. Caps on result sizes (50 runs, 200 timeline buckets) prevent resource abuse.
• Deterministic Fallbacks: If the LLM misbehaves, the coach falls back to a safe default query and still produces an answer—never displays instructions to "use Quick Questions."
• PySide6 Desktop UI: Native Windows app with tabbed views (Summary, Runs, Skills, Coach) and background workers for non-blocking analysis.
• PyInstaller One-Click Build: Ships as a standalone EXE with Python runtime and all dependencies (except the GGUF model, which downloads on first launch).
• Class Context (coming soon): UI shows class dropdown today; backend class-filtered analysis will land in the next iteration.
• Fair Play: Reads UTF-8 combat log files only; no game hooks, memory reads, packet interception, or automation.

🏗️ Architecture

┌──────────────┐
│  PySide6 UI  │  (main.py)
│  (Desktop)   │
└──────┬───────┘
       │ QPushButton clicks
       ▼
┌──────────────────┐
│   SQLCoach       │  (coach_local.py)
│   Intent Router  │  ─ Detects RUNS, SKILLS, CRIT_BUCKET_TREND, etc.
│   + LLM Planner  │  ─ Plans SQL or returns deterministic answer
└──────┬───────────┘
       │ MCP client calls
       ▼
┌──────────────────┐
│  MCP Client      │  (mcp_client.py)
│  (Subprocess)    │  ─ Spawns `python -m mcp_server`
└──────┬───────────┘
       │ stdio JSON-RPC
       ▼
┌──────────────────┐
│  MCP Server      │  (mcp_server.py, FastMCP)
│  + DuckDB Store  │  ─ analyze_dps_logs, query_dps, get_analysis_packet
│  (event_store)   │  ─ Safe SELECT templates, no mutations
└──────┬───────────┘
       │ read logs
       ▼
┌──────────────────┐
│  Combat Logs     │  (UTF-8 .txt/.log files)
│  (TL SAVED dir)  │
└──────────────────┘

Key Design Choices:

• MCP as the contract boundary: UI and coach communicate via MCP tools, ensuring the same payload shape for CLI, desktop, and future integrations.
• Intent-first routing: Deterministic handlers (90% of questions) bypass the LLM entirely, guaranteeing consistent formatting and trace clarity.
• DuckDB instead of pandas: In-memory SQL engine enables ad-hoc queries without shipping raw events to the UI; query results are capped and safe.

🔒 Safety Guarantees

• Read-Only Tools: query_dps enforces SELECT-only via AST parse; INSERT/UPDATE/DELETE raise exceptions.
• Clamped Parameters: last_n_runs limited to [1, 50], top_k_skills to [1, 50], bucket_seconds coerced to allowed values (1, 2, 5, 10, 15, 30, 60).
• No File Writes in Tools: The MCP server never writes files; all outputs go to stdout (CLI) or returned as JSON (tools).
• Model Integrity: GGUF files must pass SHA-256 hash and minimum size checks before loading; corrupt or tampered models are rejected.
• Deterministic Self-Test: Model must respond "OK" to a trivial prompt before the UI enables the coach chat.

🎯 Engineering Signals (for hiring managers)

This project demonstrates professional software engineering practices suitable for production systems:

1. **Contract-Driven Design**