<div align="center">

🔌 Planist-MCP

Model Context Protocol (MCP) Server for Planist APOS

Connect Claude, Cursor, and External AI Agents directly to your Planist Workspace.

<p align="center"> <em>An out-of-process, privacy-focused, Model Context Protocol server enabling AI models to inspect, read, and propose edits across Planist's 6 hyper-fused page types and reactive variable substrate.</em> </p>

---

</div>

🌟 Overview

Planist-MCP is the official Model Context Protocol server for Planist — the Agentic Project Operating System (APOS).

By isolating AI interactions into an out-of-process MCP server, Planist ensures maximum data security, zero in-process script execution vulnerabilities, and seamless compatibility with Claude Desktop, Cursor, and custom AI agent frameworks.

┌────────────────────────────────────────────────────────┐
│ External AI Ecosystem (Out-of-Process)                 │
│                                                        │
│  [ Claude / LLM ] ──> [ Planist-MCP Server (TS) ]     │
└───────────────────────────┬────────────────────────────┘
                            │ (JSON-RPC stdio / HTTP)
                            ▼
┌────────────────────────────────────────────────────────┐
│ Planist Desktop Application (APOS)                     │
│                                                        │
│  1. Host-Local API Listener (127.0.0.1:8080)           │
│  2. AI Grant Validation & Proposal Review Panel        │
│  3. ProjectAuthority (Typed Transaction Write-Back)    │
└────────────────────────────────────────────────────────┘

---

✨ Features & Capabilities

• 📄 Doc (docs): Inspect Markdown block structures, append new sections, and propose document diffs (LivePageProposal).
• 📊 Sheet (sheet): Read/write specific cell ranges (A1:D20), evaluate formulas, and trigger data-driven chart projections.
• 🖼️ Slide (slide): Generate structural Markdown slides with rendering hints and speaker notes (Speaker Notes).
• 🎨 Edgeless (edgeless): Query spatial node cards, supply approximate node placements (letting Planist's internal engine layout the canvas), and draw vector ink strokes.
• 📐 Design (design): Query exact UI element trees, create vector frames with exact geometry (x, y, w, h), and export SVG previews.
• 📈 Dashboard (dashboard): Select components, bind metric data variables, and set up dynamic KPI dashboard grids.
• ⚡ Reactive Variable Substrate: List, inspect, and update project-scoped reactive variables (planist_update_variable), driving real-time updates across bound Sheets, Dashboards, and Docs!

---

🛠️ MCP Tools Specification

1. Workspace & Page Lifecycle Tools

Tool Name	Parameters	Description
planist_list_pages	kindFilter?	List accessible pages in the workspace (filtered by docs, sheet, slide, edgeless, design, dashboard).
planist_read_page	pageId	Read the AST, Markdown, or structural block representation of a specific page by its Stable ID.
planist_propose_page_edit	pageId, summary, markdownContent	Submit a structured page edit proposal (LivePageProposal) for human review in Planist.

2. Reactive Project Variable Tools

Tool Name	Parameters	Description
planist_list_variables	None	List all reactive typed variables in the Project Variable Substrate.
planist_get_variable	variableKey	Fetch current value, type contract, and UI binding references for a variable.
planist_update_variable	variableKey, value, summary?	Update a project variable value, driving automatic reactive UI updates across bound Sheet cells, Dashboard KPIs, and Docs (Execute ➔ Variable ➔ Plan loop).

---

📦 Installation & Build

# Clone the repository
git clone https://github.com/MiuDog/planist-mcp.git
cd planist-mcp

# Install dependencies
npm install

# Build TypeScript code to dist/
npm run build

---

⚙️ Configuration & Setup

Integrating with Claude Desktop

Add the following to your claude_desktop_config.json (located at %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "planist-mcp": {
      "command": "node",
      "args": ["C:/Projects/planist-mcp/dist/index.js"],
      "env": {
        "PLANIST_API_HOST": "http://127.0.0.1:8080",
        "PLANIST_GRANT_TOKEN": "<YOUR_LOCAL_GRANT_TOKEN>"
      }
    }
  }
}

---

🔒 Security & Human-in-the-Loop Governance

• Out-of-Process Isolation: The MCP server runs outside Planist's main Flutter execution thread.
• Local Host Listener: API connections are strictly bound to 127.0.0.1 (ADR-0029).
• Human Approval: Edit proposals sent via planist_propose_page_edit must be approved by human users in the Planist Review Panel unless authorized by an active AI Capability Grant (ADR-0034).

---

<div align="center">

Planist-MCP — Empowering Intelligent Collaboration for Planist.
Planist Core Repository • MCP Protocol Docs

</div>