Ultra-Eye

The main model asks a question. This MCP server reads the files, command output, page, or image with quota-plan flash models (OpenCode GO, GLM Coding Plan) and returns a short answer plus verified pointers or quotes. The raw dump never enters the main model's context. Never calls an Anthropic API.

The thing being protected is the main model's quota. A multi-file question or a long test log should be delegated, not ingested. Judge a call from its receipt: read is what the eye processed, returned is what the caller got.

[Ultra-Eye · read 11,497 tokens → returned 181 · flash 10,520 in / 181 out · glm-5.3-flash · 7.9 s]

model=none calls show flash 0 in / 0 out · no model. eye_task appends · N steps. The word saved does not appear.

Tools

Tiny scopes skip the model and return raw (scan under ~2k tokens, run under ~1.5k).

Related MCP server: local-llm-mcp

Tell your agent

Paste into a project CLAUDE.md or AGENTS.md (same text as AGENT-GUIDANCE.md):

• When a question spans several files, or a command will print more than a screen, delegate to eye_task in one call and answer from its result.

• When a page or an image needs reading, use eye_fetch or eye_look.

• For a lookup one grep would answer, do it yourself.

• Expect one to three minutes for a delegation; do not poll or retry within that window.

• After any Ultra-Eye call, repeat its receipt line (the last line, starting [Ultra-Eye ·) at the end of your reply.

Usage over a week: python -m ultraeye.report

Install

Python 3.11+, Windows-native stdio, no WSL. Version 1.0.0.

git clone https://github.com/Zhihong0321/Ultra-Eye.git
cd Ultra-Eye
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
copy ultraeye.example.json ultraeye.json

Set vault_path in ultraeye.json to your credential store. Credentials are read by name on every call. No telemetry.

Start command (from the clone):

.venv\Scripts\python.exe ultraeye\server.py

Grok

grok mcp add ultra-eye -- "<clone>\.venv\Scripts\python.exe" "<clone>\ultraeye\server.py"
grok mcp enable ultra-eye

Then /mcps → enable, or start a new session. Five tools should appear.

Claude Code (global)

claude mcp add ultra-eye -- "<clone>\.venv\Scripts\python.exe" "<clone>\ultraeye\server.py"

Codex

~/.codex/config.toml:

[mcp_servers.ultra-eye]
command = "C:\\path\\to\\Ultra-Eye\\.venv\\Scripts\\python.exe"
args = ["C:\\path\\to\\Ultra-Eye\\ultraeye\\server.py"]

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "ultra-eye": {
      "command": "C:/path/to/Ultra-Eye/.venv/Scripts/python.exe",
      "args": ["C:/path/to/Ultra-Eye/ultraeye/server.py"]
    }
  }
}

OpenCode

opencode.json:

{
  "mcp": {
    "ultra-eye": {
      "type": "local",
      "command": ["C:/path/to/Ultra-Eye/.venv/Scripts/python.exe", "C:/path/to/Ultra-Eye/ultraeye/server.py"],
      "enabled": true
    }
  }
}

This machine

Already cloned at D:\Tools\Ultra-Eye:

D:\Tools\Ultra-Eye\.venv\Scripts\python.exe D:\Tools\Ultra-Eye\ultraeye\server.py

Providers

Text (providers in ultraeye.json): OpenCode GO glm-5.3-flash then qwen3.8-flash, then GLM Coding Plan glm-5.3-flash. Reasoning: default | low | high (shipped low). default is the OpenCode endpoint default, not “off”.

Vision (vision_providers): OpenCode GO deepseek-v4-flash-vision-exp. Text calls do not use this list.

Response shapes

Every response ends with the receipt.

• eye_scan — ANSWER / POINTERS / CONFIDENCE / receipt

• eye_run — EXIT / FAILURES / SUMMARY / RAW / receipt

• eye_task — RESULT / EVIDENCE / STEPS / CONFIDENCE / receipt

• eye_fetch — ANSWER / QUOTES / SOURCE / CONFIDENCE / receipt

• eye_look — ANSWER / TEXT_FOUND / CONFIDENCE / receipt

Call log

ultraeye.log — one JSON line per call. Per-model incidents: ultraeye.incidents.jsonl.

python -m ultraeye.patches
python selftest.py

License

MIT. See LICENSE.