feat(v1.5): contribution CTA + MCP server + agent docs + SVG charts + GH Pages dashboard

[howardpen9]

Layered on top of #11. Once that lands on main, this PR's base auto-rebases.

Summary

Three additive feature groups addressing real pain points uncovered while reviewing the v1 PR:

1. Backlog of 6 open relay submissions (#1, #2, #5, #6, #8, #9) shows real demand — but the contribution flow was buried in CONTRIBUTING.md with no README CTA. v1.5-A surfaces it.
2. The agent-citation strategy in v1 (llms.txt + JSON-LD + raw URLs) needed concrete integration paths for agents to actually use the data. v1.5-B ships the MCP server + a six-framework cookbook.
3. "Comparing prices is really painful" (Howard, direct quote) needs visuals, not just tables. v1.5-C ships SVG charts (in repo) + an interactive GH Pages dashboard.

A. Lower contribution friction

• README "Want your relay listed?" section (en/zh-TW/zh-CN) above the price snapshot — surfaces the issue template + PR path; sets the expectation that status: unverified is normal until canary
• Enhanced .github/PULL_REQUEST_TEMPLATE.md with the schema CI mention + an optional operator-disclosure field
• New .github/workflows/pr-validate.yml runs scripts.validate on every PR touching data/, fetchers/, scripts/, or pyproject.toml — catches typos before a human ever reads the PR

B. Agent integration layer

• mcp/ — awesome-ai-api-proxy-mcp (separate PyPI package)
  Six tools: list_providers, list_canonical_models, get_price, find_cheapest, compare, tier_overview + data://prices/latest resource. FastMCP, stdio. Branch override via AWESOME_AI_API_PROXY_REF env var for dev/staging.
  Drop in Claude Desktop / Cursor / Cline as uvx awesome-ai-api-proxy-mcp — the model picks the right tool automatically.
• docs/agent-integration.md — one-page reference for MCP / OpenAI function calling / LangChain / direct HTTP / pandas+DuckDB / n8n. Same example question (cheapest claude-sonnet-4.6) across all six paths so friction is directly comparable.
• CSV + Parquet exports in scripts/build_prices.py — data/prices.latest.csv (185KB, Excel/DuckDB-friendly) and data/prices.latest.parquet (24KB, snappy). Gated on the new [charts] optional extra.

C. Visualization

• scripts/build_charts.py generates SVG via matplotlib:
  • Tier-ladder bar chart (input + output): x = 9 canonical models grouped by tier, y = log $/1M, colored by provider, per-bar value labels, dashed tier separators
  • Cost-spread heatmap (input + output): rows × cols × log color scale with values annotated in each cell, "—" for missing
• README embeds tier-ladder-input.svg inside the prices markers — GitHub renders SVG natively + LLM screenshot tools can ingest it directly
• docs/index.html — GitHub Pages dashboard (vanilla HTML + Plotly CDN, no build step). Reads raw prices.latest.json, renders interactive grouped bars + heatmap + filterable record table. Light/dark via prefers-color-scheme. Tier + unit + free-text filter. docs/.nojekyll keeps it served raw.
  Activate via repo Settings → Pages → Source: `main` /`docs`.

Pipeline changes

The weekly price-refresh.yml workflow now installs [charts] extra and runs build_charts after build_prices, before validate. So every weekly PR includes refreshed SVGs.

Test plan

• All three fetchers still pass (3/3 fetchers, 1024 records, 47 canonical matches)
• python -m scripts.scrape && python -m scripts.build_prices && python -m scripts.build_charts && python -m scripts.validate runs clean locally
• CSV (185KB) and Parquet (24KB) generated alongside JSON
• 4 SVGs land in assets/charts/, README embeds the input ladder
• MCP server smoke-tested: find_cheapest("grok-4.3") returns Relaydance $1.125 with full provenance; compare("grok-4.3") returns 3-row sorted list; tier_overview(2) returns 3 canonical models
• Open a test PR mutating providers.yaml with a bad type → pr-validate.yml should red-light
• Enable GH Pages (Settings → Pages → main /docs) → dashboard loads at https://howardpen9.github.io/awesome-ai-api-proxy/
• Add the MCP server to a Claude Desktop config → ask a relay-pricing question → confirm the tool gets called

Out of scope (v2)

• Historical trend charts (need ≥4 weeks of snapshots)
• Canary automation against docs/canary-prompts.md
• More fetchers (UiUiAPI / Yunwu / bltcy — these will trigger ⚠ < 50% of OR)
• Triaging the 6 open backlog PRs (planned for after this merges)

🤖 Generated with Claude Code