# visual-mcp

**Your agent's long reply, one point at a time.**

When a coding agent hands you 30 decisions in one wall of text, it sends them as a slide deck instead. You go through it in the browser, mark each point **OK** or leave a comment, and submit. The agent picks up your answers on its own.

![Slide view](docs/screenshots/slide.png)

## How it works

1. The agent calls `create_slide_deck` and gives you a link.
2. You open it: one point per slide, grouped into chapters.
3. Per slide: **OK**, a comment, both, or just **Next**.
4. You submit. A background `deck wait` wakes the agent with your answers.

If the chat session ended in between, tell the agent "I submitted my answers" and it fetches them.

| Chapters | Page view | Phone, dark |
| --- | --- | --- |
| ![Chapter list](docs/screenshots/chapters.png) | ![Page view](docs/screenshots/page-view.png) | ![Phone, dark mode](docs/screenshots/phone-dark.png) |

## Install

Node.js 20+, Linux or macOS.

```sh
git clone https://github.com/akuratnik/respond-as-slides.git visual-mcp && cd visual-mcp
npm ci && npm run build

claude mcp add deck -- node "$PWD/dist/cli.js" mcp
mkdir -p ~/.claude/skills/visual-deck && cp skill/SKILL.md ~/.claude/skills/visual-deck/
```

The skill is optional; the MCP server supplies the full instructions and tool descriptions.

Then ask your agent to "give me that as a deck". The service starts by itself on `localhost:7333`.

## Keys

`O` OK · `C` comment · `J` / `→` next · `K` / `←` back · `V` slides ↔ page · `Esc` leave the comment box

## Remote machine

Working over SSH? Forward port 7333 (VS Code: Ports panel → Forward a Port), then open the link on your computer.

To serve it behind a login instead, run server mode (`DECK_AUTH=proxy`) behind an auth proxy. Examples: [systemd unit](deploy/systemd/visual-mcp.service), [Caddy + oauth2-proxy](deploy/caddy/Caddyfile.example).

## Editing the agent's instructions

Everything the agent reads is plain Markdown in [prompts/](prompts/README.md):

| File | Controls |
| --- | --- |
| `instructions.md` | How to use decks (sent to the agent when it connects) |
| `tools/*.md` | Each tool's description |
| `fields.md` | Field hints: title, intro, headline, body… |
| `present_result.md` | The note returned with a new deck |
| `feedback_next.md` | The note returned with your answers |

Edits apply to the next agent session. To keep your own copies outside the repo, set `DECK_PROMPTS_DIR`; files there override the bundled ones.

## More

Configuration, API, security model and limits: [SPEC.md](SPEC.md).

- Built for Claude Code (auto wake-up needs background commands). Other MCP clients work with "I submitted my answers".
- Local mode assumes a single-user machine.
- No Mermaid, images or attachments yet.

## License

MIT