jl-image-vison

MCP server for image understanding — structured description of UI designs, HTML pages, and visual layouts, powered by Agnes 2.0 Flash.

Tool: describe_image

Analyse an image and return a richly structured breakdown — layout hierarchy, UI components, readable text, interactions, design notes, and accessibility observations. Optimised for UI mockups, Figma exports, HTML/CSS screenshots, dashboards, and app interfaces.

Input

Parameter	Type	Required	Description
image	string	yes	The image to analyse. Accepts three formats: (1) a public URL — https://example.com/screenshot.png; (2) a local file path — ~/Desktop/mockup.png or C:\Users\you\shot.png; (3) a base64 data URL — data:image/png;base64,....
detail_level	enum: standard | detailed | comprehensive	no (default detailed)	How thorough the description should be.
focus	string	no	Steering hint, e.g. "layout only", "extract all text", "focus on accessibility", "identify design system".

Output

• content[0].text — the full structured description (markdown).
• structuredContent — machine-readable fields: summary, description, model, tokens.

Setup

npm install
npm run build

Configuration

Environment variables (all optional except AGNES_API_KEY at runtime):

Variable	Default	Description
AGNES_API_KEY	—	Your Agnes AI API key (required to call the tool).
AGNES_BASE_URL	https://apihub.agnes-ai.com/v1	Override the API base URL.
AGNES_MODEL	agnes-2.0-flash	Override the model name.

Get an API key from the Agnes AI developer console.

Connect to a host

Claude Code / Claude Desktop (stdio)

Add to your MCP config:

{
  "mcpServers": {
    "image-vison": {
      "command": "node",
      "args": ["D:/my/oss/jl_image-vison-mcp/dist/index.js"],
      "env": {
        "AGNES_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Any MCP client via npx

AGNES_API_KEY=sk-your-key npx tsx src/index.ts

Develop

npm run dev        # run with tsx (no build step)
npm run typecheck  # type-check only
npm run build      # compile to dist/
npm run inspect    # launch MCP Inspector for interactive testing

Limitations (v0.2)

• Single image — one image per call. Multi-image comparison is not yet supported.
• Agnes 2.0 Flash only — first release supports only this model.
• Local file size limit — 10 MB per image (Agnes payload limit).
• Claude Code pasted images — when you paste an image into Claude Code, it may pass a file path or a data URL; both are now supported. If you get a "Cannot read file" error, the path Claude Code passed doesn't exist on the server's filesystem — upload to a public URL instead.