Arnoldkevin / prismrelay-mcp

PrismRelay MCP

Vision First — v0.3.0

PrismRelay gives text-only Agents, including DeepSeek-based workflows, a way to inspect real image pixels through a local stdio MCP server. The Agent remains the primary reasoner; PrismRelay sends the requested images to an external vision provider and returns a visual answer.

Agnes AI is the current backend. PrismRelay is an independent community project and is not affiliated with, endorsed by, or sponsored by Agnes AI.

Release status

Capability	Status	Suitable for
Image understanding	Supported, primary workflow	Scene and object questions, screenshots, documents, charts, diagrams, visible text, image comparison
Image generation	Experimental	General drafts where provider variation is acceptable
Image editing and composition	Experimental	Exploratory edits with manual review
Strong Style Skill compliance	Not a claimed capability	Do not promise faithful art direction or native multimodal quality

PrismRelay does not change the text model into a native multimodal model. It gives the Agent a callable external “eye.” Visual accuracy, latency, and availability still depend on Agnes AI and on the Agent host correctly invoking MCP tools.

Tools

• prismrelay_understand_image — inspect, compare, answer questions, read visible text, and interpret screenshots, documents, charts, diagrams, products, or scenes.
• prismrelay_generate_image — experimental generation with optional references, final dimensions, candidates, and review.
• prismrelay_edit_image — experimental editing and composition with input roles, preservation hints, and review.

Legacy agnes_* tools remain for compatibility but are not recommended for new workflows.

Requirements

• Node.js 18 or newer
• Your own Agnes Platform account and API key
• An Agent host that supports local stdio MCP tools
• Outbound HTTPS access to https://apihub.agnes-ai.com/v1 or your configured Agnes route

PrismRelay is BYOK: every user supplies their own key and accesses Agnes directly. Do not share accounts, keys, credits, or offer PrismRelay as a resale/proxy service.

Install from GitHub

git clone https://github.com/Arnoldkevin/prismrelay-mcp.git
cd prismrelay-mcp
npm install
export AGNES_API_KEY="your_api_key_here"

Persist AGNES_API_KEY using your operating system or shell's secret/environment mechanism. Never paste it into a chat, tracked file, screenshot, or support log.

Codex

node dist/prismrelay-mcp.mjs setup codex --dry-run
node dist/prismrelay-mcp.mjs setup codex --force
node dist/prismrelay-mcp.mjs doctor

This installs the Skill at ~/.agents/skills/prismrelay-images and registers the MCP server as prismrelay.

Claude Code

node dist/prismrelay-mcp.mjs setup claude-code --dry-run
node dist/prismrelay-mcp.mjs setup claude-code --force
node dist/prismrelay-mcp.mjs doctor
claude mcp get prismrelay

This registers a user-scoped stdio server and installs the Skill at ~/.claude/skills/prismrelay-images. Start a new Claude Code session from a shell that exports AGNES_API_KEY, then use /mcp to confirm that the server is connected.

Other Agent hosts

Configure this process in the host's stdio MCP settings:

command: node
args: /absolute/path/to/prismrelay-mcp/dist/prismrelay-mcp.mjs serve
environment passthrough: AGNES_API_KEY, AGNES_BASE_URL, AGNES_OUTPUT_DIR

Also install skills/prismrelay-images in the host's supported Skill directory if it supports Agent Skills. See Host setup and automatic invocation.

DeepSeek Harness plugin

PrismRelay also ships as an installable DeepSeek Harness bundle. It uses Harness's official MCP Client to expose the same local PrismRelay tools; the visual runtime is not duplicated.

export AGNES_API_KEY="your_api_key_here"
npx @deepseek-ai/dsh plugin --profile web add github:Arnoldkevin/prismrelay-mcp
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

DeepSeek Harness is currently a Developer Preview, so compatibility may need to track upstream breaking changes. See DeepSeek Harness integration for configuration, removal, and current MCP image-output limitations.

Does it call itself automatically?

Sometimes, but installation is not a guarantee.

MCP makes the tools available. The host model decides whether to invoke them from the request, MCP tool descriptions, the companion Skill, permissions, and its tool-calling implementation. PrismRelay's Skill strongly instructs a text-only Agent to call prismrelay_understand_image whenever a visual task includes a readable image source.

For the most reliable first test, give an explicit local path:

请查看 /absolute/path/to/screenshot.png，告诉我页面当前状态和可见的报错。

A local MCP process cannot intercept an opaque image attachment held only inside the host's private conversation payload. If a pasted image is not exposed as a path, save it to disk and provide the path. DeepSeek used through a Claude Code-compatible proxy must also support Claude Code's tool-calling protocol; that behavior is controlled by the proxy/model, not PrismRelay.

Recommended vision tasks

• Ask what is visible in a photo and request evidence for the answer.
• Diagnose a UI screenshot or error dialog.
• Extract headings, totals, dates, or status labels from a clean document image.
• Explain the trend and legend in a chart.
• Compare two product images or two UI screenshots.
• Check whether a poster contains a specified element or visible wording.

Run the repeatable matrix in Vision evaluation before making reliability claims for a particular Agent host and model combination.

Privacy and data flow

Images are read by the local MCP process and sent to the configured Agnes API for inference. They are not processed entirely on-device. Generated or downloaded results are saved under AGNES_OUTPUT_DIR (default ./outputs). See Privacy before using personal, confidential, regulated, or third-party images.

Configuration

Variable	Required	Default	Purpose
AGNES_API_KEY	Yes	None	Agnes API authentication
AGNES_BASE_URL	No	https://apihub.agnes-ai.com/v1	Agnes API route
AGNES_OUTPUT_DIR	No	./outputs	Downloaded and finalized image directory
AGNES_TIMEOUT_MS	No	120000	Per-request timeout in milliseconds
AGNES_MAX_RETRIES	No	3	Maximum retryable API attempts
AGNES_MAX_IMAGE_BYTES	No	26214400	Input/output image safety limit
AGNES_EMBED_MAX_BYTES	No	4194304	Largest image embedded in an MCP response

Scope and limitations

• Local stdio MCP only; no remote hosting, shared service, OAuth, billing, or video generation.
• Understanding is delegated to a separate vision model. It may misread small text, blur, occlusion, dense tables, subtle differences, or ambiguous scenes.
• Generation/editing review can identify some failures, but cannot force a provider to follow strong style or layout instructions.
• The current release has automated contract and packaging tests. Users should separately run the live evaluation matrix with their own Agnes key and chosen Agent host.

Development

npm test
npm run smoke
npm run pack:check
npm audit --omit=dev

License and provider terms

PrismRelay's original code is released under the MIT License. MIT covers this repository's code only; it does not grant rights to Agnes models, APIs, output, documentation, branding, or trademarks.

The Agnes service terms restrict unauthorized resale, sublicensing, or provision of the service to third parties. PrismRelay therefore uses a direct BYOK design and must not be operated as a shared-key proxy or resale service. The public terms do not explicitly name community MCP clients, so this repository does not claim official authorization or endorsement. Read Third-party notices and obtain written clarification from Agnes for commercial redistribution models beyond direct BYOK use.

Official references

• Agnes Terms of Service
• Agnes Privacy Policy
• Agnes official model catalog
• Claude Code MCP documentation
• Claude Code Skills documentation
• Model Context Protocol TypeScript SDK
• DeepSeek Harness
• DeepSeek Harness MCP Client