convez.ai
MCP ServerDesenvolvimento WebIntermediário
mcp-tool-shop-org

Ollama Intern MCP

mcp-tool-shop-org/ollama-intern-mcp

Estagiário local em MCP com 42 ferramentas, evidence-first e zero egress padrão

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que funciona como um estagiário local para Claude Code, oferecendo 42 ferramentas estruturadas com IDs de correlação, relatórios baseados em evidências e artefatos duráveis. Suporta roteamento opcional para Ollama Cloud com fallback automático para modelos locais, validado com Hermes Agent em hermes3:8b.

Instalação

$npx convez-ai mcp-tool-shop-org/ollama-intern-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 6 dias
Versão
v2.10.2
Issues abertas
10
Contribuidores
2

Casos de uso

  • Assistência de código local para Claude com 42 ferramentas estruturadas
  • Integração com Hermes Agent usando hermes3:8b ou qwen3
  • Processamento local-first com roteamento opcional para cloud (600B models) com fallback

Veredito

Ferramenta sofisticada de MCP que traz automação inteligente para o desenvolvimento local. Arquitetura bem pensada com tiering automático (Instant/Workhorse/Deep/Embed) e suporte a cloud-primary com fallback, mas requer setup técnico e conhecimento de MCP/Ollama para aproveitar ao máximo.

README

A tradução para o português deste README ainda está na fila.

The local intern for Claude Code. 42 job-shaped tools, evidence-first briefs, durable artifacts.

An MCP server that gives Claude Code a local intern with rules, tiers, a desk, and a filing cabinet. Claude picks the tool; the tool picks the tier (Instant / Workhorse / Deep / Embed); the tier writes a file you can open next week.

Also drives Hermes Agent on hermes3:8b — validated end-to-end 2026-04-19. The default ladder is hermes3:8b; qwen3:* is the alternate rail. See Use with Hermes below.

Hardware requirements: ~6 GB VRAM for hermes3:8b, or ~16 GB RAM for CPU inference. See handbook/getting-started for the full breakdown.

Not using Claude? The examples/ directory has a minimal Node.js and Python MCP client you can spawn over stdio. See also handbook/with-hermes.

Local-first — zero network egress until you opt in. No telemetry. No "autonomous" anything. Every call shows its work. Optional Ollama Cloud routing puts 600B-class models behind the same tools when local hardware is the bottleneck — with automatic fallback to local.


New in v2.7.0

Optional Ollama Cloud routing — cloud-primary, local-fallback. Opt in with a key + a flag and the generative tiers route to a 600B-class cloud model; embeddings stay local; a circuit breaker falls back to your local profile on any cloud failure. Off by default — zero egress unless you set both OLLAMA_API_KEY and OLLAMA_CLOUD_PRIMARY=1. Additive minor — pre-v2.7.0 callers (and anyone not opting in) see byte-identical behavior. See Ollama Cloud (optional).

  • Cloud-primary with a safety net. A RoutingOllamaClient tries cloud first and falls back to the local profile on timeout / 5xx / 429 / network. Bad keys (401/403) surface loudly via a sticky breaker instead of degrading silently forever; a retired/typo'd cloud model id (404) surfaces too.
  • Never a silent downgrade. Every envelope gains backend (cloud|local), degraded, and degrade_reason so you always know when you got the local model instead of the big one. A backend_fallback NDJSON event makes the cloud→local fallback rate visible in ollama_log_tail.
  • ollama_doctor reports cloud auth + reachability as a distinct block; ollama-intern-mcp doctor shows a Cloud (primary) section.
  • Default cloud model is minimax-m3:cloud; override per-tier with INTERN_CLOUD_MODEL / INTERN_CLOUD_DEEP_MODEL (e.g. deepseek-v3.1:671b).

New in v2.6.0

Per-call tier-budget override on ollama_extract. Additive minor — pre-v2.6.0 callers unchanged. Detailed entry in CHANGELOG.md.

  • tier_budget_ms_override?: number schema field on ollama_extract (optional, bounded [1, 600000] ms). When present, applies the override to every tier visited by the runner so the inner runWithTimeoutAndFallback machinery at src/guardrails/timeouts.ts:61 honors the operator-supplied budget instead of the profile default. The cascade (workhorse → instant on timeout) still fires; the override governs each cascade hop uniformly.
  • Why this exists. The research-os R-018 wrapper (v0.12.1) wrapped MCP callTool with Promise.race and found the wrapper's budget did not reach the inner tier — DEV_RTX5080_TIMEOUTS.instant = 15_000 continued to fire TIER_TIMEOUT at 15000ms regardless of a 180000ms wrapper budget. v2.6.0 supplies the MCP-side authoritative budget so the operator's --planner-timeout-ms flag (research-os) finally controls inner-tier timeouts as designed.
  • Default behavior preserved. Field omitted = profile defaults govern byte-identically. Pre-v2.6.0 callers see zero change.
  • R-010 fallback-cause regex preserved. Server-side TIER_TIMEOUT error message still matches /elapsed=(\d+)ms/ + /budget=(\d+)ms/ so AI-advisor visibility downstream works on override and default paths alike.
  • Consumed by research-os v0.13.0 (cumulative R-019 client wire-up + R-020 + R-021) in a coordinated multi-repo release.

Historical — v2.4.0 deliverables

See CHANGELOG.md and docs/release-notes/v2.4.0.md for the full v2.4.0 entry (per-tier num_ctx control on the profile system).

New in v2.4.0

Per-tier num_ctx (context window) control on the profile system. Additive minor — v2.3.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.4.0.md.

  • TierConfig.num_ctx map (new) — optional { instant?, workhorse?, deep?, embed? } on the profile. When set for a tier, the MCP server places options.num_ctx = <value> on every Ollama generate/chat request routed to that tier (initial + fallback). When unset, the request omits num_ctx entirely so Ollama uses its model-loaded default — v2.3.0 behavior preserved exactly.
  • New envelope field num_ctx_used?: number — present only when the MCP server actually sent num_ctx. Absent when the request let Ollama choose. Do not infer a default — the MCP server does not query Ollama for the effective value.
  • Profile defaults: dev-rtx5080 / dev-rtx5080-qwen3 ship with instant: 4096, workhorse: 8192, deep/embed UNSET. Sized to keep hermes3:8b resident in the RTX 5080's 16GB VRAM budget for fast tools. m5-max leaves every tier UNSET — 128GB unified memory has no spill problem.
  • Closes the v0.8.0 Phase 1 diagnostic — hermes3:8b at the default 32K context on RTX 5080 spilled to CPU and started timing out workhorse ollama_extract calls. v2.4.0 prevents that at the profile layer.

Per-tier num_ctx control (new in v2.4.0)

Profile (excerpt from src/profiles.ts):

"dev-rtx5080": {
  tiers: {
    instant: "hermes3:8b",
    workhorse: "hermes3:8b",
    deep: "hermes3:8b",
    embed: "nomic-embed-text",
    num_ctx: {
      instant: 4096,    // fast classify/summarize
      workhorse: 8192,  // schema-bound extract / batch
      // deep: UNSET — long-context briefs keep current behavior
      // embed: UNSET — no context-window pressure on embed
    },
  },
  // ... timeouts, prewarm
}

Envelope on a workhorse-tier call (e.g. ollama_extract):

{
  "result": { /* extracted data */ },
  "tier_used": "workhorse",
  "model": "hermes3:8b",
  "num_ctx_used": 8192,        // present because the profile set workhorse=8192
  // ... rest of envelope unchanged
}

On m5-max (or any profile that leaves a tier unset), num_ctx_used is absent from the envelope and the wire request to Ollama does not include the num_ctx field — Ollama uses its model-loaded default.

Operators tune by selecting / editing the profile; there is no per-call num_ctx input on tool schemas. If a future call surfaces the need, the pattern follows v2.3.0's model override.

Historical — v2.3.0 deliverables

See CHANGELOG.md and docs/release-notes/v2.3.0.md for the full v2.3.0 entry (per-call model override).

New in v2.3.0

Per-call model override across LLM-backed atom tools. Additive minor — v2.2.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.3.0.md.

  • Optional model: string input on 8 atom tools — ollama_extract, ollama_classify, ollama_summarize_fast, ollama_summarize_deep, ollama_research, ollama_corpus_answer, ollama_chat, ollama_code_citation. The first attempt on the tool's tier runs against the caller-specified model; on timeout, the existing TIER_FALLBACK cascade resolves the cheaper tier's own model (NOT the caller's override). Composite/brief/pack tools deliberately do NOT accept model — atoms get per-call control, composites use tier defaults.
  • New envelope field model_requested?: string — present only when the override was supplied. Calibration-aware callers compare model_requested vs model to detect fallback substitution: if (env.model_requested && env.model !== env.model_requested) { /* substitution */ }. Empty / whitespace-only inputs throw ZodError at schema parse, not silent fallthrough.
  • Bug fix — src/version.ts drift. The runtime VERSION constant is now read from package.json at module load; v2.1.0 and v2.2.0 had shipped reporting the stale "2.0.0" identity string. New tests/version.test.ts locks VERSION === pkg.version.

Per-call model override (new in v2.3.0)

{
  "tool": "ollama_classify",
  "arguments": {
    "text": "patch null pointer in auth",
    "labels": ["feat", "fix", "chore"],
    "frame": "what is the change kind?",
    "model": "hermes3:8b"
  }
}

Envelope:

{
  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
  "tier_used": "instant",
  "model": "hermes3:8b",
  "model_requested": "hermes3:8b",       // present because override was supplied
  // ... rest of envelope unchanged
}

If the workhorse/deep tier had timed out and the call had cascaded to the instant tier, env.model would be the instant tier's resolved model and env.fallback_from would be "workhorse" — env.model_requested would still be "hermes3:8b", and env.model !== env.model_requested is the substitution signal. The override is deliberately NOT carried into the cheaper tier; the chosen model may not fit that tier's role at all.

Historical — v2.2.0 deliverables

See CHANGELOG.md and docs/release-notes/v2.2.0.md for the full v2.2.0 entry (frame-bound topicality + structured abstention).

New in v2.2.0

Local evidence-worker role contract: frame-bound topicality and structured abstention. Additive minor — v2.1.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.2.0.md.

  • Frame-bound extraction on ollama_extract, ollama_classify, ollama_summarize_fast, ollama_summarize_deep — optional frame: string input + structured frame_alignment / on_topic / frame_addressed outputs. Off-topic sources are flagged instead of paraphrased into the schema.
  • Structured abstention on ollama_research — weak / abstained / sources_address_question fields. Empty citations[] with non-empty answer is no longer silent success.
  • Topicality threshold on ollama_corpus_answer — optional min_top_score. Below the floor, the tool short-circuits with abstained: true and skips synthesis. Per-citation score now visible on each citation.
  • Retrieval score preservation through brief evidence — corpusHitsToEvidence carries score (and corpus_min_evidence_score knob filters at assembly time on incident_brief / repo_brief / change_brief).
  • Citation line-range bounds — guardrails/citations.ts rejects out-of-bounds ranges on ollama_research, matching the existing posture on ollama_code_citation.
  • Operator-contract docs corrected — README chunk_id/chunk_index fix, "validated server-side" rewritten, Evidence Laws section qualified, marketing slogan annotated.

Seed regression — the verification

The slice's contract is verified against the literal research-os fresh-pack failure: arxiv 2112.10422 (Cosmological Standard Timers) under the section-01 frame "What does evidence custody mean in local-first vs cloud LLM deep-research workflows?" — 9 / 9 mocked-LLM contract tests confirm the off-topic source is now contained (frame_alignment.on_topic = false on extract; off_topic: true on classify; frame_addressed: false on summarize_deep; abstained: true on corpus_answer with min_top_score set).

Historical — v2.1.0 deliverables

See CHANGELOG.md for the full v2.1.0 entry (feature pass: 13 new tools + 4 enhancements + freeze lift).


Architecture at a glance

flowchart LR
  Claude["Claude Code<br/>(MCP client)"]
  MCP["ollama-intern-mcp<br/>server (stdio)"]
  Ollama["Ollama daemon<br/>(127.0.0.1:11434)"]
  Models[("Hermes 3 / Qwen 3<br/>nomic-embed-text")]
  Corpus[("~/.ollama-intern/<br/>corpora/")]
  Artifacts[("~/.ollama-intern/<br/>artifacts/")]
  NDJSON[("~/.ollama-intern/<br/>log.ndjson")]
  Guards{{"Guardrails<br/>citations · banned phrases<br/>protected paths · confidence"}}

  Claude -- "JSON-RPC over stdio" --> MCP
  MCP --> Guards
  MCP -- "/api/generate · /api/chat<br/>/api/embed · /api/ps · /api/tags" --> Ollama
  Ollama --> Models
  MCP --- Corpus
  MCP --- Artifacts
  MCP --> NDJSON

Every Claude tool call enters the MCP server over stdio JSON-RPC. The server validates the call against the tool's zod schema, runs the configured guardrails (citation validation, banned-phrase strip, protected-path enforcement, confidence thresholds), then routes to either a deterministic renderer (artifact tier) or an Ollama HTTP call (every other tier). The Ollama daemon never sees user-supplied paths — only the model tier and the prepared prompt. Every call appends one structured event to the NDJSON log at ~/.ollama-intern/log.ndjson, where ollama_log_tail and your shell can read it.


Lead example — one call, one artifact

// Claude → ollama-intern-mcp
{
  "tool": "ollama_incident_pack",
  "arguments": {
    "title": "sprite pipeline 5 AM paging regression",
    "logs": "[2026-04-16 05:07] worker-3 OOM killed\n[2026-04-16 05:07] ollama /api/ps reports evicted=true size=8.1GB\n...",
    "source_paths": ["F:/AI/sprite-foundry/src/worker.ts", "memory/sprite-foundry-visual-mastery.md"]
  }
}

Returns an envelope pointing at a file on disk:

{
  "result": {
    "pack": "incident",
    "slug": "2026-04-16-sprite-pipeline-5-am-paging-regression",
    "artifact_md":   "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.md",
    "artifact_json": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.json",
    "weak": false,
    "evidence_count": 6,
    "next_checks": ["residency.evicted across last 24h", "OLLAMA_MAX_LOADED_MODELS vs loaded size"]
  },
  "tier_used": "deep",
  "model": "hermes3:8b",
  "hardware_profile": "dev-rtx5080",
  "tokens_in": 4180, "tokens_out": 612,
  "elapsed_ms": 8410,
  "residency": { "in_vram": true, "evicted": false }
}

→ weak: false means ≥2 evidence items were assembled; it does NOT mean the hypotheses are vetted. See Evidence laws below.

That markdown file is the intern's desk output — headings, evidence block with cited ids, investigative next_checks, weak: true banner if evidence is thin. It's deterministic: the renderer is code, not a prompt. (The renderer is deterministic; the content of hypotheses and surfaces is generative — read them as draft, not verified.) Open it tomorrow, diff it next week, export it into a handbook with ollama_artifact_export_to_path.

Every competitor in this category leads with "save tokens." We lead with here is the file the intern wrote.

Second example — build a corpus, then ask it

// 1. Build a persistent, searchable corpus over your project.
{ "tool": "ollama_corpus_index",
  "arguments": { "name": "sprite-foundry",
                 "paths": ["F:/AI/sprite-foundry/src"],
                 "embed_model": "nomic-embed-text" } }
// → { chunks_written: 1204, paths_indexed: 312, failed_paths: [] }

// 2. Ask an evidence-bound question against it.
{ "tool": "ollama_corpus_answer",
  "arguments": { "name": "sprite-foundry",
                 "query": "how does the worker handle OOM eviction?",
                 "top_k": 8 } }
// → { answer: "...", citations: [{chunk_index, path}...], weak: false }

The server validates citation identity and that each chunk_index is in range of the retrieved hits. It does NOT prove that every generated claim is semantically supported by the cited chunk content — that's the model's responsibility, and weak retrieval can still produce citation-shaped answers. Full walkthrough in handbook/corpora.


Frame-bound extraction (new in v2.2.0)

ollama_extract, ollama_classify, ollama_summarize_fast, and ollama_summarize_deep accept an optional frame: string input. The frame names the question the source is being asked to answer; the model is instructed to abstain rather than emit true-but-off-topic content when the source doesn't address the frame.

{
  "tool": "ollama_extract",
  "arguments": {
    "text": "<long source document>",
    "schema": { /* your fields */ },
    "frame": "section purpose here — e.g. 'OOM eviction behavior in the sprite worker'"
  }
}
// → result includes frame_alignment: { on_topic: boolean, reason: string, unaddressed_aspects: string[] }

If frame is omitted, behavior is unchanged from v2.1.0. When supplied, frame_alignment.on_topic = false signals that extracted fields may be true-of-the-source but not relevant to the frame — treat that as the same shape as a weak: true brief: useful, but spot-check before promoting into downstream evidence.


Abstention contract (new in v2.2.0)

ollama_research returns structured abstention fields: weak: boolean, abstained: boolean, sources_address_question: boolean | null. An empty citations[] with a non-empty answer is no longer silent — abstained: true says the model declined to synthesize because the caller-supplied paths did not address the question. Treat abstention as a success, not a failure: it is the tool refusing to launder weak retrieval into authoritative output.

ollama_corpus_answer accepts an optional min_top_score: number topicality threshold (0.0–1.0). When the top retrieval score for a query falls below min_top_score, the tool short-circuits with abstained: true and skips synthesis — preventing the "5 off-topic chunks at score 0.21 still drive a full answer" failure mode that the v2.1.0 weak: true rule did not catch (weak: true only fired on hits.length < 2). Pair this with the per-citation score field newly surfaced on each citation to audit retrieval quality directly from the envelope.


What's in here — four tiers, 42 tools

Job-shaped means each tool names a job you'd hand to an intern — classify this, extract that, triage these logs, draft this release note, pack this incident. The tool's input is the job spec; the output is the deliverable. No generic run_model / chat_with_llm primitive at the top.

TierCountWhat lives here
Atoms28Job-shaped primitives. Original 15: classify, extract, triage_logs, summarize_fast / deep, draft, research, corpus_search / answer / index / refresh / list, embed_search, embed, chat. +13 added in v2.1.0: doctor, log_tail, batch_proof_check (ops); code_map, code_citation, multi_file_refactor_propose, refactor_plan (refactor); artifact_prune, hypothesis_drill (artifact/brief); corpus_health, corpus_amend, corpus_amend_history, corpus_rerank (corpus). Batch-capable atoms (classify, extract, triage_logs) accept items: [{id, text}].
Briefs3Evidence-backed structured operator briefs. incident_brief, repo_brief, change_brief. Every claim cites an evidence id; unknowns stripped server-side. Weak evidence surfaces weak: true rather than fake narrative.
Packs3Fixed-pipeline compound jobs that write durable markdown + JSON to ~/.ollama-intern/artifacts/. incident_pack, repo_pack, change_pack. Deterministic renderers — no model calls on the artifact shape.
Artifacts7Continuity surface over pack outputs. artifact_list / read / diff / export_to_path, plus three deterministic snippets: incident_note, onboarding_section, release_note.

Total: 28 atoms + 3 briefs + 3 packs + 7 artifact tools = 42.

Freeze lines:

  • Atoms: freeze lifted at v2.1.0 (28 today; +13 added in the v2.1.0 feature pass). New atoms still require an audit-justified gap, tests, handbook page, and CHANGELOG entry — no casual additions.
  • Packs frozen at 3. No new pack types.
  • Artifact tier frozen at 7.

The full tool reference lives in the handbook.


Install

Requires Ollama running locally and the tier models pulled (see Model pulls below).

Claude Code (recommended)

Most users install this by adding it to their Claude Code MCP server config — no global install required. Claude Code runs the server on demand via npx:

{
  "mcpServers": {
    "ollama-intern": {
      "command": "npx",
      "args": ["-y", "ollama-intern-mcp"],
      "env": {
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "INTERN_PROFILE": "dev-rtx5080"
      }
    }
  }
}

Claude Desktop

Same block, written to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Global install (advanced)

Only needed if you want the binary on your PATH for ad-hoc use outside Claude Code:

npm install -g ollama-intern-mcp

Use with Hermes

This MCP was validated end-to-end with Hermes Agent against hermes3:8b on Ollama (2026-04-19). Hermes is an external agent that calls into this MCP's frozen primitive surface — it does the planning, we do the work.

Reference config (hermes.config.example.yaml in this repo):

model:
  provider: custom
  base_url: http://localhost:11434/v1
  default: hermes3:8b
  context_length: 65536    # Hermes requires 64K floor under model.*

providers:
  local-ollama:
    name: local-ollama
    base_url: http://localhost:11434/v1
    api_mode: openai_chat
    api_key: ollama
    model: hermes3:8b

mcp_servers:
  ollama-intern:
    command: npx
    args: ["-y", "ollama-intern-mcp"]
    env:
      OLLAMA_HOST: http://localhost:11434
      INTERN_PROFILE: dev-rtx5080
      # hermes3:8b is the default ladder in v2.0.0, so tier overrides are
      # only needed if you're pinning a different local model.

Prompt shape matters. Imperative tool-invocation prompts ("Call X with args …") are the integration test — they give an 8B local model enough scaffolding to emit clean tool_calls. List-form multi-task prompts ("do A, then B, then C") are capability benchmarks for larger models; don't interpret a list-form failure on 8B as "the wiring is broken." See handbook/with-hermes for the full integration walkthrough + known transport caveats (Ollama /v1 streaming + openai-SDK non-streaming shim).

Model pulls

Default dev profile (RTX 5080 16GB and similar):

ollama pull hermes3:8b
ollama pull nomic-embed-text
export OLLAMA_MAX_LOADED_MODELS=2
export OLLAMA_KEEP_ALIVE=-1

Qwen 3 alternate rail (same hardware, for Qwen tooling):

ollama pull qwen3:8b
ollama pull qwen3:14b
ollama pull nomic-embed-text
export INTERN_PROFILE=dev-rtx5080-qwen3

M5 Max profile (128GB unified):

ollama pull qwen3:14b
ollama pull qwen3:32b
ollama pull nomic-embed-text
export INTERN_PROFILE=m5-max

Per-tier env vars (INTERN_TIER_INSTANT, INTERN_TIER_WORKHORSE, INTERN_TIER_DEEP, INTERN_EMBED_MODEL) still override profile picks for one-offs.


Uniform envelope

Every tool returns the same shape:

{
  result: <tool-specific>,
  tier_used: "instant" | "workhorse" | "deep" | "embed",
  model: string,
  hardware_profile: string,     // "dev-rtx5080" | "dev-rtx5080-qwen3" | "m5-max"
  tokens_in: number,
  tokens_out: number,
  elapsed_ms: number,
  residency: {
    in_vram: boolean,
    size_bytes: number,
    size_vram_bytes: number,
    evicted: boolean
  } | null
}

residency comes from Ollama's /api/ps. When evicted: true or size_vram < size, the model paged to disk and inference dropped 5–10× — surface this to the user so they know to restart Ollama or trim loaded-model count.

In Ollama Cloud mode the envelope also carries backend ("cloud" | "local") and, on a cloud→local fallback, degraded: true + degrade_reason. These fields are absent in the default local-only path, so existing consumers are unaffected. residency is null for cloud-served calls (the stateless cloud has no local-VRAM residency).

Every call is logged as one NDJSON line to ~/.ollama-intern/log.ndjson. Filter by hardware_profile to keep dev numbers out of publishable benchmarks.


Hardware profiles

ProfileInstantWorkhorseDeepEmbed
dev-rtx5080 (default)hermes3 8Bhermes3 8Bhermes3 8Bnomic-embed-text
dev-rtx5080-qwen3qwen3 8Bqwen3 8Bqwen3 14Bnomic-embed-text
m5-maxqwen3 14Bqwen3 14Bqwen3 32Bnomic-embed-text

Default dev collapses all three work tiers onto hermes3:8b — the validated Hermes Agent integration path. Same model top to bottom means there is one thing to pull, one residency cost, one set of behavior to understand. Users who prefer Qwen 3 (with its THINK_BY_SHAPE plumbing) opt into dev-rtx5080-qwen3. m5-max is the Qwen 3 ladder sized for unified memory.


Ollama Cloud (optional)

Local 8B models are the hardware bottleneck most people hit. Ollama Cloud serves 600B-class models behind the same /api/* surface, so you can route the heavy tools to a far stronger model and free up local VRAM — while keeping local as an always-on fallback.

This is opt-in and off by default. The package stays local-first with zero egress unless you set both of these. Anyone who doesn't opt in is unaffected.

{
  "mcpServers": {
    "ollama-intern": {
      "command": "npx",
      "args": ["-y", "ollama-intern-mcp"],
      "env": {
        "OLLAMA_CLOUD_PRIMARY": "1",
        "OLLAMA_API_KEY": "sk-...your-key...",
        "INTERN_PROFILE": "dev-rtx5080"
      }
    }
  }
}

The key is a runtime env var, not a CI secret. A GitHub Actions secret is only visible inside CI runs — it never reaches the running server. Create a key at ollama.com/settings/keys and put it in your MCP client's env block (or your shell environment).

How routing works. When cloud is on, the generative tiers (instant / workhorse / deep) go to the cloud model; embeddings always stay local (Ollama Cloud serves no embedding models, so the corpus/embed tools are unaffected). A circuit breaker tries cloud first and falls back to your local profile on timeout / 5xx / 429 / network errors. A bad key (401/403) trips a sticky breaker that surfaces loudly rather than degrading silently. The local profile (INTERN_PROFILE) is the fallback ladder, so keep its models pulled.

You're never silently downgraded. Every envelope reports which backend served the call:

{ ...envelope, backend: "cloud" | "local", degraded?: true, degrade_reason?: "cloud_timeout" | "cloud_5xx" | "cloud_rate_limited" | "cloud_unreachable" | "cloud_auth_failed" | "circuit_open" }

A backend_fallback line lands in ~/.ollama-intern/log.ndjson on every cloud→local fallback (ollama_log_tail --filter_kind backend_fallback), and ollama-intern-mcp doctor shows a Cloud (primary) block with reachability + auth status.

Latency vs quality. Big cloud models run far slower per token than a local 8B (seconds, not milliseconds) — a quality upgrade, not a speed one. Cloud tiers use a generous timeout ladder (instant 30s / workhorse 120s / deep 300s by default).

Cloud env vars

VarDefaultPurpose
OLLAMA_CLOUD_PRIMARY(unset)The opt-in switch. 1/true/yes/on enables cloud-primary. Unset = local-only, zero egress.
OLLAMA_API_KEY(unset)Bearer key for Ollama Cloud. Required when cloud is enabled (fail-fast at startup if missing).
OLLAMA_CLOUD_HOSThttps://ollama.comCloud base host.
INTERN_CLOUD_MODELminimax-m3:cloudCloud model for instant + workhorse + deep.
INTERN_CLOUD_DEEP_MODEL(= INTERN_CLOUD_MODEL)Optional deep-tier-only override, e.g. deepseek-v3.1:671b.
INTERN_CLOUD_TIMEOUT_{INSTANT,WORKHORSE,DEEP}_MS30000/120000/300000Per-tier cloud-attempt timeouts.
INTERN_CLOUD_NUM_CTX32768Context-window cap for cloud calls (cloud bills by GPU-time; cap controls cost).

Model availability changes. Ollama periodically retires cloud models. minimax-m3:cloud, deepseek-v3.1:671b, gpt-oss:120b, and qwen3-coder:480b are current picks; check ollama.com/search?c=cloud before pinning an id.

Privacy note. Routing to Ollama Cloud sends prompts to a third party. Ollama's privacy policy states cloud prompts are processed transiently, not retained beyond the request, and not used for training — but it is still egress, which is why it's opt-in and disclosed. Local-only mode (the default) sends nothing off the box.


Evidence laws

These are enforced in the server, not the prompt:

  • Citations required. Every brief claim cites an evidence id.
  • Unknowns stripped server-side. Models that cite ids not in the evidence bundle have those ids dropped with a warning before the result returns.
  • ID-validated, not content-validated. Server checks that every cited evidence_ref points to a real evidence id in the assembled set. It does NOT verify that the claim text is derivable from the cited evidence — that is the model's job, and weak briefs sometimes contain unsupported claims with valid refs. Use weak: true + coverage_notes + the included excerpt field to spot-check.
  • Weak is weak. Thin evidence flags weak: true with coverage notes. Never smoothed into fake narrative.
  • Investigative, not prescriptive. next_checks / read_next / likely_breakpoints only. Prompts forbid "apply this fix."
  • Deterministic renderers. Artifact markdown shape is code, not a prompt. draft stays reserved for prose where model wording matters.
  • Same-pack diffs only. Cross-pack artifact_diff is refused loudly; payloads stay distinct.

Artifacts & continuity

Packs write to ~/.ollama-intern/artifacts/{incident,repo,change}/<slug>.(md|json). The artifact tier gives you a continuity surface without turning this into a file-management tool:

  • artifact_list — metadata-only index, filterable by pack, date, slug glob
  • artifact_read — typed read by {pack, slug} or {json_path}
  • artifact_diff — structured same-pack comparison; weak-flip surfaced
  • artifact_export_to_path — writes an existing artifact (with provenance header) to a caller-declared allowed_roots. Refuses existing files unless overwrite: true.
  • artifact_incident_note_snippet — operator-note fragment
  • artifact_onboarding_section_snippet — handbook fragment
  • artifact_release_note_snippet — DRAFT release-note fragment

No model calls in this tier. All render from stored content.


Threat model & telemetry

Data touched: file paths the caller explicitly hands in (ollama_research, corpus tools), inline text, and artifacts the caller asks to be written under ~/.ollama-intern/artifacts/ or a caller-declared allowed_roots.

Data NOT touched: anything outside source_paths / allowed_roots. .. is rejected before normalize. artifact_export_to_path refuses existing files unless overwrite: true. Drafts targeting protected paths (memory/, .claude/, docs/canon/, etc.) require explicit confirm_write: true, enforced server-side.

Network egress: off by default. Out of the box the only outbound traffic is to the local Ollama HTTP endpoint — no cloud calls, no update pings, no crash reporting. Opt-in exception: if you enable Ollama Cloud (OLLAMA_CLOUD_PRIMARY=1 + OLLAMA_API_KEY), prompts for the generative tiers are sent to ollama.com over HTTPS with a Bearer key. This is explicit, disclosed, and off unless you set both vars; embeddings still never leave the box. See SECURITY.md §11.

Telemetry: none. Every call is logged as one NDJSON line to ~/.ollama-intern/log.ndjson on your machine. The server itself phones home to nothing.

Errors: structured shape { code, message, hint, retryable }. Stack traces are never exposed through tool results.

Full policy: SECURITY.md.


Standards

Built to the Shipcheck bar. Hard gates A–D pass; see SHIP_GATE.md and SCORECARD.md.

  • A. Security — SECURITY.md, threat model, no telemetry, path-safety, confirm_write on protected paths
  • B. Errors — structured shape across all tool results; no raw stacks
  • C. Docs — README current, CHANGELOG, LICENSE; tool schemas self-document
  • D. Hygiene — npm run verify (full vitest suite), CI with dep scanning, Dependabot, lockfile, engines.node

Roadmap (hardening, not scope creep)

  • Phase 1 — Delegation Spine ✓ shipped: atom surface, uniform envelope, tiered routing, guardrails
  • Phase 2 — Truth Spine ✓ shipped: schema v2 chunking, BM25 + RRF, living corpora, evidence-backed briefs, retrieval eval pack
  • Phase 3 — Pack & Artifact Spine ✓ shipped: fixed-pipeline packs with durable artifacts + continuity tier
  • Phase 4 — Adoption Spine ✓ v2.0.1: three-stage health pass hardened corpus (TOCTOU, 50 MB file cap, symlink rejection, atomic writes, per-file failure capture), tool path traversal, observability (semaphore wait events, timeout error context, profile env-override logging, prewarm cold-start signal), test safety (module-load env snapshot across 10 files, tools/call E2E). Troubleshooting handbook + hardware minimums added for operators.
  • Phase 5 — M5 Max benchmarks — publishable numbers once the hardware lands (~2026-04-24)

Phase by hardening layer. Pack and artifact tiers stay frozen at 3 and 7. The atom freeze was lifted at v2.1.0 — new atoms require an audit-justified gap, tests, handbook page, and CHANGELOG entry.


License

MIT — see LICENSE.


Ver o original no GitHub

Bom para

Relacionados