LLM-Infra-Advisor-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Project Is

infra-advisor-mcp is a FastMCP server that estimates GPU requirements, training/inference costs, and cloud vs. on-prem TCO for AI workloads. It exposes ~11 MCP tools backed entirely by deterministic Python calculators — no LLM is invoked for arithmetic. All pricing data lives in YAML files under src/infra_advisor/data/.

Commands

# Install (editable, with dev extras)
pip install -e ".[dev]"

# Run all tests
pytest

# Run a single test file
pytest tests/test_calculators.py

# Run a single test by name
pytest tests/test_tools.py::test_generate_full_report_returns_markdown

# Lint
ruff check src/ tests/

# Run the MCP server (stdio transport — used by Claude Code)
infra-advisor
# NOTE: After editing any .py file, the MCP server process must be fully restarted
# (Claude Code Settings → MCP → restart) for changes to take effect in the live tool.
# YAML-only changes can use the reload_data MCP tool without a full restart.

# Sync cloud pricing from AWS/GCP/Azure APIs
python scripts/sync_cloud_pricing.py --auto

# Check provider pricing pages (OpenAI, Anthropic, etc.) — scrape + flag for manual review
python scripts/sync_provider_pricing.py

# Reload YAML data without restarting the server
# Use the reload_data MCP tool, or call infra_advisor.data_loader.reload_all() directly

Architecture

src/infra_advisor/
├── server.py          # FastMCP entry point — registers all MCP tools as @mcp.tool()
├── data_loader.py     # lru_cache-based YAML loaders; reload_all() clears caches
├── data/              # gpu_specs.yaml, model_registry.yaml, cloud_pricing.yaml
├── calculators/       # Pure math, no I/O
│   ├── compute.py     # Training FLOPs via 6·N·D; Chinchilla scaling; GPU-hour estimation
│   ├── memory.py      # VRAM estimation for inference and training
│   └── tco.py         # Cloud vs. on-prem monthly cost; break-even; token cost
└── tools/             # MCP tool implementations — call calculators + format output
    ├── analyze.py     # Keyword classifier → TaskAnalysis Pydantic model
    ├── recommend.py   # Scores model_registry entries → ranked ModelRecommendation list
    ├── training.py    # Wraps compute.py + data_loader → TrainingCostEstimate
    ├── inference.py   # Loops over model_registry pricing → InferenceCostEstimate
    ├── compare.py     # Wraps tco.py → TCOResult
    ├── maintenance.py # Detailed on-prem opex breakdown → MaintenanceCostEstimate
    ├── report.py      # Orchestrates all tools → full markdown report (generate_full_report)
    └── followup.py    # Focused single-question answer with inline glossary