"""modelread MCP: a Gradio Space whose functions are MCP tools (mcp_server=True), so it can be added from huggingface.co/settings/mcp and used by any MCP client. Thin client over the modelread API; deterministic (no LLM). Env (Space secrets, never in code): MODELREAD_PROXY_SECRET marks this Space as a trusted front end so the API rate-limits per viewer. MODELREAD_API overrides the upstream. """ from __future__ import annotations import os import gradio as gr import httpx API = os.environ.get("MODELREAD_API", "https://modelread.159.223.102.247.nip.io").rstrip("/") SECRET = os.environ.get("MODELREAD_PROXY_SECRET", "") SITE = "https://modelread.com" _http = httpx.Client(timeout=httpx.Timeout(connect=10, read=150, write=20, pool=10), follow_redirects=True) def _headers(request: gr.Request | None) -> dict: h = {"user-agent": "modelread-mcp-space/1", "accept": "application/json"} if SECRET: h["x-modelread-proxy"] = SECRET ip = "" if request is not None: ip = (request.headers.get("x-forwarded-for") or "").split(",")[0].strip() h["x-modelread-client"] = ("hfmcp:" + ip)[:64] return h def _get(path: str, params: dict, request: gr.Request | None): r = _http.get(API + path, params={k: v for k, v in params.items() if v not in (None, "")}, headers=_headers(request)) if r.status_code == 202: return {"status": "queued", "detail": "modelread is reading this repository from the Hub for the first time; " "call again in about a minute."} if r.status_code == 429: return {"status": "rate_limited", "detail": "too many requests; retry in a minute"} try: body = r.json() except ValueError: body = {"detail": r.text[:300]} if r.status_code >= 400: return {"status": "error", "http_status": r.status_code, "detail": body.get("detail", body) if isinstance(body, dict) else body} return body def _slim(v: dict | None) -> dict | None: if not v: return None keep = ("repo", "variant", "format", "verdict", "summary", "confidence", "ctx", "max_ctx_fit", "bits_per_weight", "decode_tps", "prefill_tps", "placement_bytes", "budgets", "launch", "reasons", "unknowns", "warnings", "notes", "runtime_support", "hub_url") return {k: v.get(k) for k in keep if k in v} def estimate_fit(repo: str, hardware: str = "rtx4090", ctx: int = 32768, kv_cache_dtype: str = "f16", request: gr.Request = None) -> dict: """Will this Hugging Face model run on this hardware, how fast, with which quant, and with what command? Checks the repo and its quantized derivatives (GGUF / MLX / AWQ / FP8) from their real file sizes and tensor headers. Returns the best variant and alternatives, each with: verdict (fits | fits-tight | offload | no | unknown), decode and prefill tokens/sec as a calibrated range (lo/mid/hi with basis), longest context that fits, memory placement (VRAM / RAM / SSD) and an exact llama.cpp / vLLM / MLX launch command. Args: repo: Hugging Face repo id, e.g. "Qwen/Qwen3.6-27B" or "unsloth/gemma-4-26B-A4B-it-GGUF". hardware: device preset id ("rtx4090", "m4max-128", "dgx-spark", "8x-h100-sxm", "iphone-17pro-12"), "2x-rtx3090", free text ("MacBook Pro M3 Max 128GB", "AWS g6e.xlarge"), or "gpu=24,ram=64,bw=936". ctx: context length in tokens to fit (default 32768). kv_cache_dtype: KV cache type: "f16", "q8_0" or "q4_0". """ d = _get("/api/estimate", {"repo": repo.strip(), "hw": hardware.strip(), "ctx": int(ctx), "kv": kv_cache_dtype}, request) if not isinstance(d, dict) or "best" not in d: return d return {"repo": d.get("repo"), "hardware": d.get("hardware"), "ctx": d.get("ctx"), "model": d.get("model"), "best": _slim(d.get("best")), "alternatives": [_slim(a) for a in (d.get("alternatives") or [])[:4]], "notes": d.get("notes", []), "page": f"{SITE}/m/{repo.strip()}"} def compare_hardware(repo: str, hardware_list: str = "rtx4090, m4max-128, dgx-spark, h100-sxm", ctx: int = 32768, request: gr.Request = None) -> dict: """Run one Hugging Face model against several devices and rank them (best first). Use for "which of my machines should run X" or "is a 4090 or an M4 Max better for X". Args: repo: Hugging Face repo id, e.g. "openai/gpt-oss-120b". hardware_list: comma-separated devices (preset ids or free text), up to 8. ctx: context length in tokens (default 32768). """ rows = [] rank = {"fits": 0, "fits-tight": 1, "offload": 2, "unknown": 3, "no": 4} for hw in [h.strip() for h in hardware_list.split(",") if h.strip()][:8]: d = _get("/api/estimate", {"repo": repo.strip(), "hw": hw, "ctx": int(ctx)}, request) b = (d or {}).get("best") if isinstance(d, dict) else None if not b: rows.append({"hardware": hw, "error": (d or {}).get("detail") if isinstance(d, dict) else str(d)}) continue rows.append({"hardware": d.get("hardware"), "verdict": b.get("verdict"), "repo": b.get("repo"), "variant": b.get("variant"), "decode_tps": b.get("decode_tps"), "max_ctx_fit": b.get("max_ctx_fit"), "launch": b.get("launch")}) rows.sort(key=lambda r: (rank.get(r.get("verdict"), 5), -((r.get("decode_tps") or {}).get("mid") or 0))) return {"repo": repo, "ctx": ctx, "results": rows} def find_models(question: str, default_hardware: str = "", request: gr.Request = None) -> dict: """Recommend open models for a task on a device, from a natural-language question. Ranks ~20k indexed Hugging Face models by fit, task benchmark percentile (vendor vs independent kept apart), quant quality and speed. Examples: "best coding model for an RTX 4090 + 64GB RAM at 32k context", "Japanese chat on a Galaxy S25 Ultra", "serve 8 users on 2x RTX 3090". Args: question: the request in plain words; name the device in it, or set default_hardware. default_hardware: device used when the question names none (preset id, e.g. "m4max-128"). """ r = _http.post(API + "/api/ask", json={"q": question, "llm": False, "hw": default_hardware or None}, headers=_headers(request)) if r.status_code >= 400: return {"status": "error", "http_status": r.status_code, "detail": r.text[:300]} d = r.json() return {"query": d.get("query"), "answer_markdown": d.get("answer_md"), "notes": d.get("notes"), "results": [{"repo": x.get("repo"), "quality": (x.get("quality") or {}).get("quality"), "best": _slim(x.get("best"))} for x in d.get("results", [])]} def list_hardware(filter: str = "", limit: int = 40, request: gr.Request = None) -> list: """List device presets: GPUs of every vendor, Apple Silicon, multi-GPU nodes, cloud instances (with $/hour), Jetson, phones, tablets, single-board computers and VPS tiers. Args: filter: words matched against id / name / vendor / segment, e.g. "h100", "amd datacenter", "phone samsung". limit: maximum rows to return. """ rows = _get("/api/hardware", {}, request) if not isinstance(rows, list): return [rows] words = filter.lower().split() out = [r for r in rows if all(w in f"{r['id']} {r['name']} {r['vendor']} {r['segment']} {r['backend']}".lower() for w in words)] return out[: max(1, min(int(limit), 400))] def search_models(query: str = "", task: str = "chat", limit: int = 20, request: gr.Request = None) -> list: """Search the modelread index of Hugging Face models by name and task (no fit estimate; fast). Args: query: words that must appear in the repo id, e.g. "qwen3.6" or "gemma 4". task: chat | coding | vision | ocr | embedding | speech-to-text | tts | image-generation. limit: maximum rows (1-100). """ rows = _get("/api/search", {"q": query, "task": task, "limit": int(limit), "match": bool(query)}, request) if not isinstance(rows, list): return [rows] keep = ("id", "pipeline_tag", "library", "params", "downloads", "likes", "license", "created") return [{k: r.get(k) for k in keep} for r in rows] CSS = ".gradio-container {max-width: 980px !important}" with gr.Blocks(title="modelread MCP") as demo: gr.Markdown( "# modelread MCP\n" "Will this Hugging Face model run on your hardware, how fast, which quant, and with what command? " "This Space is an **MCP server**: add it from [your MCP settings](https://huggingface.co/settings/mcp) " f"or use the endpoint below. The full site is [modelread.com]({SITE}).\n\n" "MCP endpoint: `https://patrickbdevaney-modelread-mcp.hf.space/gradio_api/mcp/` ยท " f"also available at `{SITE}/mcp`" ) with gr.Tab("Estimate fit"): with gr.Row(): repo = gr.Textbox(label="Repo", value="Qwen/Qwen3.6-27B") hw = gr.Textbox(label="Hardware", value="rtx4090") ctx = gr.Number(label="Context", value=32768, precision=0) kv = gr.Dropdown(["f16", "q8_0", "q4_0"], value="f16", label="KV cache") out = gr.JSON(label="Result") gr.Button("Estimate", variant="primary").click(estimate_fit, [repo, hw, ctx, kv], out, api_name="estimate_fit") with gr.Tab("Compare devices"): with gr.Row(): crepo = gr.Textbox(label="Repo", value="openai/gpt-oss-120b") chw = gr.Textbox(label="Devices (comma-separated)", value="rtx5090, m4max-128, dgx-spark, h100-sxm") cctx = gr.Number(label="Context", value=32768, precision=0) cout = gr.JSON(label="Ranked") gr.Button("Compare", variant="primary").click(compare_hardware, [crepo, chw, cctx], cout, api_name="compare_hardware") with gr.Tab("Find models"): q = gr.Textbox(label="Question", value="best coding model for an RTX 4090 with 64GB RAM at 32k context") dh = gr.Textbox(label="Default hardware (if the question names none)", value="") fout = gr.JSON(label="Recommendations") gr.Button("Find", variant="primary").click(find_models, [q, dh], fout, api_name="find_models") with gr.Tab("Hardware"): hf_ = gr.Textbox(label="Filter", value="h100") hl = gr.Number(label="Limit", value=40, precision=0) hout = gr.JSON(label="Devices") gr.Button("List").click(list_hardware, [hf_, hl], hout, api_name="list_hardware") with gr.Tab("Search"): sq = gr.Textbox(label="Query", value="gemma 4") st = gr.Dropdown(["chat", "coding", "vision", "ocr", "embedding", "speech-to-text", "tts", "image-generation"], value="chat", label="Task") sl = gr.Number(label="Limit", value=20, precision=0) sout = gr.JSON(label="Models") gr.Button("Search").click(search_models, [sq, st, sl], sout, api_name="search_models") if __name__ == "__main__": demo.launch(mcp_server=True, css=CSS, ssr_mode=False)