How michniks2001/poke-mcp works
Project type and purpose
• This is a Python-based monolithic service plus CLI tool that provides Pokémon VGC team analysis.
• It exposes two interfaces:
• A “FastMCP” protocol server (RPC style) for integration with MCP-compatible clients.
• A FastAPI REST/web server (with static frontend) for browser-based use and REST clients.
Main components
a. Interface layers
• CLI entrypoint (main.py): accepts team files or stdin, calls the core library, prints JSON or text.
• FastMCP server (poke_mcp.server): RPC interface exposing four tools.
• FastAPI web server (poke_mcp.web_server + static/): REST API endpoints + single-page JS frontend.
b. Core library
• parsers (poke_mcp.parsers): Smogon text → Team model
• models (poke_mcp.models): Team, Pokémon data, reports
• analysis (poke_mcp.analysis): damage_calc, speed_tier, strategy_detector, team_analyzer
• services (poke_mcp.services.analysis_pipeline): orchestrates parsing, analysis, threat detection
• clients (poke_mcp.clients): fetch data from external APIs (PokeAPI, Pikalytics)
• LLM adapter (poke_mcp.llm.gemini_client): offload analysis prompts to a language model
• vectorstore (poke_mcp.vectorstore.chroma_store + data/vectorstore): cache embeddings and contexts
c. External systems
• PokeAPI
• Pikalytics
• LLM provider (Google Gemini or another endpoint)
Relationships and data flow
• CLI/FastMCP/WebServer → invoke analysis pipeline
→ Parser reads text → Team model
→ services.AnalysisPipeline calls clients & LLM & vectorstore → returns TeamReport
→ Top-level interface serializes to JSON/text/HTTP response
• Clients fetch raw data from external APIs; vectorstore persists embeddings to disk under data/vectorstore.
• WebServer also serves static/index.html + app.js for user input and result rendering.
Architectural patterns and design principles
• Layered (Ports & Adapters/Hexagonal): core logic is independent of transport (CLI, RPC, HTTP).
• Single codebase hosting multiple adapters (CLI, RPC, REST).
• Separation of concerns: parsing, domain modeling, analysis, data access, external integrations are in separate packages.
• Cache layer (vectorstore) for expensive LLM embeddings.
Technologies & frameworks to annotate
• Python 3 + standard libs
• FastAPI + Uvicorn (web REST server)
• FastMCP (RPC server module)
• Chroma DB (vectorstore)
• HTTP clients for PokeAPI/Pikalytics
• Gemini client (LLM integration)
• pytest for tests