MCP Tools

Overview

The nexus-ollama MCP server exposes six tools via the Model Context Protocol. When configured in your AI CLI, these tools are called automatically — the AI decides when to use them based on the task type. You don’t invoke them manually.

All tools route to local Ollama models. If Ollama is unreachable, they return CIRCUIT_BREAKER and the AI falls back to cloud inference.

---

Available tools

ollama_health

Check whether the local compute plane is reachable and which models are available.

Band:    —
Model:   —
Speed:   instant

Called before any delegation to confirm the plane is up. Returns a list of available models from the Ollama API.

---

ollama_commit_msg

Generate a conventional commit message from a git diff.

Band:    supervisor
Model:   qwen2.5-coder:1.5b (default)
Speed:   ~4.5s
Output:  Clean conventional commit (feat/fix/chore: description)

When it’s called: Automatically when an AI CLI is about to generate a commit message from staged changes.

---

ollama_boilerplate

Generate component, route, or model scaffolding from a spec.

Band:    supervisor
Model:   qwen2.5-coder:1.5b (default)
Speed:   ~7s
Output:  Reasonable scaffold (Express+Zod, React component, etc.)

When it’s called: When the AI needs to create a new file with standard structure — not novel logic.

---

ollama_test_scaffold

Generate a test file structure (describe/it blocks) without implementations.

Band:    supervisor
Model:   qwen2.5-coder:1.5b (default)
Speed:   ~3s
Output:  Correct describe/it block structure for the target file

When it’s called: When the AI sets up a test file before implementing the tests themselves.

---

ollama_lint_fix

Fix lint errors in a file given the error list and source.

Band:    logic
Model:   llama3.2:3b (default)
Speed:   ~6.5s
Output:  Fixed file with most errors resolved

Note: The 3B model fixes most lint errors well. Complex multi-fix scenarios occasionally garble edge cases — upgrading to 7B+ eliminates this.

---

ollama_logic_refactor

Refactor a code block for clarity and maintainability.

Band:    logic
Model:   llama3.2:3b (default)
Speed:   ~3s
Output:  Excellent — nested loops → filter+map, clear variable names, etc.

When it’s called: When the AI identifies code that would benefit from restructuring without changing behavior.

---

Configuration

Adding to Claude Code

Create or update ~/.claude.json:

{
  "mcpServers": {
    "nexus-ollama": {
      "command": "node",
      "args": ["~/.config/nexus/tools/mcp/server.mjs"]
    }
  }
}

For a specific project, add to .claude/mcp.json in the project root.

Adding to Gemini CLI

{
  "mcpServers": {
    "nexus-ollama": {
      "command": "node",
      "args": ["~/.config/nexus/tools/mcp/server.mjs"]
    }
  }
}

See mcp-configs/ in the NEXUS repo for per-CLI templates.

Overriding models per-tool

# Per-task model override (in .env)
NEXUS_MODEL_COMMIT_MSG="qwen2.5-coder:3b"
NEXUS_MODEL_LINT_FIX="qwen2.5:7b"
NEXUS_MODEL_LOGIC_REFACTOR="qwen2.5:7b"
NEXUS_MODEL_BOILERPLATE="qwen2.5-coder:1.5b"
NEXUS_MODEL_TEST_SCAFFOLD="qwen2.5-coder:1.5b"

---

Fallback: shell script

If the MCP server is not configured, the same delegation is available via shell:

bash ~/.config/nexus/tools/automation/ollama-delegate.sh <task-type> <context-file>

---

How CIRCUIT_BREAKER works

If Ollama is unreachable or a model isn’t pulled, the MCP tool returns:

CIRCUIT_BREAKER: ollama unreachable at http://localhost:11434

The AI CLI treats this as a signal to handle the task directly without retrying the local route. This prevents silent failures where a broken local model produces garbage output.

---

Test results (RTX 3050, default config)

Tested 2026-04-13 via JSON-RPC stdio.

Tool	Model	Time	Quality
ollama_health	—	instant	✅ Lists all models
ollama_commit_msg	qwen2.5-coder:1.5b	~4.5s	✅ Clean conventional commit
ollama_boilerplate	qwen2.5-coder:1.5b	~7s	✅ Reasonable Express+Zod scaffold
ollama_test_scaffold	qwen2.5-coder:1.5b	~3s	✅ Correct describe/it blocks
ollama_lint_fix	llama3.2:3b	~6.5s	⚠️ Good; edge case garble on complex multi-fix
ollama_logic_refactor	llama3.2:3b	~3s	✅ Excellent — nested loops → filter+map