excalidrop 0.1.1

package/frontend/src/main.tsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.tsx'
+import '@excalidraw/excalidraw/index.css'
+
+const rootElement = document.getElementById('root');
+if (!rootElement) {
+  throw new Error('Root element not found');
+}
+
+ReactDOM.createRoot(rootElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

package/frontend/src/utils/ghSync.ts

@@ -0,0 +1,171 @@
+/**
+ * Static-viewer GitHub sync. Zero config on *.github.io:
+ * owner/repo are derived from the URL, token comes from
+ * localStorage (pasted PAT or agent handoff via #token=...).
+ * Device-flow login needs VITE_GITHUB_CLIENT_ID (one-time OAuth App setup).
+ */
+
+export interface RepoRef { owner: string; repo: string; branch: string }
+
+export function detectRepo(): RepoRef | null {
+  const explicit = (import.meta as any).env?.VITE_REPO_SLUG as string | undefined;
+  if (explicit?.includes('/')) {
+    const [owner, repo] = explicit.split('/');
+    return { owner, repo, branch: 'gh-pages' };
+  }
+  const host = window.location.hostname; // <owner>.github.io
+  const parts = window.location.pathname.split('/').filter(Boolean);
+  if (host.endsWith('.github.io') && parts.length > 0) {
+    return { owner: host.slice(0, -'.github.io'.length), repo: parts[0], branch: 'gh-pages' };
+  }
+  return null;
+}
+
+const TOKEN_KEY = 'excalidrop_gh_token';
+
+export function getToken(): string | null {
+  // Agent handoff: https://<site>/#token=gho_...
+  if (window.location.hash.startsWith('#token=')) {
+    const t = decodeURIComponent(window.location.hash.slice('#token='.length));
+    if (t) {
+      localStorage.setItem(TOKEN_KEY, t);
+      history.replaceState(null, '', window.location.pathname + window.location.search);
+      return t;
+    }
+  }
+  return localStorage.getItem(TOKEN_KEY);
+}
+
+export function setToken(t: string | null): void {
+  if (t) localStorage.setItem(TOKEN_KEY, t);
+  else localStorage.removeItem(TOKEN_KEY);
+}
+
+async function gh(path: string, token: string, init?: RequestInit): Promise<any> {
+  const r = await fetch(`https://api.github.com${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'Content-Type': 'application/json',
+      ...(init?.headers || {}),
+    },
+  });
+  if (!r.ok) throw new Error(`GitHub ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  return r.json();
+}
+
+/** Push scene JSON straight to the branch (viewer copy = source of truth for static mode). */
+export async function pushScene(
+  ref: RepoRef, token: string, scene: { elements: unknown[]; files?: Record<string, unknown> },
+): Promise<string> {
+  const path = 'canvas.excalidraw';
+  let sha: string | undefined;
+  try {
+    const cur = await gh(`/repos/${ref.owner}/${ref.repo}/contents/${path}?ref=${ref.branch}`, token);
+    sha = cur.sha;
+  } catch { /* new file */ }
+  const body: any = {
+    message: `excalidrop: autosync ${scene.elements.length} elements`,
+    content: btoa(unescape(encodeURIComponent(JSON.stringify(
+      { type: 'excalidraw', version: 2, source: 'excalidrop', elements: scene.elements },
+      null, 2,
+    )))),
+    branch: ref.branch,
+  };
+  if (sha) body.sha = sha;
+  const out = await gh(`/repos/${ref.owner}/${ref.repo}/contents/${path}`, token, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  });
+  return out.content.sha as string;
+}
+
+/** Load the static scene copy (no auth needed for public repos). */
+export async function loadStaticScene(): Promise<{ elements: any[]; files?: Record<string, unknown> }> {
+  const r = await fetch('./canvas.excalidraw', { cache: 'no-cache' });
+  if (!r.ok) throw new Error(`scene fetch ${r.status}`);
+  const j = await r.json();
+  return { elements: j.elements || [], files: j.files || {} };
+}
+
+/** Device-flow login. Returns {userCode, verificationUri} — the token
+ *  polling step may be CORS-blocked on static hosting, so the agent can
+ *  complete it instead (github_login tool) and hand back a #token= link.
+ *  NOTE: no `scope` — GitHub App user-tokens use fine-grained permissions
+ *  (user ∩ app), never scopes. */
+export async function startDeviceFlow(clientId: string): Promise<{ user_code: string; verification_uri: string }> {
+  const r = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ client_id: clientId }),
+  });
+  if (!r.ok) throw new Error('device flow start failed');
+  const j = await r.json();
+  return { user_code: j.user_code, verification_uri: j.verification_uri };
+}
+
+export type Access = 'editor' | 'viewer' | 'denied';
+
+export type AccessDetail =
+  | 'app-not-installed' // ghu_ token, but the user has no app installation reaching this repo
+  | 'repo-not-covered' // installation(s) exist, but none of them include this repo
+  | 'no-token-permissions' // classic token with no read access to the repo
+  | null; // editor/viewer — no problem to report
+
+/** What can this token do on this repo? Reads the user's app installations —
+ *  the token only reaches repos both the user AND the app can access, so this
+ *  mirrors GitHub's own enforcement (repo access == canvas access).
+ *  `detail` tells the UI *why* access was denied so the login modal can
+ *  point at the right fix (install the app vs. add this repo to the install). */
+export async function checkAccess(ref: RepoRef, token: string): Promise<{ access: Access; login: string; detail: AccessDetail }> {
+  const me = await gh('/user', token);
+  const login = (me.login || '') as string;
+  const wanted = `${ref.owner}/${ref.repo}`.toLowerCase();
+  // Path 1: GitHub App user-token (ghu_) — installations list the repos it reaches.
+  // Classic PATs/OAuth tokens get 403 here ("must authenticate with an access
+  // token authorized to a GitHub App") and fall through to Path 2.
+  // per_page=100: without it a user with many repos can miss the hit (p.30 default).
+  const inst = await gh('/user/installations?per_page=100', token).catch(() => null);
+  if (inst?.installations) {
+    if ((inst.installations as unknown[]).length === 0) {
+      return { access: 'denied', login, detail: 'app-not-installed' };
+    }
+    for (const i of inst.installations || []) {
+      const repos = await gh(`/user/installations/${(i as any).id}/repositories?per_page=100`, token).catch(() => null);
+      const hit = (repos?.repositories || []).find((r: any) => r.full_name.toLowerCase() === wanted);
+      if (hit) {
+        // Token reaches the repo. Resolve read vs write via the collaborator
+        // permission endpoint; if that probe fails, start optimistic-editor —
+        // the Contents API is the real enforcement and a 403 push demotes to
+        // viewer (fail-open UI, fail-closed API).
+        const perms = await gh(`/repos/${ref.owner}/${ref.repo}/collaborators/${login}/permission`, token).catch(() => null);
+        const p = (perms?.permission || '') as string;
+        if (p === 'read' || p === 'triage') return { access: 'viewer', login, detail: null };
+        return { access: 'editor', login, detail: null };
+      }
+    }
+    return { access: 'denied', login, detail: 'repo-not-covered' };
+  }
+  // Path 2: classic token — the repo endpoint echoes *this token's* permissions.
+  const repo = await gh(`/repos/${ref.owner}/${ref.repo}`, token).catch(() => null);
+  if (!repo?.permissions) return { access: 'denied', login, detail: 'no-token-permissions' };
+  if (repo.permissions.push || repo.permissions.admin || repo.permissions.maintain) {
+    return { access: 'editor', login, detail: null };
+  }
+  return { access: 'viewer', login, detail: null };
+}
+
+/**
+ * Shared GitHub App (one app, many installs — any user installs it on their
+ * own repo; the Client ID is public, not a secret). Overridable at publish
+ * time via VITE_GITHUB_CLIENT_ID / VITE_GITHUB_APP_SLUG.
+ */
+export const CLIENT_ID =
+  ((import.meta as any).env?.VITE_GITHUB_CLIENT_ID as string | undefined) ||
+  'Iv23liuS2fx3QOEIoDmx'; // shared Excalidrop GitHub App (public ID, not a secret)
+export const APP_SLUG =
+  ((import.meta as any).env?.VITE_GITHUB_APP_SLUG as string | undefined) || 'excalidrop';
+export const APP_INSTALL_URL = `https://github.com/apps/${APP_SLUG}/installations/new`;
+/** True when a real Client ID is baked in (not the publish-time placeholder). */
+export const HAS_CLIENT_ID = !!CLIENT_ID && !CLIENT_ID.includes('EXCALIDROP_APP');

package/frontend/src/utils/mermaidConverter.ts

@@ -0,0 +1,49 @@
+import { parseMermaidToExcalidraw, MermaidConfig } from '@excalidraw/mermaid-to-excalidraw';
+import type { ExcalidrawElement } from '@excalidraw/excalidraw/types/element/types';
+import type { BinaryFiles } from '@excalidraw/excalidraw/types/types';
+
+export interface MermaidConversionResult {
+  elements: readonly ExcalidrawElement[];
+  files?: BinaryFiles;
+  error?: string;
+}
+
+/**
+ * Converts a Mermaid diagram definition to Excalidraw elements
+ * This function needs to run in the browser context as it requires DOM access
+ */
+export const convertMermaidToExcalidraw = async (
+  mermaidDefinition: string,
+  config?: MermaidConfig
+): Promise<MermaidConversionResult> => {
+  try {
+    // Parse the Mermaid diagram to Excalidraw elements
+    const result = await parseMermaidToExcalidraw(mermaidDefinition, config);
+    
+    return {
+      elements: result.elements,
+      files: result.files,
+    };
+  } catch (error) {
+    console.error('Error converting Mermaid to Excalidraw:', error);
+    return {
+      elements: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
+/**
+ * Default Mermaid configuration for Excalidraw conversion
+ */
+export const DEFAULT_MERMAID_CONFIG: MermaidConfig = {
+  startOnLoad: false,
+  flowchart: {
+    curve: 'linear',
+  },
+  themeVariables: {
+    fontSize: '20px',
+  },
+  maxEdges: 500,
+  maxTextSize: 50000,
+};

package/frontend/src/utils/webmcp.ts

@@ -0,0 +1,285 @@
+/**
+ * Thin WebMCP layer for the Excalidrop canvas.
+ *
+ * Exposes the live in-tab Excalidraw scene as browser-native tools via
+ * `document.modelContext.registerTool()` (W3C WebML CG draft, Chromium 146+
+ * behind `#enable-webmcp-testing`). No-ops where the API is absent.
+ *
+ * Tools mirror the local MCP names so agents recognise them:
+ *  - describe_scene (read-only)
+ *  - create_elements (write)
+ *  - update_element (write)
+ *  - delete_element (write)
+ *  - clear_canvas (consequential)
+ *
+ * The page itself is the tool registry — no HTTP/SSE/stdio involved.
+ * Auth/session comes for free: tools run inside the user's tab.
+ */
+
+interface MinimalCanvasApi {
+  getSceneElements(): Array<Record<string, any>>;
+  updateScene(scene: { elements: Array<Record<string, any>> }): void;
+  resetScene(): void;
+}
+
+export type CanvasApiGetter = () => MinimalCanvasApi | null | undefined;
+
+export interface WebMCPHandle {
+  available: boolean;
+  count: number;
+  cleanup: () => void;
+}
+
+interface ModelContextLike {
+  registerTool(
+    tool: {
+      name: string;
+      title?: string;
+      description: string;
+      inputSchema: Record<string, unknown>;
+      annotations?: Record<string, unknown>;
+      execute: (args: any, opts?: { signal?: AbortSignal }) => unknown | Promise<unknown>;
+    },
+    options?: { signal?: AbortSignal },
+  ): Promise<void>;
+}
+
+function getModelContext(): ModelContextLike | null {
+  try {
+    const doc = document as unknown as Record<string, unknown>;
+    const nav = navigator as unknown as Record<string, unknown>;
+    const mc =
+      (doc['modelContext'] as ModelContextLike | undefined) ??
+      (nav['modelContext'] as ModelContextLike | undefined);
+    if (mc && typeof mc.registerTool === 'function') return mc;
+  } catch {
+    /* non-DOM / restricted context */
+  }
+  return null;
+}
+
+function newId(): string {
+  try {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+      return (crypto as Crypto).randomUUID().slice(0, 12);
+    }
+  } catch {
+    /* fall through */
+  }
+  return `el_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function summarize(el: Record<string, any>): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    id: el['id'],
+    type: el['type'],
+    x: Math.round(Number(el['x'] ?? 0)),
+    y: Math.round(Number(el['y'] ?? 0)),
+  };
+  if (el['width'] !== undefined) out['width'] = el['width'];
+  if (el['height'] !== undefined) out['height'] = el['height'];
+  const text =
+    (typeof el['text'] === 'string' && el['text']) ||
+    (el['label'] as { text?: string } | undefined)?.text;
+  if (text) out['text'] = String(text).slice(0, 120);
+  if (el['locked']) out['locked'] = true;
+  return out;
+}
+
+const ELEMENT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Custom element ID (auto-generated if omitted)' },
+    type: { type: 'string', description: 'Excalidraw element type: rectangle, ellipse, diamond, text, arrow, line, freedraw, image' },
+    x: { type: 'number' },
+    y: { type: 'number' },
+    width: { type: 'number' },
+    height: { type: 'number' },
+    text: { type: 'string', description: 'Label text for shapes / content for text elements' },
+    backgroundColor: { type: 'string' },
+    strokeColor: { type: 'string' },
+    strokeWidth: { type: 'number' },
+    fontSize: { type: 'number' },
+    startElementId: { type: 'string', description: 'For arrows: bind start to this element ID' },
+    endElementId: { type: 'string', description: 'For arrows: bind end to this element ID' },
+  },
+  required: ['type', 'x', 'y'],
+  additionalProperties: true,
+};
+
+/**
+ * Register the thin WebMCP toolset against the live canvas.
+ * Safe to call anywhere: feature-detects `document.modelContext` first.
+ * Returns a handle whose `cleanup()` unregisters all tools (AbortSignal).
+ */
+export function registerCanvasWebMCP(getApi: CanvasApiGetter): WebMCPHandle {
+  const noop = () => {};
+  const mc = getModelContext();
+  if (!mc) return { available: false, count: 0, cleanup: noop };
+
+  const controller = new AbortController();
+  const signal = controller.signal;
+  let count = 0;
+
+  const requireApi = (): MinimalCanvasApi => {
+    const api = getApi();
+    if (!api) throw new Error('Canvas not ready yet');
+    return api;
+  };
+
+  const safeRegister = (tool: Parameters<ModelContextLike['registerTool']>[0]): void => {
+    try {
+      const p = mc.registerTool(tool, { signal });
+      if (p && typeof (p as Promise<void>).catch === 'function') {
+        (p as Promise<void>).catch(() => {
+          /* duplicate / invalid — ignore, keeps thin layer best-effort */
+        });
+      }
+      count += 1;
+    } catch {
+      /* API present but rejected synchronously — ignore */
+    }
+  };
+
+  safeRegister({
+    name: 'describe_scene',
+    title: 'Describe canvas scene',
+    description:
+      'Read-only summary of the live Excalidraw canvas: element counts by type plus id/type/position/label per element (capped at 200). Call before editing.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+    execute: () => {
+      const api = requireApi();
+      const els = api.getSceneElements().filter((e) => !e['isDeleted']);
+      const byType: Record<string, number> = {};
+      for (const e of els) {
+        const t = String(e['type'] ?? 'unknown');
+        byType[t] = (byType[t] ?? 0) + 1;
+      }
+      return {
+        count: els.length,
+        byType,
+        elements: els.slice(0, 200).map(summarize),
+      };
+    },
+  });
+
+  safeRegister({
+    name: 'create_elements',
+    title: 'Create canvas elements',
+    description:
+      'Add new elements to the live canvas in one batch. Assign custom ids to shapes so arrows can reference them via startElementId/endElementId.',
+    inputSchema: {
+      type: 'object',
+      properties: { elements: { type: 'array', items: ELEMENT_SCHEMA, minItems: 1 } },
+      required: ['elements'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: false },
+    execute: (args: { elements?: Array<Record<string, any>> }) => {
+      const api = requireApi();
+      const input = Array.isArray(args?.elements) ? args.elements : [];
+      if (input.length === 0) throw new Error('elements must be a non-empty array');
+      if (input.length > 200) throw new Error('max 200 elements per call');
+      const created = input.map((raw) => {
+        if (!raw || typeof raw !== 'object') throw new Error('each element must be an object');
+        if (typeof raw['type'] !== 'string') throw new Error('each element needs a type');
+        if (typeof raw['x'] !== 'number' || typeof raw['y'] !== 'number') {
+          throw new Error('each element needs numeric x and y');
+        }
+        const { startElementId, endElementId, ...rest } = raw;
+        const el: Record<string, any> = { id: newId(), ...rest };
+        if (typeof startElementId === 'string') el['start'] = { id: startElementId };
+        if (typeof endElementId === 'string') el['end'] = { id: endElementId };
+        if ((el['type'] === 'arrow' || el['type'] === 'line') && !Array.isArray(el['points'])) {
+          el['points'] = [
+            [0, 0],
+            [100, 0],
+          ];
+        }
+        return el;
+      });
+      const current = api.getSceneElements();
+      api.updateScene({ elements: [...current, ...created] });
+      return { ok: true, count: created.length, ids: created.map((e) => e['id']) };
+    },
+  });
+
+  safeRegister({
+    name: 'update_element',
+    title: 'Update canvas element',
+    description: 'Patch position, size, colors, or text of one element by id on the live canvas.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Element ID from describe_scene' },
+        patch: {
+          type: 'object',
+          description: 'Fields to merge (x, y, width, height, backgroundColor, strokeColor, text, ...)',
+        },
+      },
+      required: ['id', 'patch'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: false },
+    execute: (args: { id?: string; patch?: Record<string, unknown> }) => {
+      const api = requireApi();
+      if (!args?.id) throw new Error('id is required');
+      if (!args?.patch || typeof args.patch !== 'object') throw new Error('patch must be an object');
+      const current = api.getSceneElements();
+      const idx = current.findIndex((e) => e['id'] === args.id);
+      if (idx === -1) throw new Error(`Element ${args.id} not found`);
+      const next = current.slice();
+      next[idx] = { ...current[idx], ...args.patch, id: args.id };
+      api.updateScene({ elements: next });
+      return { ok: true, id: args.id };
+    },
+  });
+
+  safeRegister({
+    name: 'delete_element',
+    title: 'Delete canvas element',
+    description: 'Remove one element by id from the live canvas.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true },
+    execute: (args: { id?: string }) => {
+      const api = requireApi();
+      if (!args?.id) throw new Error('id is required');
+      const current = api.getSceneElements();
+      if (!current.some((e) => e['id'] === args.id)) throw new Error(`Element ${args.id} not found`);
+      api.updateScene({ elements: current.filter((e) => e['id'] !== args.id) });
+      return { ok: true, deleted: args.id };
+    },
+  });
+
+  safeRegister({
+    name: 'clear_canvas',
+    title: 'Clear canvas',
+    description: 'Remove ALL elements from the live canvas. Ask the user to confirm first.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { destructiveHint: true, consequentialHint: true },
+    execute: () => {
+      const api = requireApi();
+      const n = api.getSceneElements().length;
+      api.resetScene();
+      return { ok: true, cleared: n };
+    },
+  });
+
+  return {
+    available: true,
+    count,
+    cleanup: () => {
+      try {
+        controller.abort();
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "excalidrop",
+  "version": "0.1.1",
+  "description": "Drop an Excalidraw canvas + MCP server into any project — per-project ports, one-command AI agent setup",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "excalidrop": "dist/cli.js",
+    "mcp-excalidraw-server": "dist/index.js"
+  },
+  "scripts": {
+    "start": "npm run build:server && node dist/index.js",
+    "canvas": "npm run build:server && node dist/server.js",
+    "build": "npm run build:frontend && npm run build:server",
+    "build:frontend": "vite build",
+    "build:server": "npx tsc",
+    "build:types": "npx tsc --emitDeclarationOnly",
+    "dev": "concurrently \"npm run dev:server\" \"vite\"",
+    "dev:server": "npx tsc --watch",
+    "production": "npm run build && npm run canvas",
+    "postinstall": "node scripts/postinstall.mjs",
+    "excalidrop": "node dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "test:bind": "npm run build:server && node scripts/check-local-bind.mjs",
+    "type-check": "npx tsc --noEmit"
+  },
+  "dependencies": {
+    "@excalidraw/excalidraw": "^0.18.0",
+    "@excalidraw/mermaid-to-excalidraw": "^1.1.3",
+    "@modelcontextprotocol/sdk": "latest",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "mermaid": "^11.12.1",
+    "node-fetch": "^3.3.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "winston": "^3.11.0",
+    "ws": "^8.14.2",
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.22.3"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.19.7",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@types/ws": "^8.5.10",
+    "@vitejs/plugin-react": "^4.6.0",
+    "concurrently": "^9.2.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5"
+  },
+  "keywords": [
+    "excalidrop",
+    "excalidraw",
+    "model-context-protocol",
+    "ai",
+    "drawing",
+    "diagrams",
+    "canvas",
+    "real-time",
+    "websocket",
+    "visualization",
+    "claude",
+    "ai-tools"
+  ],
+  "author": {
+    "name": "yctimlin",
+    "email": "c22647809@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtf403/excalidrop.git"
+  },
+  "homepage": "https://github.com/wtf403/excalidrop#readme",
+  "bugs": {
+    "url": "https://github.com/wtf403/excalidrop/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src/**/*",
+    "dist/**/*",
+    "frontend/**/*",
+    "scripts/**/*",
+    "skills/**/*",
+    "*.d.ts",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json",
+    "vite.config.js"
+  ]
+}