taskia-prototype-mcp 3.0.0

package/README.md

@@ -0,0 +1,120 @@
+# taskia-prototype-mcp
+
+MCP server that lets agents **browse and see** the live Taskia design prototype.
+
+The MCP opens a real Chromium browser pointed at the published GitHub Pages URL.
+Agents can navigate screens, click UI elements, hover for tooltips, scroll — and every
+action returns a screenshot so they can see exactly what happened.
+
+Because it connects to the **live GitHub Pages deployment**, agents always see
+Andreina's latest design — no local clone, no `REPO_PATH` required.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `screenshot` | PNG of whatever is visible right now |
+| `go_to_screen` | Navigate to a named screen + screenshot |
+| `click` | Click an element by visible text + screenshot |
+| `hover` | Hover an element (tooltips / hover states) + screenshot |
+| `scroll` | Scroll the page + screenshot |
+| `list_interactive_elements` | Every clickable element currently on screen |
+| `reload` | Reload from GitHub Pages (picks up Andreina's latest push) |
+| `reset` | Return to default screen (Tasks, signed in) |
+| `list_screens` | All screen names available in the prototype |
+| `get_design_tokens` | CSS custom properties (light + dark) from live `styles.css` |
+| `get_design_system_docs` | Full `DESIGN_SYSTEM.md` |
+| `get_prototype_url` | The live GitHub Pages URL |
+
+---
+
+## Setup
+
+### 1. Clone the repo
+
+```bash
+git clone https://github.com/Omicron-Group-Solutions/prototipo_diseno.git
+cd prototipo_diseno/mcp-server
+```
+
+### 2. Install dependencies + Chromium
+
+```bash
+npm install
+npm run install-browser
+```
+
+> `install-browser` downloads a local Chromium (~130 MB, one-time).
+
+### 3. Add to Claude Code
+
+Edit `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "taskia-prototype": {
+      "command": "node",
+      "args": ["C:\\Users\\You\\Desktop\\prototipo_diseno\\mcp-server\\server.js"]
+    }
+  }
+}
+```
+
+> No `REPO_PATH` needed — the MCP fetches everything from GitHub Pages.
+
+### 4. Restart Claude Code
+
+---
+
+## Watch the browser (optional)
+
+Add `HEADLESS=false` to see the browser window on screen while agents drive it:
+
+```json
+{
+  "mcpServers": {
+    "taskia-prototype": {
+      "command": "node",
+      "args": ["C:\\Users\\You\\Desktop\\prototipo_diseno\\mcp-server\\server.js"],
+      "env": {
+        "HEADLESS": "false"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Staying up to date
+
+When Andreina pushes a design update, call `reload()` — the browser refreshes from
+GitHub Pages and returns a screenshot of the new design. No restart needed.
+
+---
+
+## Example usage
+
+```
+"Show me the Tasks screen"
+→ go_to_screen({ screen_name: "ScreenTasks" })
+
+"What can I click on the Kanban board?"
+→ go_to_screen({ screen_name: "ScreenKanban" })
+→ list_interactive_elements()
+
+"Click that task to open the detail panel"
+→ click({ text: "Diseño nuevo sistema" })
+
+"Show the hover state on the sidebar"
+→ hover({ text: "Kanban" })
+
+"What color is the primary button?"
+→ get_design_tokens()   ← look for --brand or --btn-*
+
+"Andreina just pushed an update — show me"
+→ reload()
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "taskia-prototype-mcp",
+  "version": "3.0.0",
+  "description": "MCP server — browse the live Taskia prototype, screenshot any screen, interact with UI elements",
+  "type": "module",
+  "bin": {
+    "taskia-prototype-mcp": "server.js"
+  },
+  "files": [
+    "server.js"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "install-browser": "playwright install chromium",
+    "postinstall": "playwright install chromium"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "playwright": "^1.49.0"
+  }
+}

package/server.js

@@ -0,0 +1,536 @@
+#!/usr/bin/env node
+/**
+ * taskia-prototype-mcp  v3
+ *
+ * Design-focused MCP that browses the LIVE GitHub Pages prototype.
+ *
+ * No local clone required — everything is fetched from the published URL,
+ * so the MCP always reflects Andreina's latest push automatically.
+ *
+ * A persistent Playwright session keeps one browser open across all tool
+ * calls. Set  HEADLESS=false  in the env to show the browser window on
+ * screen while agents drive it.
+ *
+ * Tools
+ * ─────────────────────────────────────────────────────────────────────────
+ *   screenshot                — PNG of whatever is visible right now
+ *   go_to_screen              — jump to a named screen
+ *   click                     — click an element by visible text
+ *   hover                     — hover an element (tooltips / hover states)
+ *   scroll                    — scroll the page in any direction
+ *   list_interactive_elements — every clickable element on screen
+ *   reload                    — reload from GitHub Pages (picks up latest push)
+ *   reset                     — return to default screen (Tasks, signed in)
+ *   list_screens              — all screen names in the prototype
+ *   get_design_tokens         — CSS custom properties (light + dark)
+ *   get_design_system_docs    — full DESIGN_SYSTEM.md
+ *   get_prototype_url         — the live GitHub Pages URL
+ *
+ * Optional env vars:
+ *   HEADLESS=false  → shows the browser window (watch agents drive the prototype)
+ */
+
+import { Server }               from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { chromium } from 'playwright';
+
+// ── Config ─────────────────────────────────────────────────────────────────
+
+const PAGES_URL = 'https://omicron-group-solutions.github.io/prototipo_diseno/';
+const HEADLESS  = process.env.HEADLESS !== 'false';  // default: headless; set HEADLESS=false to show window
+
+const SCREEN_IDS = {
+  ScreenLogin:     'login',
+  ScreenDashboard: 'dashboard',
+  ScreenTasks:     'tasks',
+  ScreenKanban:    'kanban',
+  ScreenCalendar:  'calendar',
+  ScreenReports:   'reports',
+  ScreenContacts:  'contacts',
+  ScreenLabels:    'labels',
+};
+
+// ── Persistent browser session ─────────────────────────────────────────────
+
+let _browser = null;
+let _page    = null;
+
+/** Returns the live page, launching a new browser if needed. */
+async function getPage() {
+  if (_page) {
+    try {
+      await _page.title();   // ping — throws if page is dead
+      return _page;
+    } catch {
+      _page    = null;
+      _browser = null;
+    }
+  }
+
+  _browser = await chromium.launch({
+    headless: HEADLESS,
+    args: HEADLESS ? [] : ['--start-maximized'],
+  });
+
+  const ctx = await _browser.newContext({
+    viewport: { width: 1440, height: 900 },
+  });
+
+  _page = await ctx.newPage();
+  await _page.goto(PAGES_URL, { waitUntil: 'networkidle', timeout: 30_000 });
+  await _page.waitForSelector('.app', { timeout: 20_000 });
+
+  return _page;
+}
+
+// Clean up when the MCP server exits
+process.on('SIGTERM', () => _browser?.close().catch(() => {}));
+process.on('SIGINT',  () => _browser?.close().catch(() => {}));
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+async function snap() {
+  const page = await getPage();
+  const png  = await page.screenshot({ type: 'png', fullPage: false });
+  return png.toString('base64');
+}
+
+/** Fetch a file from the live GitHub Pages deployment. */
+async function fetchAsset(path) {
+  const url = PAGES_URL.replace(/\/$/, '') + '/' + path.replace(/^\//, '');
+  const res  = await fetch(url);
+  if (!res.ok)
+    throw new Error(
+      `Could not fetch "${path}" from GitHub Pages (HTTP ${res.status}). ` +
+      `Make sure GitHub Pages is published at ${PAGES_URL}`
+    );
+  return res.text();
+}
+
+function parseDesignTokens(css) {
+  const light = {}, dark = {};
+  for (const [, block] of css.matchAll(/:root(?:\[.*?\])?\s*\{([^}]+)\}/g))
+    for (const [, k, v] of block.matchAll(/--([^:]+):\s*([^;]+);/g))
+      light[`--${k.trim()}`] = v.trim();
+  for (const [, block] of css.matchAll(/\[data-theme="dark"\]\s*\{([^}]+)\}/g))
+    for (const [, k, v] of block.matchAll(/--([^:]+):\s*([^;]+);/g))
+      dark[`--${k.trim()}`] = v.trim();
+  return { light, dark };
+}
+
+// ── MCP server ─────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'taskia-prototype', version: '3.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'screenshot',
+      description:
+        'Returns a PNG of whatever the prototype browser is showing right now. ' +
+        'Call after any navigation or interaction to see the result.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'go_to_screen',
+      description:
+        'Navigate the prototype to a specific screen and return a screenshot. ' +
+        'Call list_screens to get valid names.',
+      inputSchema: {
+        type: 'object',
+        required: ['screen_name'],
+        properties: {
+          screen_name: {
+            type: 'string',
+            description:
+              'Screen component name, e.g. ScreenTasks, ScreenKanban, ScreenLogin, ' +
+              'ScreenDashboard, ScreenCalendar, ScreenReports, ScreenContacts, ScreenLabels.',
+          },
+        },
+      },
+    },
+    {
+      name: 'click',
+      description:
+        'Click an element by its visible text. ' +
+        'Call list_interactive_elements to see what is on screen. ' +
+        'Returns a screenshot of the state after the click.',
+      inputSchema: {
+        type: 'object',
+        required: ['text'],
+        properties: {
+          text: {
+            type: 'string',
+            description: 'Visible label / text of the element to click (partial match, case-insensitive).',
+          },
+          exact: {
+            type: 'boolean',
+            description: 'Match the text exactly. Default false (partial match).',
+          },
+        },
+      },
+    },
+    {
+      name: 'hover',
+      description:
+        'Hover over an element to reveal tooltips, hover states, or dropdowns. ' +
+        'Returns a screenshot of the hover state.',
+      inputSchema: {
+        type: 'object',
+        required: ['text'],
+        properties: {
+          text: {
+            type: 'string',
+            description: 'Visible text of the element to hover.',
+          },
+        },
+      },
+    },
+    {
+      name: 'scroll',
+      description: 'Scroll the prototype. Returns a screenshot of the new position.',
+      inputSchema: {
+        type: 'object',
+        required: ['direction'],
+        properties: {
+          direction: {
+            type: 'string',
+            enum: ['up', 'down', 'left', 'right'],
+          },
+          amount: {
+            type: 'number',
+            description: 'Pixels to scroll. Default 300.',
+          },
+        },
+      },
+    },
+    {
+      name: 'list_interactive_elements',
+      description:
+        'Lists every visible, interactive element on the current screen — ' +
+        'buttons, nav items, tabs, links, inputs. ' +
+        'Use this before calling click() to discover what is available.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'reload',
+      description:
+        'Reload the prototype from GitHub Pages to pick up the latest design Andreina has pushed. ' +
+        'Returns a screenshot of the freshly loaded prototype.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'reset',
+      description: 'Return to the default screen (Tasks, signed in). Start fresh from a known state.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'list_screens',
+      description: 'Lists all screens in the prototype. Use these names with go_to_screen.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'get_design_tokens',
+      description:
+        'Returns all CSS custom properties (colors, spacing, radius, blur) for both themes, ' +
+        'fetched live from the published prototype. Source of truth for design values.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'get_design_system_docs',
+      description:
+        'Returns the full DESIGN_SYSTEM.md — every token, component pattern, and design decision. ' +
+        'Read before implementing any screen.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'get_prototype_url',
+      description: 'Returns the live GitHub Pages URL of the Taskia prototype.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+  ],
+}));
+
+// ── Tool handlers ──────────────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    switch (name) {
+
+      // ── screenshot ──────────────────────────────────────────────────────
+      case 'screenshot': {
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: 'Current prototype state:' },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── go_to_screen ────────────────────────────────────────────────────
+      case 'go_to_screen': {
+        const page       = await getPage();
+        const screenName = args.screen_name ?? '';
+        const id         = SCREEN_IDS[screenName] ?? screenName.toLowerCase();
+
+        if (id === 'login') {
+          await page.evaluate(() => window.__setSignedIn?.(false));
+        } else {
+          await page.evaluate((sid) => {
+            window.__setSignedIn?.(true);
+            window.__setScreen?.(sid);
+          }, id);
+        }
+
+        await page.waitForTimeout(600);
+
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: `Navigated to ${screenName} (id: "${id}")` },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── click ───────────────────────────────────────────────────────────
+      case 'click': {
+        const page    = await getPage();
+        const exact   = args.exact ?? false;
+        const locator = page.getByText(args.text, { exact });
+        const count   = await locator.count();
+
+        if (count === 0) {
+          return {
+            content: [{ type: 'text', text: `No visible element found with text "${args.text}". Call list_interactive_elements to see what is on screen.` }],
+            isError: true,
+          };
+        }
+
+        await locator.first().click({ timeout: 5_000 });
+        await page.waitForTimeout(400);
+
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: `Clicked "${args.text}"` },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── hover ───────────────────────────────────────────────────────────
+      case 'hover': {
+        const page    = await getPage();
+        const locator = page.getByText(args.text, { exact: false });
+        const count   = await locator.count();
+
+        if (count === 0) {
+          return {
+            content: [{ type: 'text', text: `No visible element found with text "${args.text}"` }],
+            isError: true,
+          };
+        }
+
+        await locator.first().hover({ timeout: 5_000 });
+        await page.waitForTimeout(350);
+
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: `Hovering over "${args.text}"` },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── scroll ──────────────────────────────────────────────────────────
+      case 'scroll': {
+        const page   = await getPage();
+        const amount = args.amount ?? 300;
+        const deltas = {
+          down:  [0,  amount],
+          up:    [0, -amount],
+          right: [ amount, 0],
+          left:  [-amount, 0],
+        };
+        const [dx, dy] = deltas[args.direction] ?? [0, 300];
+        await page.mouse.wheel(dx, dy);
+        await page.waitForTimeout(300);
+
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: `Scrolled ${args.direction} ${amount}px` },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── list_interactive_elements ────────────────────────────────────────
+      case 'list_interactive_elements': {
+        const page = await getPage();
+
+        const elements = await page.evaluate(() => {
+          const SELECTORS = [
+            'button', 'a[href]',
+            '[role="button"]', '[role="link"]', '[role="tab"]',
+            '[role="menuitem"]', '[role="option"]',
+            'input', 'select', '[onclick]',
+            '.nav-item', '.ws-item', '.sidebar-item', '.tab', '.btn',
+          ];
+
+          const seen    = new Set();
+          const results = [];
+
+          for (const sel of SELECTORS) {
+            for (const el of document.querySelectorAll(sel)) {
+              const rect = el.getBoundingClientRect();
+              // skip invisible or off-screen elements
+              if (rect.width === 0 || rect.height === 0) continue;
+              if (rect.top > window.innerHeight + 20 || rect.bottom < -20) continue;
+
+              const text = (
+                el.textContent ||
+                el.getAttribute('aria-label') ||
+                el.getAttribute('title') ||
+                el.getAttribute('placeholder') ||
+                ''
+              ).trim().replace(/\s+/g, ' ').slice(0, 60);
+
+              if (!text) continue;
+
+              const key = `${el.tagName}|${text}`;
+              if (seen.has(key)) continue;
+              seen.add(key);
+
+              const role = el.getAttribute('role');
+              const tag  = el.tagName.toLowerCase() + (role ? `[role=${role}]` : '');
+              results.push({ tag, text });
+            }
+          }
+
+          return results;
+        });
+
+        const lines = elements.map(e => `  [${e.tag}] "${e.text}"`).join('\n');
+        return {
+          content: [{
+            type: 'text',
+            text: `Interactive elements (${elements.length}):\n${lines}\n\nUse click({ text: "..." }) with any of these labels.`,
+          }],
+        };
+      }
+
+      // ── reload ──────────────────────────────────────────────────────────
+      case 'reload': {
+        const page = await getPage();
+        await page.reload({ waitUntil: 'networkidle', timeout: 30_000 });
+        await page.waitForSelector('.app', { timeout: 20_000 });
+        await page.waitForTimeout(500);
+
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: `Prototype reloaded — now showing the latest design from:\n${PAGES_URL}` },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── reset ───────────────────────────────────────────────────────────
+      case 'reset': {
+        const page = await getPage();
+        await page.evaluate(() => {
+          window.__setSignedIn?.(true);
+          window.__setScreen?.('tasks');
+        });
+        await page.waitForTimeout(600);
+
+        const png = await snap();
+        return {
+          content: [
+            { type: 'text',  text: 'Reset to default screen (Tasks, signed in).' },
+            { type: 'image', data: png, mimeType: 'image/png' },
+          ],
+        };
+      }
+
+      // ── list_screens ─────────────────────────────────────────────────────
+      case 'list_screens': {
+        const source  = await fetchAsset('screens.jsx');
+        const screens = [...source.matchAll(/^function\s+(Screen[A-Za-z]+)\s*\(/gm)].map(m => m[1]);
+        return {
+          content: [{
+            type: 'text',
+            text: `Screens (${screens.length}):\n${screens.map(s => `  • ${s}`).join('\n')}\n\nUse go_to_screen with any of these names.`,
+          }],
+        };
+      }
+
+      // ── get_design_tokens ─────────────────────────────────────────────────
+      case 'get_design_tokens': {
+        const css         = await fetchAsset('styles.css');
+        const { light, dark } = parseDesignTokens(css);
+        const fmt         = obj => Object.entries(obj).map(([k, v]) => `  ${k}: ${v}`).join('\n');
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              `### Light theme (${Object.keys(light).length} tokens)`,
+              fmt(light),
+              '',
+              `### Dark theme overrides (${Object.keys(dark).length})`,
+              fmt(dark),
+            ].join('\n'),
+          }],
+        };
+      }
+
+      // ── get_design_system_docs ────────────────────────────────────────────
+      case 'get_design_system_docs': {
+        const docs = await fetchAsset('DESIGN_SYSTEM.md');
+        return { content: [{ type: 'text', text: docs }] };
+      }
+
+      // ── get_prototype_url ─────────────────────────────────────────────────
+      case 'get_prototype_url':
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              `Live prototype : ${PAGES_URL}`,
+              `Source repo    : https://github.com/Omicron-Group-Solutions/prototipo_diseno`,
+              '',
+              'Always reflects the latest design Andreina has pushed to main.',
+              'Call reload() after a push to refresh the browser session.',
+            ].join('\n'),
+          }],
+        };
+
+      default:
+        throw new Error(`Unknown tool: "${name}"`);
+    }
+
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start ──────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);