mcp-replay-dota2: Skill for Claude Code

Add an MCP tool to mcp-replay-dota2

Read CLAUDE.md (repo root) first — it holds the python-manta attribute-access rules, the enum rules, the lane-naming rules, and the mandatory tests+docs+changelog policy. This skill adds the tool-specific vertical slice on top of that.

Tool vs resource

• Dynamic, parameter-required query (needs a match_id or other args) -> @mcp.tool.
• Static reference data, no params (heroes, map, pro lists) -> @mcp.resource in the dota2:// namespace (see src/resources/, registered in dota_match_mcp_server.py).

This skill is for tools. For a brand-new analysis domain (new service), use the add-replay-collector-service skill first, then come back here to expose it.

Workflow (do in this order)

1. Service method first. Put extraction logic in a service under src/services/<domain>/, not in the tool. The service must have ZERO MCP/fastmcp imports — it stays importable from CLI/web (the boundary is stated in src/services/__init__.py). Tools must contain no extraction logic; they only call services and shape the response.
2. Response model. Add or extend a Pydantic model in src/models/ (NOT src/services/models/ — those are the service-layer models). Write a Field(description=...) on every field; those descriptions become the LLM-visible schema. FastMCP auto-serializes the model — never return a raw dict.
3. Register the tool inside the correct register_<domain>_tools(mcp, services) in src/tools/<domain>_tools.py. Tools are NOT decorated at module top level — they live inside the register function so they capture services. Pull dependencies out of the dict, e.g. replay_service = services["replay_service"]. Decorate with @mcp.tool (bare, no parens — see replay_tools.py).
4. Replay tools follow this exact pattern for progress + cached parse:

   @mcp.tool
   async def get_something(match_id: int, ctx: Context) -> SomethingResponse:
       async def progress_callback(current: int, total: int, message: str) -> None:
           await ctx.report_progress(current, total)
       data = await replay_service.get_parsed_data(match_id, progress=progress_callback)
       return some_service.do_thing(data)
   

   get_parsed_data returns a cached ParsedReplayData; never call python-manta Parser directly in a tool.
5. Filtering uses the shared filter models in src/models/filters.py (DeathFilters, CombatFilters, EventFilters, FightFilters, HeroPerformanceFilters). Build with .from_params(killer=..., location=..., start_time=...) then .apply(items). Location filters accept the 37 named map regions — do not invent ad-hoc filtering.
6. New tool module? Add register_<domain>_tools to the imports and the call list in src/tools/__init__.py::register_all_tools. The six existing modules are: replay_tools, combat_tools, fight_tools, match_tools, pro_scene_tools, analysis_tools (registered in that order; ~41 tools total).
7. New service dependency? Instantiate the singleton in dota_match_mcp_server.py and add it to the services dict (~line 97). Available keys today: replay_service, combat_service, fight_service, jungle_service, lane_service, seek_service, farming_service, rotation_service, heroes_resource, pro_scene_resource, constants_fetcher, match_fetcher, pro_scene_fetcher.
8. Tool-selection instructions — update BOTH surfaces so the LLM knows when to pick the tool:
   • the TOOL_INSTRUCTIONS markdown table in dota_match_mcp_server.py, and
   • the "AI Summary - Tool Selection Guide" admonition table at the top of docs/api/tools/index.md (and bump the per-category tool count in the Categories table).
9. Docs page — add ## <tool_name> with a one-line purpose, a python call example, and a JSON Returns block, on the page matching the tool's category (see map below). Use the write-mkdocs-docs skill for the admonition/changelog conventions.
10. Real-values test under tests/<area>/ using conftest fixtures only — never parse a replay in a test. See the run-ci-and-test-replays skill.
11. CI gate — run all three before declaring done (also in CLAUDE.md):

    uv run ruff check src/ tests/ dota_match_mcp_server.py
    uv run mypy src/ dota_match_mcp_server.py --ignore-missing-imports
    uv run pytest