modlens-mcp

MCP server that gives text-only models (e.g. DeepSeek) structured JSON vision evidence (summary / OCR / layout / semantics / uncertainty) by calling vision APIs directly — no CLI dependencies. The output contract follows the ModLens spec, so evidence files stay structured and machine-checkable.

Designed for Reasonix (.mcp.json with Claude Code-compatible mcpServers), works with any MCP client.

Features

• 4 tools — analyze_image, ocr_image, compare_images, find_image

• Direct API calls: OpenAI-compatible endpoints (openai / gemini-api) and Anthropic native (anthropic) — configured via one JSON file, no CLI installs, no shell spawning

• Structured evidence, never free text: the ModLens JSON contract (summary / ocr / layout / semantics / uncertainty) is requested via a strict system prompt and validated on parse

• Fits Reasonix's 32KB tool-result cap: every tool result is a slim projection (summary / uncertainty / evidence_path); the full evidence JSON is persisted to .reasonix/vision-evidence/<sha256>.json and read on demand via read_file

• Stateless & zero-pollution: each call is an independent HTTP request; image bytes never enter any model history

• Registry: analyze_image registers image metadata (.reasonix/vision-index.jsonl) so find_image can locate pasted images even after the conversation window lost the reference

• Workspace root resolution: on every call the server asks the MCP client for the current project root (roots/list, ≤1s, never cached across calls) and probes candidate roots in order — project root → configured workspaceRoot → global workspace ~/.reasonix → home dir → cwd — picking the first that exists. A single long-lived server resolves pasted attachments correctly in every project (Reasonix stores pasted files under the project's .reasonix/attachments/).

• Delivery-first friendly: all four tools declare readOnlyHint, so Reasonix hosts treat them as non-destructive instead of blocking them behind acceptance criteria. Side effects stay inside the server's own state (~/.reasonix/vision-evidence/, vision-index.jsonl); the only external effect is the paid vision-API call you configured.

Related MCP server: vision-relay-mcp

Install

npm install          # inside this project
npm run build        # tsc → dist/

Configure

Precedence: Reasonix MCP panel env wins — set VISION_API_KEY (plus VISION_PROVIDER / VISION_BASE_URL / VISION_MODEL) in the MCP server env (panel or .mcp.json) and it takes effect after restart. Without a key in env, the server reads ~/.reasonix/vision-config.json (copy from config.example.json; VISION_CONFIG_FILE overrides the path), then falls back to the remaining VISION_* env vars.

{
  "provider": "openai",
  "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
  "apiKey": "your-real-key",
  "model": "glm-4.6v",
  "workspaceRoot": "D:/你的项目目录"
}

• provider: openai (OpenAI-compatible endpoints: Zhipu GLM, Aliyun Qwen-VL, OpenAI…), gemini-api (its OpenAI-compatible endpoint), or anthropic (native Messages API; baseUrl defaults to https://api.anthropic.com)

• Missing / placeholder / non-ASCII keys are rejected with a clear Chinese error before any HTTP call — you can never hit a cryptic provider error

.mcp.json (project root) only needs the server itself:

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["<你的用户目录>/.reasonix/modlens-mcp/dist/index.js"]
    }
  }
}

No VISION_WORKSPACE_ROOT needed: relative paths resolve via candidate roots (global workspace ~/.reasonix first), so the same server works in any project.

Environment variables (all optional)

Tool contract (summary)

analyze_image(image, prompt?, provider?, model?) → { image, tool, provider, model, summary, uncertainty, analysis, evidence_path } (slim, <32KB); full evidence (ocr.full_text, layout, semantics) at evidence_path.

Every call makes two vision requests: ① OCR/evidence (ModLens JSON contract → evidence file), ② a free-form analysis answering your prompt verbatim (no JSON constraints; a Chinese default question is used when no prompt is given). The analysis lands in the analysis field of both the slim result and the evidence file (additive, backward compatible). If the analysis request fails, the OCR evidence still succeeds (degraded, no analysis).

ocr_image(image, format?) → { image, format, evidence_path, preview, full_text_chars }.

compare_images(images[2-4], prompt?) → per-image slim blocks with independent image + evidence_path.

find_image(filename?, sha256Prefix?, limit?) → registry matches (metadata only, never image bytes).

Test

npm test    # 74 tests: config + direct (mock HTTP) + tools + real MCP protocol e2e

Security

• No shell spawning; HTTP requests use argument-safe fetch with only the configured endpoint

• Errors are sanitized (keys / Bearer / Basic redacted) before reaching the model context; the config key is never echoed back

• Evidence files and the registry are written with 0600 / 0700 permissions

• The key lives either in ~/.reasonix/vision-config.json (0600, not in version control) or in the Reasonix MCP panel env (VISION_API_KEY, persisted plaintext in the Reasonix config.toml — /mcp shows it redacted; keep that config out of shared screens and backups). Either way: rotate the key if it ever appears in logs or chats