prismrelay-mcp

Readme

# 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](https://platform.agnes-ai.com/) 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

```bash
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

```bash
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

```bash
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:

```text
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](docs/HOST_SETUP.md).

### 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.

```bash
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](docs/DEEPSEEK_HARNESS.md) 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:

```text
请查看 /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](docs/VISION_EVAL.md) 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](PRIVACY.md) 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

```bash
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](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](THIRD_PARTY_NOTICES.md) and obtain written clarification from Agnes for commercial redistribution models beyond direct BYOK use.

## Official references

- [Agnes Terms of Service](https://app.agnes-ai.com/terms)
- [Agnes Privacy Policy](https://app.agnes-ai.com/privacy)
- [Agnes official model catalog](https://github.com/AgnesAI-Labs/AgnesAI-Models)
- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
- [Claude Code Skills documentation](https://code.claude.com/docs/en/skills)
- [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
- [DeepSeek Harness MCP Client](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client)