ollama-mcp-server

A thin TypeScript MCP server for delegating bounded work to Ollama and for inspecting repositories without spending the host agent's context on bulk work. It runs over stdio with npm start; there is no build step.

For a concise orientation to the repository layout and the purpose of each tracked file, start with the project map.

Supported now

The default MCP surface is intentionally small.

Basic Ollama tools

• run_ollama_task sends one stateless task to an Ollama model.

• summarize_output condenses large text through Ollama. Pass text, or repository_root + path to read a file (max 2 MB) inside the bridge.

• list_ollama_models lists available local or signed-in models.

Quality Review

The separate read-only CLI scans JavaScript/TypeScript functions into SQLite, reviews a bounded queue, and saves reports under the target repository's .quality-review/ directory. It never changes target source files.

npm run quality -- scan --cwd /path/to/repo
npm run quality -- review --count 10 --cwd /path/to/repo
npm run quality -- status --cwd /path/to/repo

Findings can later be inspected and marked accepted or rejected; those decisions are metadata only. See the Quality Review guide.

Lean Explorer

The default Explorer uses deterministic repository intelligence:

• outline_file and read_symbol

• find_symbol, find_references, find_callers, and find_callees

• hybrid_retrieve in basic mode, combining lexical and structural ranking with relevant documentation and package scripts

basic mode does not use embeddings or autonomous model planning. A client can retrieve likely symbols, read focused source, and summarize the evidence. Use mode: "lexical" for the narrow symbol baseline. mode: "hybrid" is available only when semantic search and Git-history intelligence are enabled.

The supported implementation is isolated in src/explorer/. Advanced and autonomous code is parked under src/experimental/ and is not imported during default startup.

Deterministic CLI entry points remain available, for example:

npm run index:super-explorer -- /path/to/repo
npm run hybrid:super-explorer -- basic /path/to/repo "where is config loaded"

Related MCP server: Ollama MCP Server

Experimental and disabled by default

Experimental code remains in the repository, but its MCP tools are not registered unless enabled. ENABLE_EXPERIMENTAL=1 enables all experimental groups; a group-specific 0 can override the master flag.

local_explore_repo is the preferred model-backed scout. It retrieves basic candidates, merges bounded source windows and caller context, and asks the model to select up to sixteen evidence line references per question part. The server shortlists lines for each evidence requirement, constrains output refs to supplied lines, copies quotes from source, and retries once while retaining checked partial citations. Image workflows and query/list questions have explicit operation checklists and separate source windows. These checklists preserve absent-file fallback branches and recognize provider-name phrasing. Recognized named image operations require method declarations and conditions/errors from the same indexed method. Cleanup-error contrasts keep upload and helper evidence separate; the parent inspects the helper to establish suppression. These checks guide selection but do not prove semantic completeness across providers or branches. Unchecked completeness, empty checklists and missing requirements return needs_review. Recognized bounded coverage checks remain heuristics; the parent still interprets behavior.

Local delegation, summaries and both scout routes default to qwen-context:h-q4_0-24k. They inherit the selected model's saved num_ctx. Default output reserves are the smaller of its finite saved ceiling and 8192 for delegation/summaries or 2048 for either scout. Optional request fields override these limits explicitly; long output needs a larger num_predict. H defaults to 24576 context / 16000 saved output. The desktop GPU report records the 50K/32K offload and verified 24K placement. The retained qwen-context:h-q4_0-50k is an explicit option for larger inputs; it can offload under desktop memory pressure. At the default output reserves, 24K leaves 15360 input tokens for delegation/summaries and 21504 for scouts, before prompt/schema charges. Oversized inputs still return input_overflow. Restart the MCP server through your client to load the new default. In Codex for VS Code, run Developer: Reload Window from the command palette to start a fresh server process. Existing clients explicitly requesting 50K must select the new tag or omit model. Budget metadata identifies limits from the model, tool policy, or request. Advanced discovery/verification also inherit saved settings. Missing saved limits use reported 16384/8192 fallbacks; unbounded output defaults require an explicit finite ceiling. generate() continues to return text. Model settings are cached per tag for up to 60 seconds, including concurrent requests. Restart the server after editing a tag to refresh them immediately.

H generation requests use the installed GGUF vocabulary and Qwen35 byte BPE to count system text, source and the rendered assistant framing. The matching weights and named renderer must be present locally; other configurations, thinking requests and tokenizer failures keep the conservative UTF-8 byte bound. The legacy chat scout also keeps byte accounting. Schema bytes remain an additional reserve, and all routes retain the 1024-token safety margin. Oversized requests return input_overflow; source is never silently omitted and explicit output overrides are preserved. Generation tools and the deterministic-first scout report byte charges alongside the accounting method. Byte fallback can reject requests whose actual token count would fit. In particular, Explicitly reserving I's full 25000 ceiling at 32768 context leaves only 6744 input tokens. KV precision is a daemon setting: I needs a q8 daemon; its tag alone cannot change the current q4 daemon. See the context checklist.

run_ollama_task and summarize_output accept timeout_ms from 1000 through 900000; omission uses the configured server deadline (120 seconds by default). Their _meta.completion reports stop reason, token counts and raw Ollama timings in nanoseconds. A length stop or unfinished generation returns isError: true with the partial text retained. Completion does not establish answer correctness. These tools do not retry timed-out generation automatically. Both also accept format: "json", or a JSON Schema object to force an exact output shape. The schema constrains shape, not factual accuracy.

local_explore_repo returns no_evidence before any model call when the question names a tracked language the index cannot search (e.g. Ruby); the index covers TypeScript, JavaScript, PHP, Python, Go and Rust (symbols, calls, includes, inheritance; no PHP namespace/use resolution; Python imports resolve to files, but self.method() calls and import a.b bindings stay unresolved). Go indexes functions, receiver methods, named types and top-level const/var declarations. Go calls, references and import paths are source-backed but unresolved: package resolution, receiver dispatch and local binding identity are not inferred. Go scout context adds only the nearest declaration or anonymous function header. Rust indexes functions, lexical impl/trait methods, structs, enums, traits, type aliases, modules, constants and statics. Method names preserve the literal impl header (for example impl Sender for Invoice.send); this identifies source context, not a trait or receiver binding. Calls, references, use declarations and external module names stay unresolved. Crate paths, macros, cfg conditions and dispatch are not evaluated. Rust scout context adds the nearest declaration or closure header and, for direct members, the lexical impl/trait header.

The model has no tools or shell access in the scout route. The older local_explorer_task loop remains for historical comparisons.

The corresponding semantic, knowledge, verification, full-Explorer, and framework CLI commands enforce the same gates. The full pipeline defaults to deterministic basic retrieval; full hybrid mode additionally requires both ENABLE_SEMANTIC_SEARCH=1 and ENABLE_GIT_HISTORY=1.

Autonomous workers

Git-writing workers are a separate safety category and are never enabled by ENABLE_EXPERIMENTAL:

• LOCAL_WORKER_ENABLED=1 registers run_local_worker_task.

• CLOUD_CLAUDE_ENABLED=1 registers run_cloud_claude_task.

Both retain the shared Git-command allowlist and cloud validation hook. Verify their work with git status and git log; do not trust a worker's own report.

Frozen research

Historical benchmark results, model-routing experiments, fine-tuning plans, framework research, and autonomous-agent experiments are preserved under docs/ and scripts/. They are not being expanded and are not part of the normal runtime path. Start with the documentation index.

Setup

Requires Node 22.13+ and an Ollama server for model-backed tools.

npm install
ollama serve
npm start

Copy .env.example to .env only when configuration overrides are needed. Register npm start as a local stdio MCP server in your client.

Verification

npm run test:features
npm run test:quality
npm run test:local-explore
npx tsc --noEmit

The Quality Review integration test binds a temporary localhost port for a mocked Ollama endpoint.