Skip to content
T1KTheOneKit

image-analysis-routing

Image Analysis Routing — human-mcp First

Section titled “Image Analysis Routing — human-mcp First”

Rule

Section titled “Rule”

For ANY image the user provides (pasted, attached, or a file path), route the analysis through the human-mcp MCP server’s vision tools — mcp__human-mcp__eyes_analyze (or eyes_compare / eyes_read_document for multi-image or document inputs) — instead of Claude’s built-in vision.

This is the kit default and is reinforced by the UserPromptSubmit hook image-routing-human-mcp.cjs, which injects a routing reminder whenever an image is attached.

How to apply

Section titled “How to apply”
  1. When an image is present, call mcp__human-mcp__eyes_analyze with the image’s file path (Claude Code’s pasted-image cache path, a URL, or a local path) as source.
  2. Use eyes_compare for before/after or A/B image pairs, and eyes_read_document / eyes_summarize_document for screenshots of text, PDFs, or documents.
  3. If human-mcp is registered but mcp__human-mcp__eyes_analyze is NOT loaded this session (it loads at session start), tell the user to restart Claude Code, then route the analysis through it.
  4. If human-mcp is NOT installed at all, just use Claude’s built-in native vision — that is the intended graceful fallback. The routing hook only fires when human-mcp is registered, so this rule never forces a tool the user doesn’t have.
  5. If human-mcp IS installed and loaded, but a call to mcp__human-mcp__eyes_analyze (or eyes_compare / eyes_read_document) errors out or times out — the configured vision backend is unreachable (dead API key, expired gateway, upstream outage). Fall back to Claude’s built-in native vision for the current image, and tell the user the human-mcp backend call failed rather than silently retrying it or surfacing a raw tool error. Do not keep retrying the same dead backend for subsequent images in the same session — fall back for each one and let the user know once, not per-image.

Scope

Section titled “Scope”

Applies to image analysis only — image generation is a separate path this rule does not govern. features.imageAnalysisRouting: false in t1k-config-core.json disables the routing hook entirely (native vision resumes).

Why: human-mcp’s dedicated vision pipeline is benchmarked correctness-first across multiple backends and keeps image analysis on the studio’s chosen gateway/models, rather than per-project wiring. Detail: docs/image-analysis-routing.md.