@protoscan/mcp 0.0.1

package/README.md

@@ -0,0 +1,66 @@
+# @protoscan/mcp
+
+MCP server for ProtoScan — expose Figma prototype QA as a tool for Claude and other MCP clients.
+
+Gives Claude (and any MCP-compatible client) a `scan_figma_prototype` tool that detects dead-end screens, orphan screens, broken back-navigation, small touch targets, overlapping hotspots, missing scroll, and overlay traps in any Figma prototype.
+
+## Setup with Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "protoscan": {
+      "command": "npx",
+      "args": ["-y", "@protoscan/mcp"],
+      "env": {
+        "FIGMA_TOKEN": "your_figma_token_here"
+      }
+    }
+  }
+}
+```
+
+Config file location:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Get your Figma token at: **https://www.figma.com/settings** → Personal access tokens
+
+## Tool: `scan_figma_prototype`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_key` | string | Yes | Figma file key or full URL |
+| `token` | string | No | Figma PAT (falls back to `FIGMA_TOKEN` env var) |
+| `format` | `terminal` \| `json` | No | Output format (default: `terminal`) |
+| `min_touch_target` | number | No | Minimum touch target size in px (default: 44) |
+| `skip` | string[] | No | Checks to skip |
+
+### Example prompts in Claude
+
+```
+Scan this Figma prototype for issues: https://www.figma.com/design/abc123/My-App
+```
+
+```
+Run protoscan on file key PDShpnJG1i8wGIf4ErIiRL and return JSON
+```
+
+## Manual usage
+
+```bash
+# Run directly
+FIGMA_TOKEN=your_token npx @protoscan/mcp
+
+# Or install globally
+npm install -g @protoscan/mcp
+FIGMA_TOKEN=your_token mcp-protoscan
+```
+
+## Related packages
+
+- [`@protoscan/cli`](https://www.npmjs.com/package/@protoscan/cli) — Command-line interface
+- [`@protoscan/core`](https://www.npmjs.com/package/@protoscan/core) — Core analysis library
+- [GitHub](https://github.com/oxxo/protoscan)

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+// src/index.ts
+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 { z } from "zod";
+import { FigmaClient, FigmaApiError, scan, formatTerminal, formatJson } from "@protoscan/core";
+var ScanArgsSchema = z.object({
+  file_key: z.string().describe('Figma file key or full URL (e.g. "abc123" or "https://figma.com/design/abc123/Name?node-id=7-2")'),
+  token: z.string().optional().describe("Figma Personal Access Token. Falls back to FIGMA_TOKEN env var."),
+  format: z.enum(["terminal", "json"]).optional().default("terminal").describe("Output format"),
+  min_touch_target: z.number().optional().default(44).describe("Minimum touch target size in px"),
+  skip: z.array(z.string()).optional().describe("Checks to skip: dead-end, orphan, back-nav, touch-target, overlap, scroll, overlay-trap")
+});
+function parseFigmaInput(input) {
+  const urlMatch = input.match(/figma\.com\/(?:design|file)\/([a-zA-Z0-9]+)/);
+  if (urlMatch) {
+    const fileKey = urlMatch[1];
+    const nodeMatch = input.match(/node-id=([0-9]+-[0-9]+)/);
+    const pageIds = nodeMatch ? [nodeMatch[1].replace("-", ":")] : [];
+    return { fileKey, pageIds };
+  }
+  return { fileKey: input, pageIds: [] };
+}
+var server = new Server(
+  { name: "protoscan", version: "0.0.1" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "scan_figma_prototype",
+      description: "Scan a Figma file for prototype navigation issues: dead-end screens, orphan screens, missing back navigation, undersized touch targets, overlapping hotspots, missing scroll, and overlay traps. Returns a detailed report.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          file_key: { type: "string", description: "Figma file key from the URL" },
+          token: { type: "string", description: "Figma PAT (optional, falls back to FIGMA_TOKEN env var)" },
+          format: { type: "string", enum: ["terminal", "json"], default: "terminal" },
+          min_touch_target: { type: "number", default: 44, description: "Min touch target px" },
+          skip: { type: "array", items: { type: "string" }, description: "Checks to skip" }
+        },
+        required: ["file_key"]
+      }
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== "scan_figma_prototype") {
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+  const args = ScanArgsSchema.parse(request.params.arguments);
+  const token = args.token || process.env.FIGMA_TOKEN;
+  if (!token) {
+    return {
+      content: [{
+        type: "text",
+        text: 'Error: Figma token required. Pass it as "token" parameter or set FIGMA_TOKEN env var.'
+      }],
+      isError: true
+    };
+  }
+  try {
+    const { fileKey, pageIds } = parseFigmaInput(args.file_key);
+    const client = new FigmaClient(token);
+    const file = await client.getFile(fileKey);
+    const result = await scan(file, {
+      fileKey,
+      minTouchTarget: args.min_touch_target,
+      skip: args.skip,
+      pageIds: pageIds.length ? pageIds : void 0
+    });
+    const output = args.format === "json" ? formatJson(result) : formatTerminal(result);
+    return {
+      content: [{ type: "text", text: output }]
+    };
+  } catch (error) {
+    const message = error instanceof FigmaApiError ? error.message : error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("ProtoScan MCP server started");
+}
+main().catch((error) => {
+  console.error("Fatal:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@protoscan/mcp",
+  "version": "0.0.1",
+  "description": "MCP server for ProtoScan — expose Figma prototype QA as a tool for Claude and other MCP clients.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "mcp-protoscan": "./dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.1",
+    "@protoscan/core": "0.0.1",
+    "zod": "^3.23.8"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}