llmledger-mcp 0.1.0__tar.gz

llmledger_mcp-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# ── private, never public ──────────────────────────────────────────────
+# Study notes, career context, working notes. First rule in the file
+# because it is the one that must never fail.
+notes/
+
+# ── data: ALLOW-LIST, never a deny-list ───────────────────────────────
+# A deny-list of extensions fails on the next file type you invent.
+# Everything under data/ is ignored except the one marker that keeps
+# the directory in git. The upstream litellm clone also lands here
+# (data/upstream/), so it is covered by this rule and needs no other.
+data/*
+!data/.gitkeep
+
+# ── secrets ───────────────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+secrets/
+
+# ── Python ────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+
+# ── macOS ─────────────────────────────────────────────────────────────
+.DS_Store
+site/

llmledger_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pouriaetab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llmledger_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: llmledger-mcp
+Version: 0.1.0
+Summary: Which AI model, and what it costs: LiteLLM prices, Arena ratings and price history, inside Claude and other AI apps.
+Project-URL: Homepage, https://pouriaetab.github.io/llmledger/
+Project-URL: Source, https://github.com/pouriaetab/llmledger/tree/main/mcp
+Project-URL: Issues, https://github.com/pouriaetab/llmledger/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastmcp,litellm,llm,mcp,model selection,pricing
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: fastmcp==4.1.0
+Description-Content-Type: text/markdown
+
+# llmledger-mcp
+
+<!-- mcp-name: io.github.pouriaetab/llmledger -->
+
+Ask Claude (or Cursor, ChatGPT desktop, any app that speaks MCP) which AI model to use and what it
+costs, in the middle of your work. The answers come from [llmledger](https://pouriaetab.github.io/llmledger/):
+LiteLLM's public price catalogue, Arena's ratings by task, and every price change since 2023 with how
+likely a price is to change next. Rebuilt every day.
+
+## Install
+
+Needs [uv](https://docs.astral.sh/uv/). Nothing to host and no keys: the plug-in runs on your computer
+and reads the day's data from the llmledger page, cached for a day, with a bundled copy for offline use.
+
+Claude Code:
+
+```bash
+claude mcp add llmledger -- uvx llmledger-mcp
+```
+
+Claude Desktop (Settings, Developer, Edit config) or Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "llmledger": { "command": "uvx", "args": ["llmledger-mcp"] }
+  }
+}
+```
+
+A LiteLLM proxy can offer it to a whole team through its MCP gateway, as a stdio server with the same
+command.
+
+## What you can ask
+
+| Tool | For example |
+|---|---|
+| `suggest_for_project` | "Which model and effort for this project?" with the starting prompt; `pay` can be `claude` or `chatgpt` to compare within a plan |
+| `compare_models` | "Opus 5.5 or Fable 5.1 for coding, and when is Fable cheaper?" |
+| `estimate_cost` | "What do 2,000 calls a day of 10K tokens in and 1K out cost on these three?" |
+| `find_models` | "The best rated coding models under $10 per 1M answer tokens that read images" |
+| `price_history` | "Has Claude Opus 5.5's price changed, and how likely is it to change soon?" |
+
+Plus a resource, `llmledger://snapshot` (data dates and sources), and a prompt, `pick_a_model`.
+
+## Good to know
+
+- Costs and ratings are estimates. Arena ratings say which answers people preferred, not what will work
+  best for you. Plan use (Claude, ChatGPT) assumes a plan runs down in step with API prices, because
+  plans do not publish per-model limits. Not financial or procurement advice.
+- Effort levels come from LiteLLM; the suggested level is a rule of thumb. No open source measures
+  tokens per task at each effort level yet.
+- Set `LLMLEDGER_DATA` to a local data.json or another address to use your own copy.
+
+## Data and licences
+
+Prices: LiteLLM's `model_prices_and_context_window.json` (MIT). Ratings: the Arena leaderboard
+(CC BY 4.0). Price history and outlook: [llmledger](https://github.com/pouriaetab/llmledger) (MIT).
+Built with [FastMCP](https://github.com/PrefectHQ/fastmcp) (Apache-2.0). Independent; not affiliated
+with BerriAI, LiteLLM or Arena.

llmledger_mcp-0.1.0/README.md

@@ -0,0 +1,60 @@
+# llmledger-mcp
+
+<!-- mcp-name: io.github.pouriaetab/llmledger -->
+
+Ask Claude (or Cursor, ChatGPT desktop, any app that speaks MCP) which AI model to use and what it
+costs, in the middle of your work. The answers come from [llmledger](https://pouriaetab.github.io/llmledger/):
+LiteLLM's public price catalogue, Arena's ratings by task, and every price change since 2023 with how
+likely a price is to change next. Rebuilt every day.
+
+## Install
+
+Needs [uv](https://docs.astral.sh/uv/). Nothing to host and no keys: the plug-in runs on your computer
+and reads the day's data from the llmledger page, cached for a day, with a bundled copy for offline use.
+
+Claude Code:
+
+```bash
+claude mcp add llmledger -- uvx llmledger-mcp
+```
+
+Claude Desktop (Settings, Developer, Edit config) or Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "llmledger": { "command": "uvx", "args": ["llmledger-mcp"] }
+  }
+}
+```
+
+A LiteLLM proxy can offer it to a whole team through its MCP gateway, as a stdio server with the same
+command.
+
+## What you can ask
+
+| Tool | For example |
+|---|---|
+| `suggest_for_project` | "Which model and effort for this project?" with the starting prompt; `pay` can be `claude` or `chatgpt` to compare within a plan |
+| `compare_models` | "Opus 5.5 or Fable 5.1 for coding, and when is Fable cheaper?" |
+| `estimate_cost` | "What do 2,000 calls a day of 10K tokens in and 1K out cost on these three?" |
+| `find_models` | "The best rated coding models under $10 per 1M answer tokens that read images" |
+| `price_history` | "Has Claude Opus 5.5's price changed, and how likely is it to change soon?" |
+
+Plus a resource, `llmledger://snapshot` (data dates and sources), and a prompt, `pick_a_model`.
+
+## Good to know
+
+- Costs and ratings are estimates. Arena ratings say which answers people preferred, not what will work
+  best for you. Plan use (Claude, ChatGPT) assumes a plan runs down in step with API prices, because
+  plans do not publish per-model limits. Not financial or procurement advice.
+- Effort levels come from LiteLLM; the suggested level is a rule of thumb. No open source measures
+  tokens per task at each effort level yet.
+- Set `LLMLEDGER_DATA` to a local data.json or another address to use your own copy.
+
+## Data and licences
+
+Prices: LiteLLM's `model_prices_and_context_window.json` (MIT). Ratings: the Arena leaderboard
+(CC BY 4.0). Price history and outlook: [llmledger](https://github.com/pouriaetab/llmledger) (MIT).
+Built with [FastMCP](https://github.com/PrefectHQ/fastmcp) (Apache-2.0). Independent; not affiliated
+with BerriAI, LiteLLM or Arena.

llmledger_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llmledger-mcp"
+version = "0.1.0"
+description = "Which AI model, and what it costs: LiteLLM prices, Arena ratings and price history, inside Claude and other AI apps."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["mcp", "llm", "pricing", "litellm", "model selection", "fastmcp"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["fastmcp==4.1.0"]
+
+[project.scripts]
+llmledger-mcp = "llmledger_mcp.server:main"
+
+[project.urls]
+Homepage = "https://pouriaetab.github.io/llmledger/"
+Source = "https://github.com/pouriaetab/llmledger/tree/main/mcp"
+Issues = "https://github.com/pouriaetab/llmledger/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llmledger_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/llmledger_mcp", "tests", "scripts", "README.md", "LICENSE", "server.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

llmledger_mcp-0.1.0/scripts/snapshot.py

@@ -0,0 +1,20 @@
+"""Refresh the data snapshot bundled in the package (used only before the first download).
+Run before each build: python scripts/snapshot.py [path or address of data.json]"""
+import gzip
+import json
+import sys
+import urllib.request
+from pathlib import Path
+
+SOURCE = sys.argv[1] if len(sys.argv) > 1 else "https://pouriaetab.github.io/llmledger/data.json"
+DEST = Path(__file__).parent.parent / "src" / "llmledger_mcp" / "snapshot.json.gz"
+
+if SOURCE.startswith("http"):
+    with urllib.request.urlopen(urllib.request.Request(SOURCE, headers={"User-Agent": "llmledger-mcp"}), timeout=60) as r:
+        body = r.read()
+else:
+    body = Path(SOURCE).read_bytes()
+data = json.loads(body)
+assert data.get("schema") == 1 and len(data["models"]) > 100, "not a llmledger data.json"
+DEST.write_bytes(gzip.compress(json.dumps(data, separators=(",", ":")).encode(), 9, mtime=0))
+print(f"{DEST.name}: {len(data['models']):,} models, built {data['built']}, {DEST.stat().st_size // 1024} KB")

llmledger_mcp-0.1.0/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pouriaetab/llmledger",
+  "description": "Which AI model, and what it costs: LiteLLM prices, Arena ratings and price history.",
+  "repository": {
+    "url": "https://github.com/pouriaetab/llmledger",
+    "source": "github",
+    "subfolder": "mcp"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "llmledger-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

llmledger_mcp-0.1.0/src/llmledger_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""llmledger-mcp: which AI model, and what it costs, inside Claude and other AI apps."""
+__version__ = "0.1.0"

llmledger_mcp-0.1.0/src/llmledger_mcp/__main__.py

@@ -0,0 +1,3 @@
+from llmledger_mcp.server import main
+
+main()

llmledger_mcp-0.1.0/src/llmledger_mcp/data.py

@@ -0,0 +1,107 @@
+"""The day's data: downloaded once a day from the llmledger page into a cache folder, so the
+plug-in works offline from the last copy, with a snapshot bundled in the package for the
+very first run. Standard library only."""
+import gzip
+import json
+import os
+import re
+import tempfile
+import time
+import urllib.request
+from importlib import resources
+from pathlib import Path
+
+URL = "https://pouriaetab.github.io/llmledger/data.json"
+MAX_AGE = 24 * 3600
+
+
+def cache_file():
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "llmledger-mcp" / "data.json"
+
+
+def _download(url, dest):
+    request = urllib.request.Request(url, headers={"User-Agent": "llmledger-mcp"})
+    with urllib.request.urlopen(request, timeout=20) as response:
+        body = response.read()
+    json.loads(body)                                    # a broken download never replaces a good copy
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(dir=dest.parent, delete=False) as f:
+        f.write(body)
+    os.replace(f.name, dest)
+
+
+def _bundled():
+    return json.loads(gzip.decompress(resources.files("llmledger_mcp").joinpath("snapshot.json.gz").read_bytes()))
+
+
+def load(now=None):
+    """(data, where it came from). LLMLEDGER_DATA may name a local file or another address."""
+    override = os.environ.get("LLMLEDGER_DATA", "")
+    if override and not re.match(r"https?://", override):
+        return json.loads(Path(override).read_text()), "file " + override
+    url, dest = override or URL, cache_file()
+    now = now or time.time()
+    fresh = dest.exists() and now - dest.stat().st_mtime < MAX_AGE
+    if not fresh:
+        try:
+            _download(url, dest)
+            fresh = True
+        except Exception:                               # offline or the page is down: use what we have
+            pass
+    if dest.exists():
+        try:
+            return json.loads(dest.read_text()), "downloaded" if fresh else "the last download (could not refresh it)"
+        except ValueError:
+            pass
+    return _bundled(), "the copy bundled with this version"
+
+
+class Shelf:
+    """The data, indexed: models by listing and by grouped name, ratings by task."""
+
+    def __init__(self, data, where=""):
+        self.data, self.where, self.loaded = data, where, time.time()
+        self.models = [m for m in data["models"]]
+        self.by_key = {m["key"]: m for m in self.models}
+        self.groups = {}
+        for m in self.models:
+            self.groups.setdefault(m["maker"] + " / " + m["name"], []).append(m)
+        ratings = data.get("ratings") or {}
+        self.labels = dict(ratings.get("labels") or [])
+        self.ratings = ratings.get("tasks") or {}
+        self.rating_date = ratings.get("date", "")
+
+    @staticmethod
+    def norm(text):
+        text = str(text).lower()
+        text = re.sub(r"(\d)[-_p](?=\d(?![\d.bkm]))", r"\1.", text)   # 4-5 and 4p5 are versions: 4.5
+        return re.sub(r"[-_:/@\s]+", " ", re.sub(r"(?<!\d)\.|\.(?!\d)", " ", text)).strip()
+
+    def resolve(self, name):
+        """The grouped name ("maker / name") for what a person typed, or a list of close ones."""
+        if name in self.groups:
+            return name, []
+        if name in self.by_key:
+            m = self.by_key[name]
+            return m["maker"] + " / " + m["name"], []
+        want = self.norm(name)
+        exact = [g for g in self.groups if self.norm(g) == want or self.norm(g.split(" / ", 1)[1]) == want]
+        if exact:
+            return exact[0], []
+        words = want.split()
+        close = [g for g in self.groups
+                 if all(any(t.startswith(w) for t in self.norm(g + " " + " ".join(m["key"] for m in self.groups[g])).split())
+                        for w in words)]
+        if len(close) == 1:
+            return close[0], []
+        close.sort(key=lambda g: (-self.rating_of("overall", g)[2] if self.rating_of("overall", g) else 0, len(g)))
+        return None, close[:8]
+
+    def rating_of(self, task, group):
+        return next((r for r in self.ratings.get(task, []) if r[0] == group), None)
+
+    def rank_of(self, task, group, priced):
+        rows = [r for r in self.ratings.get(task, []) if r[0] in priced]
+        ids = [r[0] for r in rows]
+        return (ids.index(group) + 1 if group in ids else None), len(ids)

llmledger_mcp-0.1.0/src/llmledger_mcp/logic.py

@@ -0,0 +1,301 @@
+"""The page's own logic, in Python, for the plug-in: the task guess (route.js), prompt cost
+(cost.js) and the side-by-side comparison (pick.js). Pure functions; no network, no FastMCP.
+
+The task rules are copied from route.js; tests/test_mcp_logic.py in the repo checks that both
+give the same answers. Python reads word boundaries next to accented letters a little more
+generously than JavaScript does, so a rare prompt in Spanish, French or German can differ.
+"""
+import math
+import re
+
+# ---------- task guess (route.js) ----------
+# task: (strong pattern, its flags, weak pattern, its flags); a strong match counts 2, a weak one 1.
+RULES = {
+    "webdev": ("\\b(html|css|tailwind|react|next\\.js|nextjs|vue|svelte|landing page|web ?page|website|web app|frontend|front-end)\\b", "i",
+        "\\b(navbar|button|layout|responsive|dom|jsx|tsx)\\b", "i"),
+    "coding": ("```|\\b(python|javascript|typescript|java|c\\+\\+|c#|golang|rust|kotlin|swift|flutter|php|ruby|bash|powershell|sql|regex|numpy|pandas|pytorch|tensorflow|django|flask|fastapi|node\\.?js|npm|docker\\w*|kubernetes|git|github|api|json|yaml|code|coding|script|function|debug|refactor|compile\\w*|stack ?trace|traceback|exception|bug|algorithm|leetcode|unit test|programm\\w*|linux|ubuntu|terminal|excel formula|vba)\\b|(\\bdef |\\bimport |console\\.log|#include|public static|=>|!=|==|\\w+\\(\\)\\s*[{;:]|[{};]\\s*$|\\bSELECT\\b[\\s\\S]*\\bFROM\\b)|(код|программ|функци|скрипт|代码|程序|函数|编程|コード|プログラム|関数|코드|프로그램|함수|programowa\\w*|\\bkod\\w*|funkcj\\w*|código|programa\\w*|fonction|Programmier\\w*|پایتون|کد)", "im",
+        "\\b(variable|loop|array|class|method|library|install\\w*|error|server|database|query|plugin|app|framework|sdk|cpu|gpu|windows|version|command|config\\w*|network|router)\\b", "i"),
+    "math": ("\\b(solve|equation|integral|derivative|prove|proof|theorem|lemma|probability|calculus|algebra|geometry|matrix|matrices|eigen\\w*|polynomial|logarithm|factorial|combinatorics|arithmetic)\\b|\\\\(frac|int|sum|sqrt)|\\d\\s*[\\^×÷]\\s*\\d|\\b\\d+\\s*[+\\-*\\/]\\s*\\d+\\s*=", "i",
+        "\\b(calculate|compute|how many|how long|percent\\w*|average|mean|median|standard deviation|variance|sum of|formula|area of|volume of|limit|next number|x\\s*=|f\\(x\\))\\b|\\d+\\s*%|(\\d+\\s*,\\s*){3,}|(数学|方程|计算|概率|確率|計算|수학|방정식|matemat\\w*|oblicz\\w*|równani\\w*|вычисл\\w*|уравнени\\w*|задач\\w*)", "i"),
+    "creative_writing": ("\\b(story|stories|poem|poetry|lyrics|song|novel|fiction|fanfic\\w*|screenplay|script for a|haiku|limerick|sonnet|fairy tale|roleplay|role-play|role play|role playing)\\b|(小说|故事|诗|歌词|рассказ|стих\\w*|песн\\w*|сказк\\w*|opowiada\\w*|wiersz\\w*|piosenk\\w*|histoire|poème|chanson|Geschichte|Gedicht|cuento|poema|canción|小説|物語|이야기|소설)", "i",
+        "\\b(character|plot|chapter|scene|scenario|imagine|creative|narrat\\w*|villain|hero|speech|toast|slogan)\\b", "i"),
+    "legal": ("\\b(lawsuit|attorney|lawyer|contract|legal|statute|court|plaintiff|defendant|gdpr|liabilit\\w*|clause)\\b", "i",
+        "\\b(law|rights|regulation|compliance|tenant|landlord)\\b", "i"),
+    "medicine": ("\\b(symptom\\w*|diagnos\\w*|medication|dosage|clinical|patient|disease|treatment|doctor|surgery|pregnan\\w*|vaccine)\\b", "i",
+        "\\b(health|pain|medical|drug|therapy|blood|nutrition)\\b", "i"),
+    "business": ("\\b(marketing|revenue|profit|startup|business plan|investor|pricing strategy|sales funnel|kpi|roi|invoice|accounting|financial statement|stock market|valuation)\\b", "i",
+        "\\b(business|customer|budget|finance|company|market|sales|brand|product)\\b", "i"),
+    "science": ("\\b(physics|chemistry|biology|molecule|quantum|thermodynamic\\w*|photosynthesis|dna|genome|neuron|astronom\\w*|hypothesis|experiment)\\b", "i",
+        "\\b(atom|energy|cell|evolution|climate|species|planet|element)\\b", "i"),
+    "writing": ("\\b(essay|proofread|rewrite|rephrase|paraphrase|summari[sz]e|grammar|cover letter|resume|email to|draft an? (email|letter))\\b", "i",
+        "\\b(email|letter|article|blog|tone|wording|sentence|paragraph)\\b", "i"),
+    "media": ("\\b(movie|film|tv show|series|anime|manga|album|football|soccer|basketball|nba|nfl|olympic\\w*|video game|celebrity)\\b", "i",
+        "\\b(music|sport\\w*|game|actor|singer|team|season|episode)\\b", "i")
+}
+LABELS = {
+    "overall": "Everything (overall)",
+    "coding": "Coding",
+    "math": "Math",
+    "creative_writing": "Creative writing",
+    "instruction_following": "Following detailed instructions",
+    "hard_prompts": "Hard prompts",
+    "longer_query": "Long prompts",
+    "multi_turn": "Long conversations",
+    "expert": "Expert questions",
+    "business": "Business and finance",
+    "legal": "Legal and government",
+    "medicine": "Medicine and health",
+    "science": "Science",
+    "software": "Software and IT",
+    "writing": "Writing and literature",
+    "media": "Entertainment, sports and media",
+    "chinese": "In Chinese",
+    "french": "In French",
+    "german": "In German",
+    "japanese": "In Japanese",
+    "korean": "In Korean",
+    "russian": "In Russian",
+    "spanish": "In Spanish",
+    "vision": "Understanding images",
+    "document": "Understanding documents",
+    "webdev": "Building websites and apps"
+}
+ORDER = ["webdev", "coding", "math", "creative_writing", "legal", "medicine", "science", "business", "writing", "media"]
+TASKS = list(LABELS)
+LANGUAGES = [
+    ("japanese", r"[\u3040-\u30ff]"),
+    ("korean", r"[\uac00-\ud7af]"),
+    ("chinese", r"[\u4e00-\u9fff]"),
+    ("russian", r"[\u0400-\u04ff]"),
+    ("spanish", r"[ñ¿¡]|\b(el|los|las|que|por|para|una|con|del|es|está|cómo|qué|puedes|necesito)\b"),
+    ("french", r"[çœ]|\b(les|des|est|une|pour|dans|avec|qui|pas|je|vous|c'est|n'est|qu'il)\b"),
+    ("german", r"ß|\b(der|die|das|und|ist|nicht|mit|ein|eine|ich|sie|auf|für|über|wie|bitte)\b"),
+]
+SCRIPTS = ("japanese", "korean", "chinese", "russian")
+ENGLISH = re.compile(r"\b(the|and|is|are|to|of|you|what|how|with|for|this|that|in)\b", re.I)
+
+
+def _flags(text):
+    return (re.I if "i" in text else 0) | (re.M if "m" in text else 0)
+
+
+_COMPILED = {task: (re.compile(s, _flags(sf)), re.compile(w, _flags(wf))) for task, (s, sf, w, wf) in RULES.items()}
+_LANG = [(name, re.compile(p, 0 if name in SCRIPTS else re.I)) for name, p in LANGUAGES]
+
+
+def language(text):
+    """A language with its own Arena task, or None. Writing systems decide Japanese, Korean,
+    Chinese and Russian; Spanish, French and German need 3 or more of their common words,
+    and more than English ones."""
+    english = len(ENGLISH.findall(text))
+    best = None
+    for name, pattern in _LANG:
+        hits = sum(1 for _ in pattern.finditer(text))
+        if name in SCRIPTS:
+            if hits >= 5:
+                return name
+            continue
+        if hits >= 3 and hits > english and (best is None or hits > best[1]):
+            best = (name, hits)
+    return best[0] if best else None
+
+
+def _score(text, task):
+    found, points = [], 0
+    for pattern, weight in zip(_COMPILED[task], (2, 1)):
+        for m in pattern.finditer(text):
+            points += weight
+            word = m.group(0).strip().lower()
+            if len(found) < 4 and word not in found:
+                found.append(word)
+    return points, found
+
+
+def guess_task(text, images=0, pages=0):
+    """The Arena task a prompt most likely belongs to: {task, why, language}."""
+    text = str(text or "")
+    if pages > 0:
+        return {"task": "document", "why": ["a PDF is attached"], "language": language(text)}
+    if images > 0:
+        return {"task": "vision", "why": ["an image is attached"], "language": language(text)}
+    best = None
+    for task in ORDER:
+        points, found = _score(text, task)
+        if points >= 2 and (best is None or points > best[1]):
+            best = (task, points, found)
+    lang = language(text)
+    if best:
+        return {"task": best[0], "why": best[2], "language": lang}
+    if lang:
+        return {"task": lang, "why": ["written in " + lang.capitalize()], "language": lang}
+    return {"task": "overall", "why": ["no clear task"], "language": lang}
+
+
+# ---------- prompt cost (cost.js) ----------
+CHARS_PER_TOKEN = 4
+TEXT_MODES = ("chat", "responses", "completion")
+NOT_TEXT = re.compile(r"embed|rerank|flux|diffusion|sdxl|controlnet|dall-e|imagen|whisper|tts")
+ANSWERS = {"short": 250, "medium": 800, "long": 2000, "very_long": 6000}
+
+
+def estimate_tokens(text):
+    return math.ceil(len(str(text or "")) / CHARS_PER_TOKEN)
+
+
+def is_text_model(model):
+    return model.get("mode") in TEXT_MODES and not NOT_TEXT.search(str(model.get("key", "")).lower())
+
+
+def cost_of(model, input_tokens, output_tokens, cached_tokens=0):
+    """Dollars for one call: prompt tokens at the input price (the cached part at the cache
+    read price when the model lists one), answer tokens at the output price. None if unpriced."""
+    if model.get("input") is None or model.get("output") is None:
+        return None
+    cached = min(max(cached_tokens, 0), input_tokens)
+    cache_price = model.get("cache_read")
+    if cache_price is None:
+        cache_price, cached = model["input"], cached
+    return ((input_tokens - cached) * model["input"] + cached * cache_price + output_tokens * model["output"]) / 1e6
+
+
+# ---------- compare side by side (pick.js) ----------
+LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"]
+HARD_TASKS = ("coding", "webdev", "math", "hard_prompts", "expert", "software", "science")
+DEEP = re.compile(r"\b(architect\w*|design\w*|from scratch|refactor\w*|debug\w*|root cause|prove|proof|optimi[sz]\w*|"
+                  r"migrat\w*|security|concurren\w*|race condition|trade-?offs?|specification|multi-?step|end to end|production)\b", re.I)
+LIGHT = re.compile(r"\b(summari[sz]e|translate|rewrite|rephrase|proofread|typos?|reformat|format|short|quick(ly)?|one line|"
+                   r"tl;?dr|classify|extract)\b", re.I)
+SCORE_LEVEL = ["low", "medium", "high", "high", "xhigh", "max"]
+
+
+def clamp(level, levels):
+    """The closest level a model takes: the nearest one below, else the lowest one above."""
+    if not levels:
+        return None
+    if level in levels:
+        return level
+    at = LEVELS.index(level)
+    for i in range(at, -1, -1):
+        if LEVELS[i] in levels:
+            return LEVELS[i]
+    return next((x for x in levels if LEVELS.index(x) > at), levels[0])
+
+
+def suggest_effort(text, task, levels, prompt_tokens, fallback=""):
+    """A suggested effort level: a rule of thumb from the task and the prompt's words and length."""
+    if not levels:
+        return {"level": None, "why": []}
+    text = str(text or "")
+    if not text.strip():
+        return {"level": fallback if fallback in levels else None, "why": []}
+    why, score = [], 1
+    if task in HARD_TASKS:
+        score += 1
+        why.append("a task where thinking helps")
+    deep = DEEP.search(text)
+    light = None if deep else LIGHT.search(text)
+    if deep:
+        score += 2
+        why.append('it asks for "' + deep.group(0).lower() + '"')
+    if light:
+        score -= 1
+        why.append('it asks for "' + light.group(0).lower() + '"')
+    tokens = prompt_tokens or 0
+    if tokens > 8000:
+        score += 2
+        why.append("a very long prompt")
+    elif tokens > 2000:
+        score += 1
+        why.append("a long prompt")
+    elif tokens < 40 and not deep:
+        score -= 1
+        why.append("a short prompt")
+    level = SCORE_LEVEL[max(0, min(len(SCORE_LEVEL) - 1, score))]
+    return {"level": clamp(level, levels), "why": why}
+
+
+def plan_multiples(costs):
+    """How fast each choice uses a plan compared with the one that uses it least (assumes a
+    plan runs down in step with API prices)."""
+    known = [c for c in costs if c is not None and c > 0]
+    if not known:
+        return [None for _ in costs]
+    least = min(known)
+    return [None if c is None or c <= 0 else c / least for c in costs]
+
+
+def tied(a, b):
+    """The votes cannot tell two ratings apart: their 95% ranges overlap."""
+    return a["high"] >= b["low"] and b["high"] >= a["low"]
+
+
+def best_pick(rows):
+    """Among the choices tied with the highest rated, the cheapest; without ratings, the cheapest."""
+    priced = [r for r in rows if r.get("cost") is not None]
+    if not priced:
+        return None
+    rated = [r for r in priced if r.get("rating") is not None]
+    if not rated:
+        return min(priced, key=lambda r: r["cost"])
+    top = max(rated, key=lambda r: r["rating"])
+    return min((r for r in rated if tied(r, top)), key=lambda r: r["cost"])
+
+
+def _times(x):
+    return (f"{x:.1f}" if x < 10 else f"{x:.0f}") + "×"
+
+
+def _percent(x):
+    return f"{round(100 * x)}%"
+
+
+def headline(rows, plan=False):
+    """One sentence on which to pick, and why (as the page says it)."""
+    pick = best_pick(rows)
+    if pick is None:
+        return ""
+    priced = [r for r in rows if r.get("cost") is not None]
+    if len(priced) < 2:
+        return "Add a model to compare with " + pick["name"] + "."
+    rated = [r for r in priced if r.get("rating") is not None]
+    top = max(rated, key=lambda r: r["rating"]) if rated else None
+    least = min(priced, key=lambda r: r["cost"])
+    light = "lightest on your plan" if plan else "cheapest"
+    if top is None:
+        return pick["name"] + " is the " + light + " here; none of these is rated for this task."
+    if pick is top and pick is least:
+        return pick["name"] + " is the pick: the highest rated here, and the " + light + "."
+    if pick is top:
+        return (pick["name"] + " is the pick: the highest rated here. The ones that "
+                + ("use less of the plan" if plan else "cost less") + " are rated lower.")
+    return (pick["name"] + " is the pick: the votes cannot tell it apart from the highest rated, " + top["name"]
+            + ", and it " + ("uses less of the plan" if plan else "costs less") + ".")
+
+
+def versus(r, pick, plan=False):
+    """A short note on one choice against the pick, with the break-even share of answer tokens."""
+    if pick is None or r is pick or r.get("cost") is None or not (pick.get("cost") or 0) > 0:
+        return ""
+    ratio = r["cost"] / pick["cost"]
+    name = pick["name"]
+    if plan:
+        if ratio >= 1.05:
+            line = "Uses the plan " + _times(ratio) + " as fast as " + name
+        elif ratio <= 0.95:
+            line = "Uses " + ("1/" + str(round(1 / ratio)) + " as much" if ratio <= 0.1 else _percent(1 - ratio) + " less") + " of the plan than " + name
+        else:
+            line = "Uses the plan at about the same rate as " + name
+    else:
+        if ratio >= 1.05:
+            line = "Costs " + _times(ratio) + " as much as " + name
+        elif ratio <= 0.95:
+            line = "Costs " + ("1/" + str(round(1 / ratio)) + " as much as " if ratio <= 0.1 else _percent(1 - ratio) + " less than ") + name
+        else:
+            line = "Costs about the same as " + name
+    k = r["out"] / pick["out"] if (r.get("out") or 0) > 0 and (pick.get("out") or 0) > 0 else None
+    if k is not None and 0.1 < k < 10 and abs(k - 1) >= 0.05:
+        if k > 1:
+            line += "; it only " + ("uses less" if plan else "costs less") + " if it needs under " + _percent(1 / k) + " of the answer tokens"
+        else:
+            line += "; it stays " + ("lighter" if plan else "cheaper") + " unless it needs over " + _times(1 / k) + " the answer tokens"
+    return line + "."

llmledger_mcp-0.1.0/src/llmledger_mcp/server.py

@@ -0,0 +1,313 @@
+"""llmledger as a plug-in (an MCP server) for Claude and other AI apps.
+
+Five tools answer "which model, and what will it cost?" from the same data as the llmledger
+page: LiteLLM's price catalogue (MIT), Arena's ratings (CC BY 4.0), and every price change
+since 2023 with how likely a price is to change next. Runs on the user's own computer over
+stdio; reads the day's data.json, cached for a day.
+"""
+import time
+from typing import Annotated, Literal
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from llmledger_mcp import __version__, data, logic
+
+Task = Literal[tuple(logic.TASKS)]
+Pay = Literal["api", "claude", "chatgpt"]
+Need = Literal["vision", "pdf", "audio", "video", "tools", "reasoning", "web", "schema", "cache", "computer"]
+PLANS = {"claude": ("anthropic", "anthropic", "Claude"), "chatgpt": ("openai", "openai", "ChatGPT")}
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, open_world_hint=False)
+PLAN_NOTE = ("Plan use is an estimate: plans do not publish per-model limits, so it assumes a plan runs down "
+             "in step with each model's API price on the maker's own host.")
+EFFORT_NOTE = ("The effort level is a rule of thumb from the task and the prompt. Higher effort writes more hidden "
+               "answer tokens, and no open source measures how many yet.")
+
+mcp = FastMCP(
+    "llmledger",
+    instructions=(
+        "Which AI model to use, and what it costs. Prices come from LiteLLM's public catalogue, quality from "
+        "Arena's votes, and each price's full history from llmledger. Use suggest_for_project for 'which model "
+        "for this', compare_models to put 2 to 6 models side by side, estimate_cost for a budget, find_models to "
+        "browse, and price_history for one model. Costs and ratings are estimates; pass on the credits line."),
+    version=__version__,
+)
+
+_SHELF = None
+
+
+def shelf():
+    """The data, loaded once and refreshed after a day."""
+    global _SHELF
+    if _SHELF is None or time.time() - _SHELF.loaded > data.MAX_AGE:
+        _SHELF = data.Shelf(*data.load())
+    return _SHELF
+
+
+def footer(s):
+    d = s.data
+    return {"data": {"built": d.get("built"), "litellm_changed": (d.get("litellm") or {}).get("changed"),
+                     "ratings_published": s.rating_date, "copy": s.where},
+            "credits": d.get("credits")}
+
+
+def listing(s, group, plan=None, input_tokens=0, output_tokens=0, needs=(), min_context=None):
+    """The listing a grouped model is priced at: its cheapest text listing, or on a plan the plan's own host."""
+    best = None
+    for m in s.groups.get(group, []):
+        if not logic.is_text_model(m) or (plan and m["host"] != PLANS[plan][1]):
+            continue
+        if any(n not in (m.get("skills") or []) for n in needs):
+            continue
+        if min_context and not (m.get("context") or 0) >= min_context:
+            continue
+        cost = logic.cost_of(m, input_tokens, output_tokens)
+        if cost is not None and (best is None or cost < best[1]):
+            best = (m, cost)
+    return best
+
+
+def prices(m):
+    return {"input": m["input"], "output": m["output"], "cache_read": m.get("cache_read"), "unit": "dollars per 1M tokens"}
+
+
+def money(x):
+    return None if x is None else float(f"{x:.6g}")
+
+
+def resolve_all(s, names):
+    groups, missing = [], []
+    for name in names:
+        group, close = s.resolve(name)
+        if group is None:
+            missing.append(f"{name!r}" + (" (did you mean " + ", ".join(close[:5]) + "?)" if close else ""))
+        elif group not in groups:
+            groups.append(group)
+    if missing:
+        raise ToolError("Not found: " + "; ".join(missing) + ". Use find_models to see the names.")
+    return groups
+
+
+def task_label(task):
+    return logic.LABELS.get(task, task)
+
+
+@mcp.tool(annotations=READ_ONLY)
+def find_models(
+    task: Annotated[Task, Field(description="The kind of work, as Arena rates it")] = "overall",
+    max_output_price: Annotated[float | None, Field(description="Highest answer price, dollars per 1M tokens", ge=0)] = None,
+    min_context: Annotated[int | None, Field(description="Smallest prompt size the model must take, in tokens", ge=0)] = None,
+    needs: Annotated[list[Need], Field(description="What the model must be able to do")] = [],
+    maker: Annotated[str | None, Field(description="Only this maker, for example anthropic or openai")] = None,
+    limit: Annotated[int, Field(ge=1, le=20)] = 5,
+) -> dict:
+    """The highest rated models for a kind of work that meet the limits, each at its cheapest listing,
+    with prices per 1M tokens, Arena rating and prompt size. Unrated models follow, cheapest first."""
+    s = shelf()
+    found = {}
+    for group in s.groups:
+        if maker and not group.lower().startswith(maker.lower().strip() + " / "):
+            continue
+        hit = listing(s, group, needs=needs, min_context=min_context)
+        if hit and (max_output_price is None or hit[0]["output"] <= max_output_price):
+            found[group] = hit[0]
+    rated = [r for r in s.ratings.get(task, []) if r[0] in found]
+    rows = [{"model": r[0], "listing": found[r[0]]["key"], "host": found[r[0]]["host"],
+             "rating": {"score": r[2], "low": r[3], "high": r[4], "rank": i + 1, "of": len(rated)},
+             "price_per_1m": prices(found[r[0]]), "prompt_size": found[r[0]].get("context"),
+             "effort_levels": found[r[0]].get("effort")} for i, r in enumerate(rated[:limit])]
+    if len(rows) < limit:
+        rest = sorted((g for g in found if g not in {r[0] for r in rated}), key=lambda g: found[g]["output"])
+        rows += [{"model": g, "listing": found[g]["key"], "host": found[g]["host"], "rating": None,
+                  "price_per_1m": prices(found[g]), "prompt_size": found[g].get("context"),
+                  "effort_levels": found[g].get("effort")} for g in rest[:limit - len(rows)]]
+    return {"task": task_label(task), "matching_models": len(found), "rated_for_task": len(rated), "models": rows,
+            **footer(s)}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def compare_models(
+    models: Annotated[list[str], Field(description="2 to 6 model names, for example claude-opus-5.5, gpt-6.1-sol", min_length=2, max_length=6)],
+    task: Annotated[Task, Field(description="The kind of work, as Arena rates it")] = "overall",
+    input_tokens: Annotated[int, Field(description="Prompt tokens per task", ge=0)] = 1000,
+    output_tokens: Annotated[int, Field(description="Answer tokens per task, including hidden thinking", ge=0)] = 800,
+    answer_tokens: Annotated[dict[str, int] | None, Field(description="Answer tokens per model when they differ, by the names given")] = None,
+    pay: Annotated[Pay, Field(description="api: dollars; claude or chatgpt: how fast each uses that plan")] = "api",
+) -> dict:
+    """Two to six models side by side for a kind of work: rating, prices, cost per task (or plan use), and
+    which to pick, with the break-even share of answer tokens for each against the pick."""
+    s = shelf()
+    groups = resolve_all(s, models)
+    own = {}
+    for name, n in (answer_tokens or {}).items():
+        group, _ = s.resolve(name)
+        if group:
+            own[group] = n
+    plan = pay if pay in PLANS else None
+    rows = []
+    for group in groups:
+        hit = listing(s, group, plan)
+        m = hit[0] if hit else None
+        out = own.get(group, output_tokens)
+        cost = logic.cost_of(m, input_tokens, out) if m else None
+        r = s.rating_of(task, group)
+        rows.append({"name": group.split(" / ", 1)[1], "model": group, "listing": m["key"] if m else None,
+                     "host": m["host"] if m else None, "rating": r[2] if r else None, "low": r[3] if r else None,
+                     "high": r[4] if r else None, "cost": cost, "out": m["output"] if m else None,
+                     "answer_tokens": out, "m": m})
+    pick = logic.best_pick(rows)
+    use = logic.plan_multiples([r["cost"] for r in rows])
+    table = []
+    for r, u in zip(rows, use):
+        m = r["m"]
+        row = {"model": r["model"], "listing": r["listing"], "host": r["host"],
+               "rating": None if r["rating"] is None else {"score": r["rating"], "low": r["low"], "high": r["high"]},
+               "price_per_1m": prices(m) if m else None, "answer_tokens": r["answer_tokens"],
+               "cost_per_task": money(r["cost"]), "effort_levels": m.get("effort") if m else None,
+               "versus_pick": logic.versus(r, pick, bool(plan)) or None}
+        if plan:
+            row["plan_use"] = None if u is None else round(u, 2)
+            if not m:
+                row["note"] = "Not listed on " + PLANS[plan][1]
+        table.append(row)
+    return {"task": task_label(task), "pick": pick["model"] if pick else None,
+            "headline": logic.headline(rows, bool(plan)), "models": table,
+            "notes": [PLAN_NOTE] if plan else [], **footer(s)}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def estimate_cost(
+    models: Annotated[list[str], Field(description="1 to 10 model names", min_length=1, max_length=10)],
+    input_tokens: Annotated[int, Field(description="Prompt tokens per call", ge=0)],
+    output_tokens: Annotated[int, Field(description="Answer tokens per call, including hidden thinking", ge=0)],
+    cached_tokens: Annotated[int, Field(description="How many of the prompt tokens are read from the cache", ge=0)] = 0,
+    calls_per_day: Annotated[float, Field(description="Calls per day", ge=0)] = 1,
+) -> dict:
+    """What a workload costs on each model at its cheapest listing: per call, per day and per 30 days."""
+    s = shelf()
+    rows = []
+    for group in resolve_all(s, models):
+        hit = listing(s, group, input_tokens=input_tokens, output_tokens=output_tokens)
+        if not hit:
+            rows.append({"model": group, "note": "no text price listed"})
+            continue
+        m = hit[0]
+        call = logic.cost_of(m, input_tokens, output_tokens, cached_tokens)
+        rows.append({"model": group, "listing": m["key"], "host": m["host"], "price_per_1m": prices(m),
+                     "per_call": money(call), "per_day": money(call * calls_per_day),
+                     "per_30_days": money(call * calls_per_day * 30),
+                     "cache_priced": cached_tokens > 0 and m.get("cache_read") is not None})
+    rows.sort(key=lambda r: r.get("per_call") if r.get("per_call") is not None else float("inf"))
+    return {"models": rows, **footer(s)}
+
+
+def _value(field, v):
+    if isinstance(v, (int, float)) and not isinstance(v, bool) and ("per_token" in field or "token_cost" in field):
+        return money(v * 1e6)
+    return v
+
+
+@mcp.tool(annotations=READ_ONLY)
+def price_history(
+    model: Annotated[str, Field(description="A model name, for example claude-opus-5.5, or one listing such as bedrock/anthropic.claude-opus-5-5")],
+) -> dict:
+    """Every change to a model's listings since 2023 (prices, retirement dates), and for listings that have not
+    changed yet, the chance of a price change, a retirement date or removal in the next 90 days and year."""
+    s = shelf()
+    if model in s.by_key:
+        keys = [model]
+        group = s.by_key[model]["maker"] + " / " + s.by_key[model]["name"]
+    else:
+        group = resolve_all(s, [model])[0]
+        keys = [m["key"] for m in sorted(s.groups[group], key=lambda m: m.get("last_change") or "", reverse=True)][:10]
+    out = []
+    for key in keys:
+        m = s.by_key[key]
+        events = [{"day": e[0], "change": e[1], "field": e[2] or None, "before": _value(e[2], e[3]),
+                   "after": _value(e[2], e[4]), "flag": e[5] or None} for e in s.data["events"].get(key, [])]
+        out.append({"listing": key, "host": m["host"], "added": m.get("added") or "before Sept 2023",
+                    "retirement_date": m.get("retire") or None, "price_per_1m": prices(m),
+                    "price_changes": m.get("price_changes"), "changes": events, "outlook": m.get("outlook")})
+    return {"model": group, "listings": out, "listings_in_total": len(s.groups[group]),
+            "notes": ["Prices per 1M tokens. A flag marks a bulk clean up, a unit fix or a change that was undone.",
+                      "The outlook covers listings that have not changed since they were added: Aalen-Johansen estimates "
+                      "with 95% intervals, among listings of the same age. What usually happens in the catalogue, not a "
+                      "forecast for one model."], **footer(s)}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def suggest_for_project(
+    prompt: Annotated[str, Field(description="The project's starting prompt, or a description of the work")],
+    pay: Annotated[Pay, Field(description="api: dollars; claude or chatgpt: compare within that plan")] = "api",
+    answer: Annotated[Literal["short", "medium", "long", "very_long"], Field(description="Typical answer length")] = "medium",
+) -> dict:
+    """Reads a prompt, guesses its kind of work, and suggests a model and effort level: the best value (the
+    cheapest whose rating the votes cannot tell apart from the top), the top rated and the cheapest rated."""
+    s = shelf()
+    guess = logic.guess_task(prompt)
+    task = guess["task"] if s.ratings.get(guess["task"]) else "overall"
+    plan = pay if pay in PLANS else None
+    tokens_in, tokens_out = logic.estimate_tokens(prompt), logic.ANSWERS[answer]
+    rows = []
+    for r in s.ratings.get(task, []):
+        if plan and not r[0].startswith(PLANS[plan][0] + " / "):
+            continue
+        hit = listing(s, r[0], plan, tokens_in, tokens_out)
+        if hit:
+            rows.append({"name": r[0].split(" / ", 1)[1], "model": r[0], "m": hit[0], "cost": hit[1],
+                         "rating": r[2], "low": r[3], "high": r[4], "out": hit[0]["output"]})
+    if not rows:
+        raise ToolError("No rated model matches; try pay='api'.")
+    best = logic.best_pick(rows)
+    top = max(rows, key=lambda r: r["rating"])
+    low = min(rows, key=lambda r: r["cost"])
+    picks = [("best value", best), ("top rated", top), ("cheapest rated", low)]
+    shown, seen = [], set()
+    use = logic.plan_multiples([r["cost"] for _, r in picks])
+    for (role, r), u in zip(picks, use):
+        if r["model"] in seen:
+            continue
+        seen.add(r["model"])
+        m = r["m"]
+        effort = logic.suggest_effort(prompt, task, m.get("effort"), tokens_in, m.get("effort_default") or "")
+        item = {"role": role, "model": r["model"], "listing": m["key"], "host": m["host"],
+                "rating": {"score": r["rating"], "low": r["low"], "high": r["high"],
+                           "rank": rows.index(r) + 1, "of": len(rows)},
+                "cost_per_task": money(r["cost"]), "price_per_1m": prices(m),
+                "effort": effort["level"], "effort_why": effort["why"] or None,
+                "versus_pick": logic.versus(r, best, bool(plan)) or None}
+        if plan:
+            item["plan_use"] = None if u is None else round(u, 2)
+        shown.append(item)
+    notes = [EFFORT_NOTE] + ([PLAN_NOTE] if plan else [])
+    return {"task": task_label(task), "why": guess["why"], "prompt_tokens": tokens_in, "answer_tokens": tokens_out,
+            "headline": logic.headline([r for _, r in picks], bool(plan)),
+            "picks": shown, "rated_models_considered": len(rows), "notes": notes, **footer(s)}
+
+
+@mcp.resource("llmledger://snapshot", mime_type="application/json")
+def snapshot() -> dict:
+    """What the plug-in knows today: data dates, how many models and rated tasks, and the sources."""
+    s = shelf()
+    return {"models_listed": len(s.models), "grouped_models": len(s.groups),
+            "rated_tasks": {k: len(v) for k, v in s.ratings.items()}, "tasks": logic.LABELS, **footer(s)}
+
+
+@mcp.prompt
+def pick_a_model(work: str) -> str:
+    """Pick a model for a piece of work, with its cost and effort."""
+    return ("Use the llmledger tools to pick an AI model for this work:\n\n" + work + "\n\n"
+            "1. Call suggest_for_project with the work as the prompt.\n"
+            "2. Call compare_models with its three picks and the task it returned.\n"
+            "3. Answer in five lines or fewer: the pick, its cost per task, the effort level, the runner up and why, "
+            "and the credits line.")
+
+
+def main():
+    mcp.run(show_banner=False)
+
+
+if __name__ == "__main__":
+    main()

llmledger_mcp-0.1.0/tests/fixture.json

@@ -0,0 +1,40 @@
+{"schema": 1, "built": "2026-10-16T12:00:00+00:00",
+ "litellm": {"commit": "abc", "changed": "2026-10-15T00:00:00+00:00"},
+ "credits": {"prices": "LiteLLM (MIT)", "ratings": "Arena (CC BY 4.0)", "note": "Not financial or procurement advice."},
+ "models": [
+  {"key": "claude-opus-5-5", "maker": "anthropic", "name": "claude-opus-5.5", "host": "anthropic", "mode": "chat",
+   "input": 4.0, "output": 20.0, "cache_read": 0.2, "context": 1000000, "skills": ["vision", "tools", "reasoning"],
+   "effort": ["low", "medium", "high", "xhigh", "max"], "effort_default": "", "added": "2026-08-01", "retire": "",
+   "price_changes": 0, "last_change": "2026-08-01",
+   "outlook": {"group": "all", "age_days": 76, "90": {"followed": 900, "price": [0.05, 0.04, 0.06], "retirement": [0.02, 0.01, 0.03], "removed": [0.01, 0.0, 0.02], "none": [0.92, 0.9, 0.94]}}},
+  {"key": "bedrock/claude-opus-5-5", "maker": "anthropic", "name": "claude-opus-5.5", "host": "bedrock", "mode": "chat",
+   "input": 4.4, "output": 22.0, "cache_read": null, "context": 1000000, "skills": ["tools"], "effort": null,
+   "effort_default": "", "added": "2026-08-02", "retire": "", "price_changes": 1, "last_change": "2026-09-01", "outlook": null},
+  {"key": "claude-fable-5-1", "maker": "anthropic", "name": "claude-fable-5.1", "host": "anthropic", "mode": "chat",
+   "input": 10.0, "output": 50.0, "cache_read": 0.25, "context": 1000000, "skills": ["vision", "tools", "reasoning"],
+   "effort": ["low", "medium", "high", "xhigh", "max"], "effort_default": "", "added": "2026-09-01", "retire": "",
+   "price_changes": 0, "last_change": "2026-09-01", "outlook": null},
+  {"key": "claude-sonnet-5-5", "maker": "anthropic", "name": "claude-sonnet-5.5", "host": "anthropic", "mode": "chat",
+   "input": 2.0, "output": 10.0, "cache_read": 0.1, "context": 1000000, "skills": ["tools", "reasoning"],
+   "effort": ["low", "medium", "high"], "effort_default": "medium", "added": "2026-09-01", "retire": "",
+   "price_changes": 0, "last_change": "2026-09-01", "outlook": null},
+  {"key": "gpt-6.1-sol", "maker": "openai", "name": "gpt-6.1-sol", "host": "openai", "mode": "chat",
+   "input": 2.0, "output": 10.0, "cache_read": 0.1, "context": 922000, "skills": ["vision", "tools"],
+   "effort": ["low", "medium", "high"], "effort_default": "", "added": "2026-09-10", "retire": "",
+   "price_changes": 0, "last_change": "2026-09-10", "outlook": null},
+  {"key": "tiny-embed", "maker": "other", "name": "tiny-embed", "host": "x", "mode": "embedding",
+   "input": 0.01, "output": 0.0, "cache_read": null, "context": 8000, "skills": [], "effort": null,
+   "effort_default": "", "added": "2026-01-01", "retire": "", "price_changes": 0, "last_change": "2026-01-01", "outlook": null}
+ ],
+ "events": {"claude-opus-5-5": [["2026-08-01", "added", "", null, null, ""]],
+            "bedrock/claude-opus-5-5": [["2026-08-02", "added", "", null, null, ""],
+                                        ["2026-09-01", "price", "input_cost_per_token", 5e-06, 4.4e-06, ""]],
+            "claude-fable-5-1": [], "claude-sonnet-5-5": [], "gpt-6.1-sol": [], "tiny-embed": []},
+ "ratings": {"date": "2026-10-15", "source": "s", "labels": [["overall", "Everything (overall)"], ["coding", "Coding"]],
+  "tasks": {"overall": [["anthropic / claude-opus-5.5", "claude-opus-5-5", 1548.0, 1534.0, 1561.0, 9000, 1],
+                        ["anthropic / claude-fable-5.1", "claude-fable-5-1", 1537.0, 1526.0, 1549.0, 7000, 2],
+                        ["openai / gpt-6.1-sol", "gpt-6.1-sol", 1530.0, 1520.0, 1540.0, 8000, 3],
+                        ["anthropic / claude-sonnet-5.5", "claude-sonnet-5-5", 1510.0, 1500.0, 1520.0, 6000, 4]],
+            "coding": [["anthropic / claude-fable-5.1", "claude-fable-5-1", 1550.0, 1545.0, 1556.0, 5000, 1],
+                       ["anthropic / claude-opus-5.5", "claude-opus-5-5", 1548.0, 1534.0, 1561.0, 6000, 2],
+                       ["anthropic / claude-sonnet-5.5", "claude-sonnet-5-5", 1520.0, 1510.0, 1530.0, 4000, 3]]}}}

llmledger_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,96 @@
+"""Known-answer tests for each tool, through FastMCP's in-memory client (no network)."""
+import asyncio
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+os.environ["LLMLEDGER_DATA"] = str(Path(__file__).with_name("fixture.json"))
+
+from fastmcp import Client  # noqa: E402
+from fastmcp.exceptions import ToolError  # noqa: E402
+
+from llmledger_mcp.server import mcp  # noqa: E402
+
+
+def call(tool, **args):
+    async def go():
+        async with Client(mcp) as client:
+            return (await client.call_tool(tool, args)).data
+    return asyncio.run(go())
+
+
+def test_the_five_tools_a_resource_and_a_prompt_are_listed():
+    async def go():
+        async with Client(mcp) as client:
+            tools = {t.name: t for t in await client.list_tools()}
+            resources = [str(r.uri) for r in await client.list_resources()]
+            prompts = [p.name for p in await client.list_prompts()]
+            snap = json.loads((await client.read_resource("llmledger://snapshot"))[0].text)
+            return tools, resources, prompts, snap
+    tools, resources, prompts, snap = asyncio.run(go())
+    assert sorted(tools) == ["compare_models", "estimate_cost", "find_models", "price_history", "suggest_for_project"]
+    assert all(t.annotations.read_only_hint for t in tools.values())
+    assert resources == ["llmledger://snapshot"] and prompts == ["pick_a_model"]
+    assert snap["models_listed"] == 6 and snap["rated_tasks"] == {"overall": 4, "coding": 3}
+    assert "MIT" in snap["credits"]["prices"]
+
+
+def test_find_models_ranks_by_rating_and_applies_limits():
+    out = call("find_models", task="coding", limit=5)
+    assert [m["model"] for m in out["models"]] == [
+        "anthropic / claude-fable-5.1", "anthropic / claude-opus-5.5", "anthropic / claude-sonnet-5.5", "openai / gpt-6.1-sol"]
+    assert out["models"][1]["listing"] == "claude-opus-5-5"          # the cheapest listing, not bedrock's
+    assert out["models"][3]["rating"] is None and out["rated_for_task"] == 3
+    cheap = call("find_models", task="overall", max_output_price=15, needs=["vision"])
+    assert [m["model"] for m in cheap["models"]] == ["openai / gpt-6.1-sol"]
+
+
+def test_compare_models_picks_and_explains():
+    out = call("compare_models", models=["opus 5.5", "claude-fable-5-1", "claude-sonnet-5.5"], task="coding",
+               input_tokens=1000, output_tokens=800)
+    assert out["pick"] == "anthropic / claude-opus-5.5"
+    assert out["headline"] == ("claude-opus-5.5 is the pick: the votes cannot tell it apart from the highest rated, "
+                               "claude-fable-5.1, and it costs less.")
+    opus, fable, sonnet = out["models"]
+    assert opus["cost_per_task"] == pytest.approx((1000 * 4 + 800 * 20) / 1e6)
+    assert fable["versus_pick"] == ("Costs 2.5× as much as claude-opus-5.5; it only costs less if it needs under 40% "
+                                    "of the answer tokens.")
+    plan = call("compare_models", models=["claude-opus-5.5", "claude-fable-5.1"], task="coding", pay="claude",
+                answer_tokens={"claude-fable-5.1": 300})
+    # opus: 1,000 in at $4 and 800 out at $20 = $0.020; fable with 300 answer tokens: $0.010 + $0.015 = $0.025
+    assert [m["plan_use"] for m in plan["models"]] == [1.0, 1.25]
+    assert plan["notes"] and "estimate" in plan["notes"][0]
+
+
+def test_unknown_names_say_what_is_close():
+    with pytest.raises(ToolError, match="Not found: 'claude' \\(did you mean"):
+        call("compare_models", models=["claude", "gpt-6.1-sol"])
+
+
+def test_estimate_cost_per_call_day_and_month_with_cache():
+    out = call("estimate_cost", models=["claude-opus-5.5"], input_tokens=10000, output_tokens=1000,
+               cached_tokens=8000, calls_per_day=100)
+    m = out["models"][0]
+    per_call = (2000 * 4 + 8000 * 0.2 + 1000 * 20) / 1e6
+    assert m["per_call"] == pytest.approx(per_call) and m["per_30_days"] == pytest.approx(per_call * 3000)
+    assert m["cache_priced"] is True
+
+
+def test_price_history_lists_changes_per_1m_and_the_outlook():
+    out = call("price_history", model="claude-opus-5.5")
+    bedrock = next(x for x in out["listings"] if x["listing"] == "bedrock/claude-opus-5-5")
+    assert bedrock["changes"][1] == {"day": "2026-09-01", "change": "price", "field": "input_cost_per_token",
+                                     "before": 5.0, "after": 4.4, "flag": None}
+    first = next(x for x in out["listings"] if x["listing"] == "claude-opus-5-5")
+    assert first["outlook"]["90"]["price"] == [0.05, 0.04, 0.06]
+
+
+def test_suggest_for_project_reads_the_prompt():
+    out = call("suggest_for_project", prompt="Debug this Python service and refactor the slow parts")
+    assert out["task"] == "Coding" and out["why"][:2] == ["debug", "python"]
+    best = out["picks"][0]
+    assert best["role"] == "best value" and best["model"] == "anthropic / claude-opus-5.5" and best["effort"] == "xhigh"
+    plan = call("suggest_for_project", prompt="Write a short poem", pay="chatgpt")
+    assert [p["model"] for p in plan["picks"]] == ["openai / gpt-6.1-sol"] and plan["picks"][0]["plan_use"] == 1.0