consult-smarter-model-mcp

An MCP (Model Context Protocol) server that gives an LLM agent a small set of high-leverage "consult a smarter model" and "look at the screen" tools.

The intended workflow is an LLM agent (Kilo / Claude Code / similar) that already has file/shell access, but no vision model and no easy way to escalate hard questions. This server adds:

• consult — escalate a hypothesis + context to a stronger model via OpenRouter, with configurable intelligence level and automatic fallback on content-filter refusals and reasoning-only responses.
• describe_image — describe a local image file using a vision model (downscaled to 512px height by default for cost, or full resolution when fine detail is needed).
• capture_window — grab a screenshot of a specific OS window (by title substring or PID) and save it as a PNG. Works on KDE Plasma Linux (X11 + Wayland) and Windows 10/11. Full-screen captures are explicitly not supported.

All tools return plain text, so they slot into any MCP client without extra glue.

Tools

consult(core_hypothesis, supplementing_material, intelligence_level="high") -> str

Ask a stronger model a direct question before committing to an action.

• core_hypothesis — what you plan to do or believe. Be direct.
• supplementing_material — tight context: constraints, relevant facts, what you have tried.
• intelligence_level — high (Opus-class) for core truths and critical decisions, medium (Sonnet-class) for regular decisions, low (Haiku-class) for quick checks.

Internally: builds a short system prompt, posts to OpenRouter, and on a content_filter refusal transparently retries on a more permissive fallback model. On a reasoning-only response (no main content), it sends a one-shot continuation nudge to elicit a real answer.

describe_image(image_path, question=None, image_fidelity="low") -> str

Describe a local image using a vision model.

• image_path — local filesystem path to the image.
• question — optional specific question. If omitted, returns a full description.
• image_fidelity — low (default, resizes to 512px tall — fast and cheap, good for general descriptions) or high (sends the original — use only when fine-grained detail matters: small text, subtle UI elements, etc.).

The image is base64-encoded and sent inline to the vision model.

capture_window(save_path, window_name=None, process_id=None, include_decoration=True, max_width=4096) -> str

Capture a specific window and save it as a PNG.

• save_path — required absolute path to write the PNG to.
• window_name — optional substring matched against the window title.
• process_id — optional OS PID owning the window.
• include_decoration — include the window frame/titlebar (default True).
• max_width — reject windows wider than this many pixels (default 4096).

You must provide window_name and/or process_id; full-screen and monitor-only captures are intentionally rejected.

Platform internals are kept fully separate:

• KDE Plasma Linux (X11 / Wayland) — uses xdotool to enumerate/identify windows, then import (X11) or spectacle (Wayland) to grab the window. No Python dependencies beyond the stdlib.
• Windows 10/11 — pure ctypes against user32 / dwmapi / gdi32. No pywin32. PNG is encoded with stdlib zlib + struct, so no third-party image libraries are needed.

Both backends share a zero-dependency BGRA→PNG encoder and the validation/normalisation logic.

Setup

Requirements

• Python 3.10+
• An OpenRouter API key
• Linux only for the capture_window tool: xdotool, and either ImageMagick (import for X11) or spectacle (for Wayland). Windows 10/11 has no extra system dependencies.
• Python packages (see requirements.txt): mcp[cli], httpx, Pillow.

Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure

Copy .env.example to .env and set your OpenRouter key:

cp .env.example .env
# edit .env and set OPENROUTER_API_KEY=...

The server reads OPENROUTER_API_KEY from the environment.

Run

The server uses FastMCP("AdditionalToolsMCP", stateless_http=True). Run it the way your MCP client expects (typically python additional_tools_mcp.py over stdio, or registered as an MCP server in your client config).

Models

Configured in additional_tools_mcp.py:

Intelligence level	Primary model	Fallback (on content-filter refusal)
high	anthropic/claude-fable-5	openai/gpt-5.6-sol
medium	anthropic/claude-opus-4.8	openai/gpt-5.6-sol
low	anthropic/claude-sonnet-5	openai/gpt-5.6-sol

Image description: google/gemini-3.1-flash-lite.

Tweak MODEL_MAP, FALLBACK_MODEL, and IMAGE_MODEL in additional_tools_mcp.py to point at different providers/models.

Design notes

• No full-screen captures. capture_window is for inspecting a specific window the agent has reason to look at. Rejecting full-screen keeps payloads sane and prevents accidental screen-dump exfiltration.
• Fallback on refusal. Some primary models refuse deep technical research content. The server transparently retries on a more permissive fallback model rather than failing the call.
• Continuation nudge. Reasoning-heavy models sometimes emit only reasoning with no content. The server detects this and sends a one-shot assistant/user continuation to elicit a real answer, accumulating token usage across both calls.
• Zero third-party image deps in the capture path. PNG encoding is done with stdlib zlib + struct, so the Windows backend needs nothing beyond the Python standard library.
• Plain-text returns. All tools return strings so they drop straight into any MCP client.

Files

• additional_tools_mcp.py — the FastMCP server and its three tools.
• window_capture.py — platform-separated window-capture library (Linux + Windows) with a zero-dependency PNG encoder.
• requirements.txt — mcp[cli], httpx, Pillow.
• .env.example — template for OPENROUTER_API_KEY.

License

Not specified.