j-can-see

English | 中文文档

An MCP server that sends images (local file / URL / clipboard / latest screenshot) to a vision model and returns a text description.

Who is it for: AI coding clients like Claude Code / Codex whose primary model has no multimodal input (can't see images). Use the see_image tool to outsource vision.

The problem it solves

When the primary model doesn't support image input, Read-ing an image or pasting a screenshot into the conversation causes a direct 400 at the API layer and the whole turn crashes — the model never sees a "failure" event and can't recover on its own.

j-can-see turns vision into an ordinary text tool call: the model passes a path/URL and gets back a text description — usable by any text-only model.

Related MCP server: MCP Vision Server

Quick start

One-liner (recommended)

claude mcp add j-can-see -s user \
    -e J_SEE_TOKEN='your-key' \
    -e J_SEE_BASE_URL='https://your-proxy.example' \
    -e J_SEE_MODEL='grok-4.5' \
    -- npx -y j-can-see

-s user writes the config to ~/.claude.json (outside any git repo), so the key never leaks.

Manual configuration

Add this to the mcpServers section of ~/.claude.json:

"j-can-see": {
  "command": "npx",
  "args": ["-y", "j-can-see"],
  "env": {
    "J_SEE_TOKEN": "your vision model key",
    "J_SEE_BASE_URL": "https://your-proxy.example",
    "J_SEE_MODEL": "grok-4.5"
  }
}

Environment variables

Missing required variables → crash on startup with a clear reason (fail fast).

J_SEE_MODEL has no default: use the vision model your endpoint actually supports. In testing, grok-4.5 used fewer tokens than other candidates at equal description quality.

API specs (J_SEE_API_SPEC)

Three upstream specs, default responses:

Direct Claude (anthropic): call Anthropic directly without any OpenAI-compatible proxy:

claude mcp add j-can-see -s user \
    -e J_SEE_API_SPEC='anthropic' \
    -e J_SEE_TOKEN='sk-ant-...' \
    -e J_SEE_BASE_URL='https://api.anthropic.com' \
    -e J_SEE_MODEL='claude-sonnet-4-5-20250929' \
    -- npx -y j-can-see

• J_SEE_REASONING is ignored under responses / anthropic (only openai honors it).

• In practice, none of the three specs can fully turn off reasoning — the translation layer doesn't pass through effort, so a single vision call still burns a few hundred reasoning tokens (responses ≈ 500, openai ≈ 900, anthropic keeps thinking off by default). Quality is unaffected; this is acceptable.

• Default responses: if your proxy doesn't support /v1/responses (returns 404), the error message will suggest setting J_SEE_API_SPEC=openai (no silent fallback — errors are reported as-is, and you decide explicitly to switch specs).

Tool: see_image

see_image({
  source: string,   // see table below
  prompt?: string   // omitted → "describe the image in detail, including text/UI/colors/layout"
}) → string         // text description returned by the model

CLI

npx j-can-see --hook   # print the PreToolUse hook script; save it locally and wire it up in Claude Code settings

source values

Claude Code setup (MCP + Hook)

1. MCP server

See "Quick start" above; write to ~/.claude.json or a project-level .mcp.json.

2. PreToolUse Hook (recommended)

Without it, the model's instinct when it sees an image path is to Read it — which triggers that 400. The hook intercepts the request first and redirects to see_image:

Step 1: export the hook script

npx j-can-see --hook > ~/.claude/hooks/block-image-read.mjs
chmod +x ~/.claude/hooks/block-image-read.mjs

Step 2: configure Claude Code

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/block-image-read.mjs"
          }
        ]
      }
    ]
  }
}

The hook is deliberately conservative: it only intercepts Read calls on image file extensions. Multimodal models don't Read images (they consume image blocks directly), so the hook never misfires for them.

Codex setup

Codex has no PreToolUse interception, so rely on an AGENTS.md convention:

## Image recognition
This session's primary model has no multimodal capability; do not use view_image or read images directly.
To describe an image, call the MCP tool see_image({ source }).

Less reliable than the hook, but it's all Codex supports for now.

Why these defaults (measured, not guessed)

Sharing with others

The command for a friend is identical to yours — just replace J_SEE_TOKEN with a key issued for them.

claude mcp add j-can-see -s user \
    -e J_SEE_TOKEN='friend-specific-key' \
    -e J_SEE_BASE_URL='https://your-proxy.example' \
    -e J_SEE_MODEL='grok-4.5' \
    -- npx -y j-can-see

Key safety: one per person, never shared

CLIProxyAPI's api-keys is a flat array — all keys have equal permissions (no per-key model whitelist or quota). Never hand your main key to a friend.

Create a separate key per person on the server:

# /root/CLIProxyAPI/config.yaml
api-keys:
  - sk-your-main-key      # ← never give this to anyone
  - sk-friend-A           # ← friend A. If a key misbehaves, delete just that one
  - sk-friend-B           # ← friend B

Do you need a gateway (quota / model whitelist)?

CLIProxyAPI currently has no per-key quota or model restrictions — a friend with a key can call every model on your backend (including expensive ones like video generation). If you trust your friends, no extra gateway is needed; if you need quotas/whitelists, add a thin gateway in front.

If the server side is CLIProxyAPI

No server-side changes needed — just point J_SEE_BASE_URL at it, since it already has HTTPS (Cloudflare Tunnel) + auth (api-keys) + OpenAI image compatibility.

Limitations

• No Linux clipboard: source: "clipboard" errors out clearly on Linux; use a file path instead (a declared boundary, not a silent fallback)

• Transparent PNGs are converted to JPEG (alpha becomes black); irrelevant for text screenshots

• No retries, no fallback: vision failures are reported as-is; the caller decides

Development

npm install
npm test        # vitest
npm run build   # tsc → dist/

Publishing

# 1. Bump version in package.json (e.g. 0.1.0 → 0.1.1)
# 2. Build
npm run build
# 3. Publish to npm (always use the official registry, even if a mirror is configured globally)
npm publish --registry=https://registry.npmjs.org/