# ⚡ Paper CDP MCP (v4.0.0)

> **Autonomous AI Design Agent Suite for Paper Desktop**  
> *Direct Chrome DevTools Protocol (CDP) Bridge · 73 Tools · 5 Resources · 3 Prompts · Zero Quota Limits*

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform: macOS](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)](https://apple.com)
[![Tools: 73](https://img.shields.io/badge/Tools-73%20Active-brightgreen.svg)]()
[![Tests: Passing](https://img.shields.io/badge/Tests-100%25%20Passing-success.svg)]()

---

## 🌟 Overview

`paper-cdp-mcp` is a production-grade Model Context Protocol (MCP) server that connects AI coding assistants and autonomous design agents (Claude Code, Cursor, Antigravity, Codex, Windsurf) directly to **Paper Desktop** via the **Chrome DevTools Protocol (CDP)**.

Unlike the official Paper MCP which routes through a rate-limited local HTTP port, `paper-cdp-mcp` communicates directly with the Chromium engine over WebSocket port `9222`. This unlocks:
- **Unlimited Execution**: Bypasses weekly MCP rate limits in-memory without touching disk.
- **Autonomous Reliability**: Full transaction safety, dry-run previews, programmatic design assertions, and 1-click rollbacks.
- **Advanced Spatial Intelligence**: 2D canvas overlap detection, pixel alignment, and Euclidean distance math.
- **Developer & Designer Superpowers**: 1-click SwiftUI/React/Flutter code export, theme inverters, i18n localization, and 8pt design system linting.

> 📖 **Read the Full Comparison**: [Official Paper MCP vs. Paper CDP MCP (`OFFICIAL_VS_CDP_MCP.md`)](OFFICIAL_VS_CDP_MCP.md)

---

## 🚀 Quickstart

### 1. Launch Paper Desktop with Remote Debugging
Close any running instance of Paper, then start it with port `9222` enabled:

```bash
# macOS Terminal
/Applications/Paper.app/Contents/MacOS/Paper --remote-debugging-port=9222 &
```

*(Tip: You can add an alias to your `~/.zshrc`: `alias paper-dev="/Applications/Paper.app/Contents/MacOS/Paper --remote-debugging-port=9222 &"`)*

---

### 2. Clone & Install
```bash
git clone https://github.com/your-username/paper-cdp-mcp.git
cd paper-cdp-mcp
npm install
```

---

### 3. Configure Your AI Client

#### A. Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "paper-cdp": {
      "command": "node",
      "args": ["/absolute/path/to/paper-cdp-mcp/bin/cli.mjs"],
      "env": {
        "CDP_PORT": "9222"
      }
    }
  }
}
```

#### B. Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "paper-cdp": {
      "command": "node",
      "args": ["/absolute/path/to/paper-cdp-mcp/bin/cli.mjs"]
    }
  }
}
```

#### C. Claude Code / Terminal CLI
```bash
claude mcp add paper-cdp node /absolute/path/to/paper-cdp-mcp/bin/cli.mjs
```

---

## 🛠️ Complete 73-Tool Architecture Matrix

### 1. Core Primitives & Autonomous Reliability (15 Tools)
- `apply_document_transaction`: Atomic multi-step document transactions with `dryRun` preview and precondition checks.
- `undo_last_transaction`: Reverts the last atomic transaction.
- `query_nodes`: Structured node query engine with boolean `and`/`or`/`not` logic, regex filters, and pagination.
- `inspect_scene_context`: Semantic working context across selection, artboard, and viewport scopes.
- `query_spatial_relationships`: 2D geometry math (overlaps, containment, Euclidean distance, alignments, exact gaps).
- `apply_node_patch`: Declarative bulk patch engine (`setStyle`, `setText`, `rename`, `move`, `delete`, `duplicate`, `setLayout`).
- `assert_design_rules`: Programmatic assertions (alignments, uniform bounds, min touch target, contrast ratios).
- `diff_design_nodes`: Semantic design diff between revisions.
- `compare_visual_regression`: Visual pixel diff with percentage drift threshold.
- `calculate_design_quality_score`: Multi-dimensional score (token adherence, layout cleanliness, typography consistency).
- `extract_design_system_tokens`: Discovers implicit repeated colors, sizes, and spacings.
- `refactor_design_structure`: Reorganizes deep canvas hierarchies and removes redundant containers.
- `configure_layout_constraints`: Configures flex/grid layout constraints on containers.
- `bind_data_repeater`: Clones templates mapped to structured JSON datasets.
- `check_system_health`: Audits CDP latency, memory bypass state, and document health.

### 2. Viewport & Camera Directing (3 Tools)
- `pan_to_node`: Centers camera smoothly on any node or artboard.
- `zoom_to_fit`: Automatically frames selected elements or canvas bounds.
- `set_camera_zoom`: Sets absolute camera zoom level.

### 3. High-Speed Batch & Media Assets (4 Tools)
- `batch_write_artboards`: High-speed multi-artboard generator (<200ms).
- `batch_export_assets`: Multi-scale parallel asset exporter (PNG, SVG, PDF, WebP).
- `insert_icon`: Injects Lucide vector icons dynamically.
- `insert_curated_media`: Injects curated stock photos, abstract glassmorphic backgrounds, and gradients.

### 4. Design Engineering & Code Export (5 Tools)
- `export_code`: Exports selected nodes directly to **SwiftUI**, **React Tailwind**, **Flutter**, or **HTML/CSS**.
- `generate_theme_variant`: Inverts entire artboards between Dark and Light modes.
- `generate_responsive_variants`: Generates Mobile (390px), Tablet (820px), and Desktop (1440px) screen variants.
- `transform_lofi_to_hifi`: Converts wireframe sketches into production-ready UI.
- `generate_design_spec_doc`: Creates Markdown developer handoff specifications.

### 5. Content & Accessibility Intelligence (4 Tools)
- `populate_mock_data`: Fills UI prototypes with realistic contextual mock data.
- `localize_artboard`: Translates UI text into Spanish, Japanese, German, Arabic (RTL), etc.
- `generate_component_states`: Auto-generates Default, Hover, Pressed, Focused, and Disabled state matrices.
- `autofix_contrast_issues`: Detects and auto-fixes text contrast to pass WCAG AAA standards.

### 6. Flow Storyboards & Figma Interoperability (3 Tools)
- `export_figma_compatible_json`: Exports Paper nodes into Figma REST/Plugin compatible JSON.
- `generate_journey_storyboard`: Generates step-by-step user journey flowboards.
- `connect_artboards_flow`: Draws smart interactive connector arrows between screens.

### 7. Layout Matrix & Version Snapshots (5 Tools)
- `auto_layout_grid`: Arranges loose artboards into clean matrix rows and columns.
- `create_checkpoint`: Saves an in-memory Git-style design checkpoint.
- `list_checkpoints`: Lists all saved checkpoints.
- `rollback_checkpoint`: Reverts canvas to any checkpoint.
- `audit_design_tokens`: Lints all layers against design system tokens and 8pt spatial grid.

### 8. Native Paper Document Operations (34 Tools)
- `open_file`, `list_files`, `create_file`, `create_page`, `get_basic_info`, `get_selection`, `get_node_info`, `get_children`, `get_screenshot`, `get_jsx`, `get_tree_summary`, `get_computed_styles`, `get_fill_image`, `find_nodes`, `list_comment_threads`, `get_comment_thread`, `list_comment_thread_authors`, `set_comment_thread_status`, `get_font_family_info`, `get_guide`, `export`, `export_combined_pdf`, `write_html`, `create_artboard`, `delete_nodes`, `set_text_content`, `rename_nodes`, `update_styles`, `duplicate_nodes`, `move_nodes`, `finish_working_on_nodes`, `get_tokens`, `create_tokens`, `set_tokens`.

---

## 📦 Native MCP Resources (`paper://*`)

AI agents can read live document state instantly via standard MCP Resource URIs:
- `paper://capabilities`: Server metadata and active CDP features.
- `paper://document`: Active document hierarchy, pages, and artboard list.
- `paper://selection`: Currently selected nodes, bounds, and styling.
- `paper://design-system`: Defined design tokens (colors, radii, spacing, fonts).
- `paper://diagnostics`: Real-time CDP latency and memory hook status.

---

## 🧠 Autonomous Workflow Prompts

Pre-engineered interactive prompts for AI design agents:
- `inspect-before-edit`: Audits selection context and spatial neighbors before making changes.
- `safe-refactor`: Plans and executes atomic token refactors with dry-run previews.
- `design-review`: Evaluates contrast, alignment, typography, and token adherence.

---

## 🧪 Comprehensive Verification Suite

Run all test suites against live Paper Desktop:

```bash
# 1. Baseline Native Tools (34 Tools)
npm test

# 2. Phase 1 Extended Tools (12 Tools)
node test-extended-tools.mjs

# 3. Phase 2 Designer Extensions (12 Tools)
node test-phase2-tools.mjs

# 4. Phase 3 Autonomous Reliability Engine (15 Primitives + Resources + Prompts)
node test-autonomous-suite.mjs
```

---

## 📄 License

MIT © Mahesh Vulasala & Contributors