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.
