agent-vision-mcp (hardened)

A hardened fork of @kitlau/agent-vision-mcp — an MCP server that gives non-vision LLMs the ability to analyze images via any OpenAI-compatible vision API (Claude Code, DeepSeek, etc.).

This build fixes intermittent empty / truncated image-analysis results and request hangs that affect long outputs (e.g. high-resolution 3D render screenshots) against self-hosted Qwen VLMs and similar backends.

What was broken upstream

The upstream package:

• defaulted output max_tokens to 1024 and never grew it, so long analyses hit finish_reason: length and were cut off mid-sentence — and intermittently returned empty content, surfacing as ❌ 视觉 API 返回的内容为空;

• only read message.content, ignoring message.reasoning_content used by Qwen3.x thinking-style models;

• had no retry on empty / 5xx / 429 / transient network errors;

• set no client timeout, so slow high-res inference could hang and get killed (MCP error -32001: user-cancel).

Related MCP server: Vision MCP Server

What this build changes

dist/vision-client.js:

• Grows max_tokens on truncation (finish_reason === "length") and retries, so a low ceiling can never silently produce a partial/empty answer (grow ceiling: 32768).

• Falls back to message.reasoning_content when content is empty (Qwen thinking mode).

• Retries on empty results, 5xx, 429, and network/timeout errors with exponential backoff (default 3 retries).

• Sets an explicit client timeout (default 300000 ms) to prevent hangs.

dist/config.js:

• Adds VISION_MAX_TOKENS (default 16384), VISION_TIMEOUT_MS (default 300000), VISION_MAX_RETRIES (default 3) env vars, exposed on the config object.

Install as an MCP server

Point your MCP client at this repo. Example claude_desktop_config.json / .mcp.json / global ~/.claude.json entry:

{
  "mcpServers": {
    "agent-vision": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/this/repo/dist/index.js"]
    }
  }
}

For a drop-in remote install, clone this repo and npm install, then run node dist/index.js. Or add it as a dependency with npm install github:aabbccddwasd/agent-vision-mcp.

Environment variables

License

MIT. Original author: kitlau86.