feat: add MCP server for AI agent integration

- Add heroshot-mcp binary with tools: sync, add, list, snippet, remove
- Auto-derive JSON schemas from Zod using z.toJSONSchema()
- Add AI agents documentation page with platform configs
- Add robot icon and feature card to landing page

Author: Ondrej Machala

docs/.vitepress/config.ts

@@ -163,7 +163,10 @@ export default defineConfig({
         },
         {
           text: 'Guides',
-          items: [{ text: 'Automated Updates', link: '/docs/guide/automated-updates' }],
+          items: [
+            { text: 'Automated Updates', link: '/docs/guide/automated-updates' },
+            { text: 'AI Agents', link: '/docs/ai-agents' },
+          ],
         },
         {
           text: 'Integrations',

docs/docs/ai-agents.md

@@ -0,0 +1,148 @@
+---
+description: Use Heroshot with AI coding assistants like Claude Code, Cursor, and VS Code Copilot through MCP (Model Context Protocol).
+---
+
+# AI Agents
+
+Heroshot includes an MCP (Model Context Protocol) server that lets AI coding assistants manage your screenshots directly. Ask your AI to "add a screenshot of the pricing page" and it handles the config, capture, and code snippet generation.
+
+## What It Does
+
+The MCP server exposes these tools to AI agents:
+
+| Tool               | Description                               |
+| ------------------ | ----------------------------------------- |
+| `heroshot_sync`    | Capture all screenshots defined in config |
+| `heroshot_add`     | Add a new screenshot definition           |
+| `heroshot_list`    | List all configured screenshots           |
+| `heroshot_snippet` | Generate HTML/Markdown code snippets      |
+| `heroshot_remove`  | Remove a screenshot by ID                 |
+
+## Claude Code
+
+Add to your `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "heroshot": {
+      "command": "npx",
+      "args": ["-y", "heroshot-mcp"]
+    }
+  }
+}
+```
+
+Or with a local installation:
+
+```json
+{
+  "mcpServers": {
+    "heroshot": {
+      "command": "node",
+      "args": ["/path/to/node_modules/heroshot/dist/mcp/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Code after editing.
+
+## Cursor
+
+Add to your Cursor MCP settings (Settings > MCP Servers > Add Server):
+
+```json
+{
+  "heroshot": {
+    "command": "npx",
+    "args": ["-y", "heroshot-mcp"]
+  }
+}
+```
+
+Or add directly to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "heroshot": {
+      "command": "npx",
+      "args": ["-y", "heroshot-mcp"]
+    }
+  }
+}
+```
+
+## VS Code with Copilot
+
+For VS Code with GitHub Copilot, add to your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "heroshot": {
+      "command": "npx",
+      "args": ["-y", "heroshot-mcp"]
+    }
+  }
+}
+```
+
+## Windsurf
+
+Add to your Windsurf MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "heroshot": {
+      "command": "npx",
+      "args": ["-y", "heroshot-mcp"]
+    }
+  }
+}
+```
+
+## Example Prompts
+
+Once configured, try these prompts with your AI assistant:
+
+- "List all heroshot screenshots in this project"
+- "Add a screenshot of the homepage hero section"
+- "Generate HTML snippets for all screenshots"
+- "Sync all heroshot screenshots"
+- "Remove the old pricing screenshot"
+
+The AI handles the MCP tool calls automatically.
+
+## How It Works
+
+The MCP server runs as a subprocess spawned by your AI assistant. It communicates over stdio using JSON-RPC. Each tool call maps to Heroshot's core functions:
+
+- `heroshot_sync` calls the same capture logic as `npx heroshot`
+- `heroshot_add` writes to `.heroshot/config.json`
+- `heroshot_list` reads the config and returns screenshot metadata
+- `heroshot_snippet` generates framework-specific code
+- `heroshot_remove` updates the config to remove an entry
+
+No additional authentication needed - the server uses your existing Heroshot config and session.
+
+## Input Schemas
+
+All tool inputs are validated with Zod schemas. The MCP server auto-derives JSON Schema at runtime using `z.toJSONSchema()`, so schema definitions stay in sync with Heroshot's core types.
+
+Example input for `heroshot_add`:
+
+```json
+{
+  "screenshot": {
+    "name": "Dashboard Header",
+    "url": "https://example.com/dashboard",
+    "selector": "header.main",
+    "viewports": ["desktop", "mobile"]
+  }
+}
+```
+
+See [Configuration Reference](/docs/config) for all screenshot options.

docs/index.md

@@ -59,6 +59,12 @@ features:
     details: Encrypted sessions let you log in once and capture protected pages headlessly.
     link: /docs/getting-started#sites-that-need-login
     linkText: Session handling
+  - icon:
+      src: /icons/robot.svg
+    title: AI Agent Ready
+    details: MCP server lets Claude Code, Cursor, and Copilot manage screenshots directly. Just ask.
+    link: /docs/ai-agents
+    linkText: Configure MCP
   - icon:
       src: /icons/sliders.svg
     title: Visual Editor

docs/public/icons/robot.svg

@@ -6,13 +6,18 @@
   "author": "Ondrej Machala",
   "license": "MIT",
   "bin": {
-    "heroshot": "dist/cli.js"
+    "heroshot": "dist/cli/cli.js",
+    "heroshot-mcp": "dist/mcp/index.js"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    },
     "./vue": {
       "types": "./dist/integrations/vue/index.d.ts",
       "import": "./dist/integrations/vue/index.js"
@@ -151,6 +156,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
     "commander": "^12.1.0",
     "p-limit": "^7.2.0",
     "playwright": "^1.49.0",