@octocodeai/freellama-mcp-server 0.6.0 → 0.6.2

package/CONFIGURATION.md

@@ -9,7 +9,7 @@ server-launch config (for example `.mcp.json`'s `env` block) or the launching sh
 
 | Variable | Default | Affects |
 |---|---|---|
-| `FREELLAMA_OLLAMA_ENDPOINT` | `http://127.0.0.1:11434` | Default Ollama endpoint for `doctor`, the `models` detail/raw/library views, and all `ollama_*` tools |
+| `FREELLAMA_OLLAMA_ENDPOINT` | `http://127.0.0.1:11434` | Default Ollama endpoint for `doctor`, the `models` detail/raw/library views, all `ollama_*` tools, and the autostarted serve's `--upstream` |
 | `FREELLAMA_SERVE_ENDPOINT` | `http://127.0.0.1:11435` | Default `endpoint` for serve-backed tools and `delegate_research` |
 | `FREELLAMA_MCP_DEFAULT_MODEL` | unset (routes to an installed coding model) | `delegate_research`'s default `model` |
 | `FREELLAMA_MCP_DEFAULT_ADAPTER` | `bash` | `delegate_research`'s adapter (`octocode` to switch) |
@@ -22,11 +22,11 @@ server-launch config (for example `.mcp.json`'s `env` block) or the launching sh
 | `FREELLAMA_EXTERNAL_COST_MODEL` | unset | External-model label in estimated avoided-cost telemetry; set all three cost variables or none |
 | `FREELLAMA_EXTERNAL_COST_INPUT_USD_PER_M` | unset | External input USD per million tokens |
 | `FREELLAMA_EXTERNAL_COST_OUTPUT_USD_PER_M` | unset | External output USD per million tokens |
-| `FREELLAMA_CONTROL_TIMEOUT_SECONDS` | `30` | Decision-only serve calls; read by `packages/rust-core/src/napi.rs` |
-| `FREELLAMA_TASK_TIMEOUT_SECONDS` | `900` | Generation calls; read by `packages/rust-core/src/napi.rs` |
+| `FREELLAMA_CONTROL_TIMEOUT_SECONDS` | `30` | Decision-only serve calls; read by the native client (`packages/rust-core/src/serve_client.rs`) |
+| `FREELLAMA_TASK_TIMEOUT_SECONDS` | `900` | Generation calls; read by the native client (`packages/rust-core/src/serve_client.rs`) |
 | `FREELLAMA_AUTH_TOKEN_FILE` | unset | Bearer-token file used by the native client and research adapters for all serve routes |
 | `FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR` | platform data directory | Prompt-free, model-specific token-estimator calibration shared across adapter processes |
-| `FREELLAMA_MCP_AUTOSTART_SERVE` | `1` | When the default loopback serve endpoint does not answer, start `freellama serve` as a child of the MCP server (stopped with it). `0` disables |
+| `FREELLAMA_MCP_AUTOSTART_SERVE` | `1` | When the default loopback serve endpoint does not answer, start `freellama serve` as a child of the MCP server (stopped with it): once in the background at launch, so other local clients find it, and again on a tool call if it is still down. `0` disables |
 | `FREELLAMA_SERVE_BINARY` | checkout `target/release`/`debug`, then the platform package | Binary used for serve autostart |
 | `FREELLAMA_AGENT_OS_SANDBOX` | `auto` | Bash adapter OS confinement: `bwrap` on Linux, `sandbox-exec` on macOS, when present. `off` keeps only the restricted shell |
 | `FREELLAMA_AGENT_OCTOCODE_PACKAGE` | `octocode@19.1.0` | Pinned npm spec the Octocode adapter runs through `npx` |
@@ -103,6 +103,4 @@ slots or relax memory guards. Existing queued work keeps its captured cost. See
 `packages/mcp/evidence/model-evidence.json`. A published package does not include that repository
 file, so its evidence table is empty unless you set `FREELLAMA_MCP_MODEL_EVIDENCE`. An unmeasured
 model yields a `verify` verdict, and an unreadable evidence file is reported on stderr and treated
-as empty. Tool descriptions state the rules; measurement details live in
-[`skills/freellama/references/`](https://github.com/bgauryy/FreeLlama/tree/main/skills/freellama/references/) and
-[`docs/dev/evidence/`](https://github.com/bgauryy/FreeLlama/tree/main/docs/dev/evidence/).
+as empty. Tool descriptions state the rules.

package/DEVELOPING.md

@@ -13,10 +13,11 @@ yarn install
 yarn build
 ```
 
-`yarn build` writes **one** MCP file, `packages/mcp/dist/index.js` (shebang, executable). During
+`yarn build` writes the MCP server, `packages/mcp/dist/index.js` (shebang, executable). During
 checkout development it loads `native/freellama.<triple>.node`. Published installs resolve the
 matching `@octocodeai/freellama-native-<target>` optional package instead, so the base MCP package remains
-portable. Research adapters are copied into `adapters/` for packed installs.
+portable. The research adapters compile to `dist/research/{bash-agent,octocode-agent}.js`, and the
+repository `docs/` guides are copied into `docs/`.
 
 Piecewise, if you are iterating on one layer:
 
@@ -24,7 +25,7 @@ Piecewise, if you are iterating on one layer:
 # 1. Native addon → packages/mcp/native/freellama.<triple>.node
 yarn build:native
 
-# 2. This server → dist/index.js via esbuild (then copies the research adapters into adapters/)
+# 2. This server → dist/index.js and dist/research/*.js via esbuild, plus docs/
 yarn workspace @octocodeai/freellama-mcp-server build
 ```
 
@@ -33,8 +34,8 @@ root produces both in a checkout. `dist/index.js` loads `native/index.js`, which
 first and then a matching optional platform package. The `.node` binary is gitignored (a build
 artifact). `native/index.js` is a small hand-written loader; `native/index.d.ts` is generated from
 `napi.rs` by `yarn build:native`. Both are checked in; do not edit the declarations by hand —
-change the Rust doc comments or `ts_args_type`, rebuild, and commit. CI rebuilds it and fails
-on any diff.
+change the Rust doc comments or `ts_args_type`, rebuild, and commit. The unit test
+`test/unit/native-dts-drift.test.ts` fails when the declarations and the `napi.rs` exports differ.
 
 ## Test
 
@@ -42,15 +43,17 @@ Vitest, in three tiers (all TypeScript, under `test/`):
 
 | Tier | Command (from this package) | Checks | Needs |
 |---|---|---|---|
-| `test/unit/` | `yarn test` (watch: `yarn test:watch`) | pure functions straight from `src/*.ts` — no build step, this is the TDD loop | nothing, ~0.5s |
+| `test/unit/` | `yarn test` (watch: `yarn test:watch`) | pure functions straight from `src/*.ts` — no build step, this is the TDD loop | nothing, a few seconds |
 | `test/integration/` | `yarn test:integration` | the built server over the real MCP protocol: tool contract, structured content, guardrails; rebuilds `dist/` itself | Ollama at `FREELLAMA_OLLAMA_ENDPOINT` (default :11434) |
 | `test/e2e/` | `yarn test:e2e` | every tool against the live system: real routing/execution, pull → delete round trip (net-zero), a real delegated research run | serve + Ollama + models, ~40s |
 
-The same commands work from the repository root (`yarn test` there also runs the CLI package's tests).
+The same commands work from the repository root (`yarn test` there also runs the CLI package's tests
+and the Rust suite).
 The integration/e2e tiers fail fast with a readable message when Ollama is down, and the lifecycle
 test refuses to delete a model already installed on the test system.
 
-For default-endpoint autostart, a spawn failure, early exit, or readiness timeout rejects the
+For default-endpoint autostart, the server starts `freellama serve` in the background at launch and
+logs a failure to stderr. On a tool call, a spawn failure, early exit, or readiness timeout rejects the
 request while leaving the MCP transport available for diagnosis or retry. Autostart does not apply
 to an explicit non-default endpoint; see `FREELLAMA_MCP_AUTOSTART_SERVE` in
 [configuration](CONFIGURATION.md#environment-variables).
@@ -74,8 +77,8 @@ Start the serve-backed tools' dependency from the repository root:
 cargo run --release -- serve
 ```
 
-See `skills/freellama/references/proxy-vs-serve.md` for the `proxy` vs `serve` distinction (only
-`serve` has the `/_freellama/v1/*` routes these tools call).
+`freellama proxy` only forwards raw `/api/*` calls; only `serve` has the `/_freellama/v1/*` routes
+these tools call.
 
 ## Publish
 
@@ -91,18 +94,18 @@ cd packages/mcp
 npm pack --dry-run   # confirm exactly what a publish would ship
 ```
 
-Treat `npm publish` as a public release action. Follow the repository
-[release procedure](https://github.com/bgauryy/FreeLlama/blob/main/RELEASE.md) and obtain the repository owner's release authorization first.
+Treat `npm publish` as a public release action. Follow the
+[release package checks](https://github.com/bgauryy/FreeLlama/blob/main/docs/TESTING.md#verify-release-packages) and obtain the repository owner's release authorization first.
 
 ## Why native bindings
 
 - **No routing reimplementation.** `run_task`, `run_task {preview:true}`, and the installed-model list are HTTP
-  calls into a running `freellama serve`, matching the CLI tool map in `packages/cli/src/tools.rs`. `doctor` talks to Ollama
+  calls into a running `freellama serve`, matching the CLI requests in `packages/cli/src/requests.rs`. `doctor` talks to Ollama
   and the host's portable machine-discovery layer directly. `ollama_manage` / `ollama_delete` hit Ollama's HTTP API. `delegate_research`
   is a subprocess. Routing decisions still live in exactly one place — the Rust core; see
   [what the MCP layer computes](README.md#what-the-mcp-layer-computes).
-- **One connection pool.** `packages/rust-core/src/napi.rs` holds a single `reqwest::Client` in a
-  `OnceLock` and clones the handle per request, matching the server side.
+- **One connection pool.** `packages/rust-core/src/serve_client.rs` holds a single `reqwest::Client` in a
+  `OnceLock` and clones the handle per request; `napi.rs` and the CLI share it.
 - **`unsafe_code` stays isolated.** The crate is `deny(unsafe_code)` except `napi.rs`, which
   carries an explicit `#[allow(unsafe_code)]` for napi-derive's FFI glue.
 - **The napi build is off by default** (`cargo build` never touches it); the addon is built with

package/LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) FreeLlama contributors
+Copyright (c) 2026 Guy Bary
 
 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

package/README.md

@@ -14,7 +14,7 @@ The server uses the official [TypeScript SDK](https://github.com/modelcontextpro
 
 ## Understand the tools
 
-`doctor`, `models`, `run_task`, and `task_jobs` call the Rust core through native NAPI bindings
+`doctor`, `models`, `run_task`, `task_jobs`, `scope`, and `session` call the Rust core through native NAPI bindings
 (`packages/rust-core/src/napi.rs`), with no CLI subprocess and no routing decisions in TypeScript; the
 TypeScript layer validates request shapes and derives presentation fields (see
 [what the MCP layer computes](#what-the-mcp-layer-computes)). `run_task` has four modes: one task,
@@ -190,7 +190,7 @@ flowchart TD
     S --> G["Primary Ollama"]
     S --> U["Optional CPU Ollama"]
     B -->|"detail, raw; manage; delete"| G
-    B -->|"library view"| W["ollama.com library"]
+    B -->|"library view"| W["ollama.com library + Hugging Face GGUF"]
     B -->|"delegate_research"| A["allowlisted local adapter subprocess"]
     A --> S
     C -->|"resources/read on demand"| D["packaged docs/*.md"]
@@ -218,9 +218,8 @@ The TypeScript server adds a small set of derived fields on top of core results:
 
 ## Read packaged documentation through MCP
 
-The published MCP package includes the top-level Markdown guides from the repository `docs/`
-directory (developer notes under `docs/dev/` are not packaged). The repository directory remains the
-source of truth; the package build copies it into `docs/`.
+The published MCP package includes the Markdown guides from the repository `docs/` directory.
+The repository directory remains the source of truth; the package build copies it into `docs/`.
 
 MCP clients can list resources and read `freellama://docs/index` (the repository `docs/README.md`),
 then fetch exactly one relevant guide such as `freellama://docs/PRODUCTION` or
@@ -243,6 +242,8 @@ node packages/mcp/dist/index.js
 ```
 
 The server speaks MCP over stdio — configure it in your MCP client, do not run it interactively.
+At launch it starts `freellama serve` in the background when the default endpoint does not answer;
+see `FREELLAMA_MCP_AUTOSTART_SERVE` in [Configuration](CONFIGURATION.md#environment-variables).
 
 **Claude Desktop (`claude_desktop_config.json`):**
 
@@ -264,7 +265,7 @@ The server speaks MCP over stdio — configure it in your MCP client, do not run
 | Tool | Needs `freellama serve`? | What it does |
 |---|---|---|
 | `doctor` | No (except `status`/`usage`) | Runtime/configuration diagnostic. Target another Ollama with `ollamaEndpoint` and serve with `serveEndpoint`. `summary` (default) returns endpoint, version, resident count, host/profile signals, and next step; `full` adds all non-duplicated diagnostics, including admission and categorized Ollama settings; `status` returns serve's live view (per-backend queues, current and adaptive limits, circuit breakers, loaded models, host memory, Ollama's effective settings, today's usage); `usage` returns task and token totals per day and model (`days`, default 7). The report distinguishes an observed same-user macOS process from configuration hints and never claims remote process visibility. |
-| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, use explanations, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, maximum context), paged `raw` (`GET /api/tags`), `library` (two-step ollama.com search: omit `model` for families, pass `model:"<family>"` for all tags/`fitsInMemory`). `includeLibrary:true` enriches installed/detail views with sourced public guidance; `includeReadme:true` returns bounded README text in library step 2 or enriched detail. |
+| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, use explanations, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, maximum context), paged `raw` (`GET /api/tags`), `library` (two-step public search: omit `model` to search ollama.com families and, for a `query`, Hugging Face GGUF repos (`source` limits it to one; `limit` applies per source); pass `model:"<family>"` or `model:"hf.co/<owner>/<repo>"` for every pullable tag with its size and `fitsInMemory`). `includeLibrary:true` enriches installed/detail views with sourced public guidance; `includeReadme:true` returns bounded README text in library step 2 or enriched detail. |
 | `run_task` | Yes | **Routes or executes** a chat/generate/embed call. `preview: true` accepts routing fields only and returns a decision without generation. Execution omits preview and supplies the payload. Embedding results withhold raw vectors by default (`returnEmbeddings: true` to get them). `tasks: [{id, independent:true, task}]` (max 64, `maxParallelism` bounds fan-out) runs a batch whose nested `task` takes the same fields; it is not a dependency scheduler. `warm: true` warms an exact installed `model` through managed admission with residency/profile controls and optional `defer:true`. |
 | `scope` | Yes | Creates, inspects, forks, or deletes process-local message history; history inclusion requires `includeMessages:true`. |
 | `session` | Yes | Creates, deletes, or kills model affinity without storing messages or KV; `kill` cancels the session's in-flight work. |
@@ -318,8 +319,8 @@ Memory admission, authentication, and capability requirements apply in every mod
   tasks or `input` for embeddings, plus any applicable Ollama runtime controls.
 
 Preview rejects `prompt`, `systemPrompt`, `messages`, `input`, `images`, `tools`, `keepAlive`, `format`, `think`,
-`options`, `logprobs`, `topLogprobs`, `returnEmbeddings`, `priority`, `maxWaitSeconds`, `timeoutSeconds`, and
-`defer`, `scopeId`, and `scopeRevision`. This prevents a client from attaching
+`options`, `logprobs`, `topLogprobs`, `returnEmbeddings`, `priority`, `maxWaitSeconds`, `timeoutSeconds`,
+`stopOnRepetition`, `defer`, `scopeId`, and `scopeRevision`. This prevents a client from attaching
 work to a decision-only call and mistakenly assuming it ran.
 
 `run_task.messages` preserves Ollama message fields beyond `role` and `content`, including images,
@@ -368,7 +369,7 @@ Scripts that bypass MCP post the same fields in snake_case to `POST /_freellama/
 `task`, `objective`, `model`, `session_id`, `required_capabilities`, `prompt` or `messages`,
 `images`, `priority`, `keep_alive`, `max_wait_seconds`, `timeout_seconds`, `stop_on_repetition`,
 and `request_options: {options, format, think, logprobs, top_logprobs}`. A batch is
-`{tasks: [{id, independent: true, task: {...}}], max_parallelism}`; sessions are
+`POST /_freellama/v1/task-batches` with `{tasks: [{id, independent: true, task: {...}}], max_parallelism}`; sessions are
 `POST /_freellama/v1/sessions` with `{}`. `model` accepts a bare name (`name` resolves to
 `name:latest`, or the one installed tag of that family); an ambiguous or unknown name is refused
 with the installed candidates. See [Request shapes](https://github.com/bgauryy/FreeLlama/blob/main/docs/ARCHITECTURE.md#request-shapes)

package/dist/index.js

@@ -21629,6 +21629,12 @@ function serveBinaryCandidates() {
   if (process.env.FREELLAMA_SERVE_BINARY) candidates.unshift(process.env.FREELLAMA_SERVE_BINARY);
   return candidates;
 }
+function startServeInBackground() {
+  ensureServe(void 0).catch((error2) => {
+    process.stderr.write(`[freellama serve] background start failed: ${error2 instanceof Error ? error2.message : String(error2)}
+`);
+  });
+}
 function stopAutostartedServe() {
   if (child && child.exitCode === null) child.kill("SIGTERM");
   child = null;
@@ -22371,27 +22377,38 @@ function libraryTrialCandidate(tag, embedding) {
     caution: "Measure this exact tag on representative tasks before choosing it. Include resident runners, context/KV caches and OS headroom in memory fit. Discovery does not authorize a pull."
   };
 }
+var SIZE_CHIP = /^(?:\d+x)?(?:e)?\d+(?:\.\d+)?[kmbt]$/i;
 function parseModelSearch(html) {
   const results = [];
-  for (const block of html.split(/<li\s/).slice(1)) {
+  for (const block of html.split(/<li\b/).slice(1)) {
     const link = block.match(/href="\/(?:library\/([\w.-]+)|([\w.-]+\/[\w.-]+))"/);
     const name = link?.[1] ?? link?.[2];
     if (!name) continue;
-    if (!/<p\b[^>]*class="max-w-lg/.test(block)) continue;
-    const rawDescription = block.match(/<p class="max-w-lg[^"]*">([\s\S]*?)<\/p>/)?.[1];
-    const description = rawDescription === void 0 ? "" : decodeHtml(rawDescription.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
-    const capabilities = [...block.matchAll(/text-(?:indigo-600|cyan-500)[^>]*>([a-z]+)<\/span>/g)].map(
-      (m) => m[1]
-    );
-    const stat = (label) => block.match(
-      new RegExp(`<span >([\\d.,KMB]+)<\\/span>\\s*<span class="hidden sm:flex">&nbsp;${label}`)
-    )?.[1] ?? null;
+    const rawDescription = block.match(/<p\b[^>]*>([\s\S]*?)<\/p>/)?.[1];
+    if (rawDescription === void 0) continue;
+    const description = decodeHtml(rawDescription.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+    const chips = [...block.matchAll(/<span\b[^>]*class="[^"]*\b(?:rounded-md|text-(?:indigo|cyan|blue)-\d+)\b[^"]*"[^>]*>\s*([\w.-]+)\s*<\/span>/g)].map((m) => ({ text: m[1].toLowerCase(), at: m.index }));
+    const first = chips.find((chip) => !SIZE_CHIP.test(chip.text));
+    const groupStart = first ? block.lastIndexOf("<div", first.at) : -1;
+    const groupEnd = groupStart >= 0 ? block.indexOf("</div>", first.at) : -1;
+    const inGroup = (at) => groupStart < 0 || groupEnd < 0 || at > groupStart && at < groupEnd;
+    const words = chips.filter((chip) => !SIZE_CHIP.test(chip.text) && /^[a-z]+$/.test(chip.text));
+    const sizes = chips.filter((chip) => SIZE_CHIP.test(chip.text)).map((chip) => chip.text);
+    const capabilities = [...new Set(words.filter((chip) => inGroup(chip.at)).map((chip) => chip.text))];
+    const labels = [...new Set(words.filter((chip) => !inGroup(chip.at)).map((chip) => chip.text))];
+    const legacyStat = (label) => block.match(new RegExp(`<span >([\\d.,KMB]+)<\\/span>\\s*<span class="hidden sm:flex">&nbsp;${label}`))?.[1] ?? null;
+    const downloads = block.match(/title="([\d,]+) downloads"/)?.[1];
+    const pullsShort = block.match(/title="[\d,]+ downloads"[\s\S]*?<span\s*>([\d.,]+[KMB]?)<\/span>/)?.[1];
+    const tagCount = block.match(/>\s*(\d+)\s+tags?\s*</)?.[1];
     results.push({
       name,
       description: clipText(description, 160),
       capabilities,
-      pulls: stat("Pulls"),
-      tags: stat("Tag"),
+      ...labels.length ? { labels } : {},
+      ...sizes.length ? { sizes } : {},
+      pulls: pullsShort ?? legacyStat("Pulls"),
+      ...downloads ? { downloads: Number(downloads.replace(/,/g, "")) } : {},
+      tags: tagCount ?? legacyStat("Tag"),
       cloudAvailable: capabilities.includes("cloud")
     });
   }
@@ -22430,6 +22447,130 @@ function parseModelTags(html, family) {
   return { family, tags };
 }
 
+// src/huggingface.ts
+var HUB = "https://huggingface.co";
+var MAX_JSON_BYTES = 4 * 1024 * 1024;
+function huggingFaceReference(model) {
+  const match = model.match(/^(?:https?:\/\/)?(?:hf\.co|huggingface\.co)\/([\w.-]+)\/([\w.-]+?)(?::([\w.-]+))?$/i);
+  if (!match || [match[1], match[2]].some((part) => part === "." || part === "..")) return null;
+  const repo = `${match[1]}/${match[2]}`;
+  return { repo, family: `hf.co/${repo}`, quant: match[3] ?? null, url: `${HUB}/${repo}` };
+}
+var QUANT = /^(?:UD-)?(?:I?Q\d(?:_[A-Z0-9]+)*|BF16|F16|F32|MXFP4(?:_MOE)?|TQ\d_\d)$/i;
+var SPLIT = /-\d{5}-of-\d{5}$/;
+function quantOf(path6) {
+  const parts = path6.split("/");
+  const stem = parts.pop().replace(/\.gguf$/i, "").replace(SPLIT, "");
+  for (let index = 0; index <= stem.length; index++) {
+    if (index > 0 && !/[-.]/.test(stem[index - 1])) continue;
+    if (QUANT.test(stem.slice(index))) return stem.slice(index);
+  }
+  return parts.reverse().find((dir) => QUANT.test(dir)) ?? null;
+}
+var decimalSize = (bytes) => bytes >= 1e9 ? `${(bytes / 1e9).toFixed(1)}GB` : `${Math.round(bytes / 1e6)}MB`;
+function parseHuggingFaceFiles(tree, repo) {
+  const builds = /* @__PURE__ */ new Map();
+  const projectors = [];
+  for (const entry of tree) {
+    if (entry.type !== "file" || !entry.path || !/\.gguf$/i.test(entry.path)) continue;
+    const file = entry.path.split("/").pop();
+    if (/mmproj/i.test(file)) {
+      projectors.push(entry.path);
+      continue;
+    }
+    const key = entry.path.replace(/-\d{5}-of-(\d{5})\.gguf$/i, "-00001-of-$1.gguf");
+    const bytes = entry.lfs?.size ?? entry.size ?? 0;
+    const build = builds.get(key) ?? { path: key, file: key.split("/").pop(), quant: quantOf(entry.path), bytes: 0, files: 0 };
+    builds.set(key, { ...build, bytes: build.bytes + bytes, files: build.files + 1 });
+  }
+  const perQuant = /* @__PURE__ */ new Map();
+  for (const { quant } of builds.values()) if (quant) perQuant.set(quant.toLowerCase(), (perQuant.get(quant.toLowerCase()) ?? 0) + 1);
+  const tags = [...builds.values()].sort((a, b) => a.bytes - b.bytes).map(({ path: path6, file, quant, bytes, files }) => ({
+    tag: `hf.co/${repo}:${quant && perQuant.get(quant.toLowerCase()) === 1 ? quant : file}`,
+    quant,
+    path: path6,
+    size: bytes ? decimalSize(bytes) : null,
+    sizeBytes: bytes || null,
+    files,
+    cloud: false,
+    // Hugging Face's Ollama guide shows single-file builds; say so rather than promise a pull.
+    ...files > 1 ? { note: `Split into ${files} files; the Hub's Ollama guide documents single-file GGUFs, so confirm the pull.` } : {}
+  }));
+  return { tags, projectors };
+}
+function parseHuggingFaceSearch(models) {
+  return models.filter((model) => model.id).map((model) => ({
+    name: `hf.co/${model.id}`,
+    source: "huggingface",
+    task: model.pipeline_tag ?? null,
+    downloads: model.downloads ?? null,
+    likes: model.likes ?? null,
+    updated: model.lastModified ?? null
+  }));
+}
+var HUB_EMBEDDING_TASKS = /* @__PURE__ */ new Set(["feature-extraction", "sentence-similarity"]);
+var HuggingFaceClient = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  async json(url) {
+    const response = await (this.options.fetch ?? fetch)(url, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(this.options.timeoutMs ?? Math.min(DEFAULT_OLLAMA_FETCH_TIMEOUT_SECONDS * 1e3, 1e4))
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error(response.status === 404 || response.status === 401 ? `Hugging Face has no public model at ${url} (HTTP ${response.status}).` : `Hugging Face returned HTTP ${response.status}.`);
+    }
+    const text = await response.text();
+    if (text.length > MAX_JSON_BYTES) throw new Error("Hugging Face response exceeds the 4 MiB limit.");
+    return JSON.parse(text);
+  }
+  stamp() {
+    return new Date((this.options.now ?? Date.now)()).toISOString();
+  }
+  /** GGUF repositories matching `query`, most downloaded (or newest) first. */
+  async search(query, { limit = 10, order = "popular", task } = {}) {
+    const params = new URLSearchParams({
+      search: query,
+      filter: "gguf",
+      sort: order === "newest" ? "lastModified" : "downloads",
+      direction: "-1",
+      limit: String(limit)
+    });
+    for (const field of ["downloads", "likes", "pipeline_tag", "lastModified"]) params.append("expand[]", field);
+    if (task) params.set("pipeline_tag", task);
+    const url = `${HUB}/api/models?${params}`;
+    return { url, models: parseHuggingFaceSearch(await this.json(url)), fetchedAt: this.stamp() };
+  }
+  /** One repo's pullable quants, task, architecture and context length. */
+  async lookup(model) {
+    const ref = huggingFaceReference(model);
+    if (!ref) throw new Error("Use hf.co/<owner>/<repo>, the name Ollama pulls from Hugging Face.");
+    const info = await this.json(
+      `${HUB}/api/models/${ref.repo}?expand[]=gguf&expand[]=pipeline_tag&expand[]=downloads&expand[]=likes&expand[]=lastModified&expand[]=sha&expand[]=gated`
+    );
+    const tree = await this.json(`${HUB}/api/models/${ref.repo}/tree/${info.sha ?? "main"}?recursive=true`);
+    return {
+      ...ref,
+      task: info.pipeline_tag ?? null,
+      revision: info.sha ?? null,
+      // "auto" or "manual": Hugging Face serves the files only after you accept the repo's terms.
+      gated: info.gated && info.gated !== "false" ? info.gated : false,
+      architecture: info.gguf?.architecture ?? null,
+      contextLength: info.gguf?.context_length ?? null,
+      parameters: info.gguf?.total ?? null,
+      downloads: info.downloads ?? null,
+      likes: info.likes ?? null,
+      updated: info.lastModified ?? null,
+      ...parseHuggingFaceFiles(tree, ref.repo),
+      fetchedAt: this.stamp()
+    };
+  }
+};
+
 // src/model-knowledge.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
 var FAILURE_TTL_MS = 60 * 1e3;
@@ -22707,12 +22848,32 @@ var modelsResultSchema = external_exports.object({
   library: external_exports.unknown().optional()
 }).passthrough();
 var ollamaLibrary = new OllamaLibraryClient();
+var huggingFace = new HuggingFaceClient();
 var HOST_MEMORY_FIT_FRACTION = 0.6;
+var HUB_TASKS = /* @__PURE__ */ new Map([
+  ["embedding", ["feature-extraction", "sentence-similarity"]],
+  ["vision", ["image-text-to-text"]]
+]);
+function annotateTags(tags, installed, memoryBytes, embedding) {
+  const budget = memoryBytes ? memoryBytes * HOST_MEMORY_FIT_FRACTION : null;
+  const local = installed ? new Set([...installed].map((name) => name.toLowerCase())) : null;
+  const annotated = tags.map((t) => ({
+    ...t,
+    installed: local ? local.has(t.tag.toLowerCase()) : null,
+    fitsInMemory: budget && t.sizeBytes ? t.sizeBytes <= budget : null,
+    fitScope: "host_memory_budget_only"
+  }));
+  const sized = annotated.filter((t) => t.fitsInMemory === true && !t.cloud && t.sizeBytes);
+  const best = budget ? sized.sort((a, b) => embedding ? (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0) : (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0))[0] : void 0;
+  return { annotated, budget, best };
+}
+var NO_PROFILE = "No machine profile (freellama serve unreachable), so memory fit could not be checked and no tag is recommended. Start serve, or read the sizes yourself.";
 async function libraryLookup({
   model,
   query,
   capabilities,
   order,
+  source,
   limit,
   cursor,
   includeReadme,
@@ -22740,6 +22901,40 @@ async function libraryLookup({
     return errorResult(new Error("Library step 1 has no `cursor`; it pages step-2 tags. Use `limit` for search, or pass `model`."));
   }
   try {
+    if (model && huggingFaceReference(model)) {
+      const hub2 = await huggingFace.lookup(model);
+      const { installed: installed2, installedUnavailable: installedUnavailable2, memoryBytes } = await localState();
+      const embedding = HUB_EMBEDDING_TASKS.has(hub2.task ?? "");
+      const { annotated, budget, best } = annotateTags(hub2.tags, installed2, memoryBytes, embedding);
+      const tagPage = pageLiveList(annotated, limit, cursor, (tag) => tag.tag);
+      return structuredResult({
+        family: hub2.family,
+        source: "huggingface",
+        sourcePage: hub2.url,
+        library: {
+          status: hub2.tags.length ? "available" : "no_gguf",
+          fetchedAt: hub2.fetchedAt,
+          task: hub2.task,
+          revision: hub2.revision,
+          ...hub2.gated ? { gated: hub2.gated, gatedNote: "Accept the repo's terms on Hugging Face first; its Ollama guide documents private pulls through your Ollama SSH key added to your Hugging Face account." } : {},
+          architecture: hub2.architecture,
+          contextLength: hub2.contextLength,
+          parameters: hub2.parameters,
+          downloads: hub2.downloads,
+          likes: hub2.likes,
+          updated: hub2.updated,
+          ...hub2.projectors.length ? { visionProjectors: hub2.projectors } : {}
+        },
+        ...installedUnavailable2 ? { installedUnavailable: installedUnavailable2 } : {},
+        machineMemoryBytes: memoryBytes,
+        fitBudgetBytes: budget,
+        tags: tagPage.items,
+        page: { returned: tagPage.returned, total: tagPage.total, next_cursor: tagPage.next_cursor },
+        pull: hub2.tags.length ? `ollama_manage {action:"pull", model:"<tag>"} after approval; Ollama picks Q4_K_M for a bare ${hub2.family} when the repo has it.` : "This repository has no GGUF files Ollama can pull.",
+        recommendationUnavailable: budget ? void 0 : NO_PROFILE,
+        recommendation: best ? libraryTrialCandidate(best.tag, embedding) : null
+      });
+    }
     if (model) {
       const ref = libraryReference(model);
       if (!ref) throw new Error("Use an exact Ollama family or namespace/model name, not a URL or path.");
@@ -22755,20 +22950,12 @@ async function libraryLookup({
       });
       const tags = library.tags;
       const { installed: installed2, installedUnavailable: installedUnavailable2, memoryBytes } = await localState();
-      const budget = memoryBytes ? memoryBytes * HOST_MEMORY_FIT_FRACTION : null;
-      const annotated = tags.map((t) => ({
-        ...t,
-        installed: installed2 ? installed2.has(t.tag) : null,
-        fitsInMemory: budget && t.sizeBytes ? t.sizeBytes <= budget : null,
-        fitScope: "host_memory_budget_only"
-      }));
-      const runnable = annotated.filter((t) => t.fitsInMemory === true && !t.cloud);
       const isEmbeddingFamily = library.card.capabilities.includes("embedding");
-      const sized = runnable.filter((t) => t.sizeBytes);
-      const best = budget ? isEmbeddingFamily ? sized.sort((a, b) => (a.sizeBytes ?? 0) - (b.sizeBytes ?? 0))[0] : sized.sort((a, b) => (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0))[0] : void 0;
+      const { annotated, budget, best } = annotateTags(tags, installed2, memoryBytes, isEmbeddingFamily);
       const tagPage = pageLiveList(annotated, limit, cursor, (tag) => tag.tag);
       return structuredResult({
         family,
+        source: "ollama",
         sourcePage: ref.url,
         library: {
           status: library.status,
@@ -22784,7 +22971,7 @@ async function libraryLookup({
         fitBudgetBytes: budget,
         tags: tagPage.items,
         page: { returned: tagPage.returned, total: tagPage.total, next_cursor: tagPage.next_cursor },
-        recommendationUnavailable: budget ? void 0 : "No machine profile (freellama serve unreachable), so memory fit could not be checked and no tag is recommended. Start serve, or read the sizes yourself.",
+        recommendationUnavailable: budget ? void 0 : NO_PROFILE,
         recommendation: best ? libraryTrialCandidate(best.tag, isEmbeddingFamily) : null
       });
     }
@@ -22792,20 +22979,44 @@ async function libraryLookup({
     for (const c of capabilities ?? []) params.append("c", c);
     if (query) params.set("q", query);
     if (order === "newest") params.set("o", "newest");
-    const search = await ollamaLibrary.search(params);
-    const url = search.url;
-    const parsed = search.models.slice(0, limit ?? 10);
+    const hubTasks = (capabilities ?? []).map((c) => HUB_TASKS.get(c));
+    const hubSkipped = source === "ollama" ? "source is ollama" : !query ? "the Hub is searched only with a query" : hubTasks.length > 1 || hubTasks.some((tasks) => !tasks) ? `the Hub has no filter for ${(capabilities ?? []).filter((c) => !HUB_TASKS.has(c)).join(", ") || "several capabilities at once"}` : null;
+    if (source === "huggingface" && hubSkipped) throw new Error(`source "huggingface" cannot be searched: ${hubSkipped}.`);
+    const searchHub = async () => {
+      const results = await Promise.all((hubTasks[0] ?? [void 0]).map((task) => huggingFace.search(query, { limit: limit ?? 10, order, task })));
+      const seen = /* @__PURE__ */ new Set();
+      const models = results.flatMap((r) => r.models).filter((m) => !seen.has(m.name) && seen.add(m.name)).sort((a, b) => order === "newest" ? String(b.updated).localeCompare(String(a.updated)) : (b.downloads ?? 0) - (a.downloads ?? 0)).slice(0, limit ?? 10);
+      return { url: results[0].url, models, fetchedAt: results[0].fetchedAt };
+    };
+    const [ollamaSearch, hubSearch] = await Promise.allSettled([
+      source === "huggingface" ? Promise.resolve(null) : ollamaLibrary.search(params),
+      hubSkipped ? Promise.resolve(null) : searchHub()
+    ]);
+    const tried = [source === "huggingface" ? null : ollamaSearch, hubSkipped ? null : hubSearch].filter(Boolean);
+    if (tried.every((result) => result.status === "rejected")) {
+      throw new Error(tried.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join("; "));
+    }
+    const ollama = ollamaSearch.status === "fulfilled" ? ollamaSearch.value : null;
+    const hub = hubSearch.status === "fulfilled" ? hubSearch.value : null;
+    const ollamaRows = (ollama?.models ?? []).slice(0, limit ?? 10).map((m) => ({ ...m, source: "ollama" }));
+    const hubRows = hub?.models ?? [];
     const { installed, installedUnavailable } = await localState();
-    const installedFamilies = installed ? new Set([...installed].map((n) => n.split(":")[0])) : null;
+    const local = installed ? [...installed].map((n) => n.toLowerCase()) : null;
+    const isInstalled = (name) => local ? local.some((n) => n.split(":")[0] === name.toLowerCase()) : null;
+    const reason = (result) => result.status === "rejected" ? result.reason instanceof Error ? result.reason.message : String(result.reason) : void 0;
     return structuredResult({
-      query: url,
-      fetchedAt: search.fetchedAt,
-      ...parsed.length === 0 ? { searchUnavailable: "No result cards were recognized. The query may have no matches or Ollama's markup may have changed; inspect the source URL." } : {},
+      query: ollama?.url ?? hub?.url ?? null,
+      ...ollama && hub ? { hubQuery: hub.url } : {},
+      fetchedAt: ollama?.fetchedAt ?? hub?.fetchedAt ?? null,
+      ...ollama && ollamaRows.length === 0 ? { searchUnavailable: "No ollama.com result cards were recognized. The query may have no matches or Ollama's markup may have changed; inspect the source URL." } : {},
+      ...reason(ollamaSearch) ? { ollamaUnavailable: reason(ollamaSearch) } : {},
+      ...reason(hubSearch) ? { huggingFaceUnavailable: reason(hubSearch) } : {},
+      ...hubSkipped && source !== "ollama" ? { huggingFaceSkipped: hubSkipped } : {},
       order: order ?? "popular",
-      count: parsed.length,
+      count: ollamaRows.length + hubRows.length,
       ...installedUnavailable ? { installedUnavailable } : {},
-      nextStep: 'Not pullable yet. Call again with view:"library", model:"<name>" to get tags, sizes and memory fit.',
-      models: parsed.map((m) => ({ ...m, installed: installedFamilies ? installedFamilies.has(m.name) : null }))
+      nextStep: 'Not pullable yet. Call again with view:"library", model:"<name>" (an Ollama family or hf.co/<owner>/<repo>) to get tags, sizes and memory fit.',
+      models: [...ollamaRows, ...hubRows].map((m) => ({ ...m, installed: isInstalled(m.name) }))
     });
   } catch (error2) {
     return errorResult(error2);
@@ -22815,7 +23026,7 @@ function registerModelsTool(server2) {
   server2.registerTool(
     "models",
     {
-      description: "Use when: listing installed or loaded models with capabilities, policy rank and memory fit, inspecting one model, or searching ollama.com (view:library). Do not use when: running work (run_task) or pulling (ollama_manage). Returns: models; library lists families first, then one family's tags.",
+      description: "Use when: listing installed or loaded models with capabilities, policy rank and memory fit, inspecting one model, or searching ollama.com and Hugging Face GGUF repos (view:library). Do not use when: running work (run_task) or pulling (ollama_manage). Returns: models; library lists families first, then one family's tags.",
       inputSchema: external_exports.object({
         view: external_exports.enum(["installed", "resident", "detail", "raw", "library"]).optional(),
         model: external_exports.string().min(1).optional(),
@@ -22823,8 +23034,9 @@ function registerModelsTool(server2) {
         includeLibrary: external_exports.boolean().optional(),
         includeReadme: external_exports.boolean().optional(),
         query: external_exports.string().min(1).optional(),
-        capabilities: external_exports.array(external_exports.enum(["vision", "tools", "thinking", "embedding", "cloud"])).min(1).max(5).optional(),
+        capabilities: external_exports.array(external_exports.string().regex(/^[a-z][a-z-]*$/).describe("ollama.com capability word, e.g. vision, tools, thinking, embedding, audio, decision, cloud")).min(1).max(8).optional(),
         order: external_exports.enum(["popular", "newest"]).optional(),
+        source: external_exports.enum(["ollama", "huggingface"]).optional(),
         limit: external_exports.number().int().positive().max(50).optional(),
         cursor: external_exports.string().min(1).optional(),
         endpoint: endpointParam,
@@ -22833,7 +23045,7 @@ function registerModelsTool(server2) {
       outputSchema: modelsResultSchema,
       annotations: { readOnlyHint: true }
     },
-    async ({ view, model, includeVerbose, includeLibrary, includeReadme, query, capabilities, order, limit, cursor, endpoint, ollamaEndpoint }) => {
+    async ({ view, model, includeVerbose, includeLibrary, includeReadme, query, capabilities, order, source, limit, cursor, endpoint, ollamaEndpoint }) => {
       try {
         const selectedView = view ?? "installed";
         if (includeLibrary !== void 0 && selectedView !== "installed" && selectedView !== "detail") {
@@ -22842,7 +23054,7 @@ function registerModelsTool(server2) {
         if (includeReadme !== void 0 && !(selectedView === "library" && model || selectedView === "detail" && includeLibrary === true)) {
           return errorResult(new Error('`includeReadme` needs library step 2, or view "detail" with `includeLibrary:true`.'));
         }
-        if (selectedView !== "library" && [query, capabilities, order].some((value) => value !== void 0)) {
+        if (selectedView !== "library" && [query, capabilities, order, source].some((value) => value !== void 0)) {
           return errorResult(new Error(`view "${selectedView}" does not accept library search fields.`));
         }
         if (selectedView !== "library" && selectedView !== "raw" && [limit, cursor].some((value) => value !== void 0)) {
@@ -22854,7 +23066,7 @@ function registerModelsTool(server2) {
         if (selectedView !== "detail" && selectedView !== "library" && model !== void 0) {
           return errorResult(new Error('`model` is valid only for views "detail" and "library".'));
         }
-        if (selectedView === "library" && model && [query, capabilities, order].some((value) => value !== void 0)) {
+        if (selectedView === "library" && model && [query, capabilities, order, source].some((value) => value !== void 0)) {
           return errorResult(
             new Error("Library step 2 accepts only `model` plus endpoint overrides; omit step-1 search fields.")
           );
@@ -22917,7 +23129,7 @@ function registerModelsTool(server2) {
             });
           }
           case "library":
-            return await libraryLookup({ model, query, capabilities, order, limit, cursor, includeReadme, endpoint, ollamaEndpoint });
+            return await libraryLookup({ model, query, capabilities, order, source, limit, cursor, includeReadme, endpoint, ollamaEndpoint });
           default: {
             const result = parsedResult(await listModels2(endpoint));
             if (!isStructuredSuccess(result)) return result;
@@ -23942,3 +24154,4 @@ registerOllamaLifecycleTools(server);
 registerDelegateResearchTool(server);
 var transport = withoutSchemaDialect(new StdioServerTransport());
 await server.connect(transport);
+startServeInBackground();