figura-mcp 0.2.0

package/README.md

@@ -0,0 +1,57 @@
+# figura-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
+the **Figura** visualization SaaS to MCP clients (Claude Code, Claude Desktop,
+etc.). It speaks to the Figura `/api/v1` HTTP API with a Bearer `fig_` token over
+stdio.
+
+## Token
+
+The server reads the token from, in order:
+
+1. `FIGURA_TOKEN` environment variable
+2. `~/.figura/config.json` (`{ "token": "fig_..." }`) — the same file the
+   `figura-cli` `figura login` command writes.
+
+Base URL defaults to `https://figura.so`; override with `FIGURA_API_URL`.
+All requests carry the `X-Figura-Source: mcp` header.
+
+## Add to Claude Code
+
+```bash
+claude mcp add figura --env FIGURA_TOKEN=fig_xxxxxxxx -- bunx -y figura-mcp
+
+# no bun? npx still works:
+claude mcp add figura --env FIGURA_TOKEN=fig_xxxxxxxx -- npx -y figura-mcp
+```
+
+If you've already run `figura login`, the `--env FIGURA_TOKEN=...` is optional —
+the server will fall back to `~/.figura/config.json`.
+
+## Tools
+
+| Tool                | Input                                                                                              |
+| ------------------- | -------------------------------------------------------------------------------------------------- |
+| `figura_whoami`      | `{}`                                                                                               |
+| `figura_create_fig`  | `html`, optional `title`, `description`, `area`, `tags[]`, `orientation`, `mode`, `model`, `issue` |
+| `figura_list_figs` | optional `area`, `tag`, `limit`, `cursor`                                                          |
+| `figura_get_fig`     | `id`                                                                                               |
+| `figura_comment`     | `fig_id`, `body`                                                                                   |
+
+Enum values:
+
+- `area`: `feed | profile | create | voices | capture | other | general`
+- `orientation`: `portrait | landscape | both`
+- `mode`: `single | compare | variations`
+
+Each tool returns its JSON result as a text content block; failures return
+`isError: true` with the server's error message.
+
+## Development
+
+```bash
+bun install
+bun run dev          # run from source with bun (MCP over stdio)
+bun run build        # bundle + minify src -> dist/index.js (single file)
+node dist/index.js   # speaks MCP over stdio
+```

package/dist/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{promises as _}from"node:fs";import{homedir as D}from"node:os";import{join as M}from"node:path";import U from"axios";import{McpServer as x}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as l}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as K}from"zod";var N="https://api.figura.so",m="mcp",n=M(D(),".figura","config.json");function I(){return(process.env.FIGURA_API_URL||N).replace(/\/+$/,"")}async function R(){if(process.env.FIGURA_TOKEN)return process.env.FIGURA_TOKEN;try{let B=await _.readFile(n,"utf8"),J=JSON.parse(B);if(J&&typeof J==="object"&&typeof J.token==="string")return J.token}catch{}return}async function W(B,J={}){let Q=await R();if(!Q)throw Error("No Figura token. Set FIGURA_TOKEN or run `figura login` to create ~/.figura/config.json.");let P=`${I()}${B.startsWith("/")?"":"/"}${B}`,C={Accept:"application/json",Authorization:`Bearer ${Q}`,"X-Figura-Source":m},L;if(J.body!==void 0)C["Content-Type"]="application/json",L=JSON.stringify(J.body);let $=await U.request({url:P,method:J.method??"GET",headers:C,data:L,validateStatus:()=>!0,transformRequest:[(w)=>w],transformResponse:[(w)=>w]}),H=typeof $.data==="string"?$.data:"",Z=void 0;if(H)try{Z=JSON.parse(H)}catch{Z=H}if($.status<200||$.status>=300){let w=Z&&typeof Z==="object"&&Z!==null&&"error"in Z?String(Z.error):typeof Z==="string"&&Z?Z:$.statusText||`HTTP ${$.status}`;throw Error(`${w} (HTTP ${$.status})`)}return Z}function X(B){return{content:[{type:"text",text:JSON.stringify(B,null,2)}]}}function Y(B){return{content:[{type:"text",text:B instanceof Error?B.message:String(B)}],isError:!0}}var G=["feed","profile","create","voices","capture","other","general"],j=["portrait","landscape","both"],q=["single","compare","variations"],V=new x({name:"figura",version:"0.1.0"});V.registerTool("figura_whoami",{title:"Figura: whoami",description:"Return the identity (team, actor, scopes) for the configured Figura token.",inputSchema:{}},async()=>{try{return X(await W("/v1/whoami"))}catch(B){return Y(B)}});V.registerTool("figura_create_fig",{title:"Figura: create fig",description:"Create a new visualization from an HTML document. Returns the created fig (id, slug); with publish:true it is published and the result includes a shareable public url.",inputSchema:{html:K.string().describe("The full HTML document for the visualization."),title:K.string().optional().describe("Title (otherwise derived from the HTML)."),description:K.string().optional(),area:K.enum(G).optional().describe("Product area the fig belongs to."),tags:K.array(K.string()).optional(),orientation:K.enum(j).optional(),mode:K.enum(q).optional(),model:K.string().optional().describe("Model attribution."),issue:K.number().optional().describe("Linked issue number."),publish:K.boolean().optional().describe("Publish to a shareable public URL on create (requires a paid plan).")}},async(B)=>{try{let J={html:B.html};for(let Q of["title","description","area","tags","orientation","mode","model","issue","publish"])if(B[Q]!==void 0)J[Q]=B[Q];return X(await W("/v1/figs",{method:"POST",body:J}))}catch(J){return Y(J)}});V.registerTool("figura_generate_fig",{title:"Figura: generate fig",description:"Generate a new fig server-side from a natural-language brief, then persist it. The engine runs Figura's on-brand generation — you do NOT write the HTML; just describe the screen. Returns the created fig (id, slug); publish:true publishes it with a shareable url. Requires an active paid subscription.",inputSchema:{prompt:K.string().describe("A natural-language brief describing the screen/UI to generate."),area:K.enum(G).optional().describe("Product area the fig belongs to."),orientation:K.enum(j).optional(),mode:K.enum(q).optional(),title:K.string().optional().describe("Title (otherwise derived from the generated HTML)."),fidelity:K.enum(["fast","high"]).optional().describe("Generation fidelity (default fast)."),publish:K.boolean().optional().describe("Publish to a shareable public URL on create (requires a paid plan).")}},async(B)=>{try{let J={prompt:B.prompt};for(let Q of["area","orientation","mode","title","fidelity","publish"])if(B[Q]!==void 0)J[Q]=B[Q];return X(await W("/v1/figs/generate",{method:"POST",body:J}))}catch(J){return Y(J)}});V.registerTool("figura_revise_fig",{title:"Figura: revise fig",description:"Create a new revision (version) of an existing fig from updated HTML. Returns the new fig (id, slug, version, rootFigId); publish:true publishes it with a shareable url. The new version joins the original fig's chain — it does not replace it in place.",inputSchema:{id:K.string().describe("The fig id to create a new revision of."),html:K.string().describe("The full updated HTML document."),title:K.string().optional().describe("Title (otherwise derived from the HTML)."),description:K.string().optional(),area:K.enum(G).optional().describe("Product area; inherited from the parent if omitted."),tags:K.array(K.string()).optional(),orientation:K.enum(j).optional().describe("Inherited from the parent if omitted."),mode:K.enum(q).optional(),model:K.string().optional().describe("Model attribution."),issue:K.number().optional().describe("Linked issue number."),publish:K.boolean().optional().describe("Publish the new revision to a shareable public URL (requires a paid plan).")}},async(B)=>{try{let J={html:B.html};for(let Q of["title","description","area","tags","orientation","mode","model","issue","publish"])if(B[Q]!==void 0)J[Q]=B[Q];return X(await W(`/v1/figs/${encodeURIComponent(B.id)}/revise`,{method:"POST",body:J}))}catch(J){return Y(J)}});V.registerTool("figura_list_revisions",{title:"Figura: list revisions",description:"List the full revision chain for a fig (all versions sharing a root), oldest to newest.",inputSchema:{id:K.string().describe("Any fig id in the chain.")}},async(B)=>{try{return X(await W(`/v1/figs/${encodeURIComponent(B.id)}/revisions`))}catch(J){return Y(J)}});V.registerTool("figura_publish_fig",{title:"Figura: publish fig",description:"Publish (or unpublish) an existing fig to its shareable public URL. Requires a paid plan. Returns { isPublic, url, publicId }.",inputSchema:{id:K.string().describe("The fig id to publish."),isPublic:K.boolean().optional().describe("Set false to unpublish (make private). Defaults to true (publish).")}},async(B)=>{try{let J={};if(B.isPublic!==void 0)J.isPublic=B.isPublic;return X(await W(`/v1/figs/${encodeURIComponent(B.id)}/publish`,{method:"POST",body:J}))}catch(J){return Y(J)}});V.registerTool("figura_list_figs",{title:"Figura: list figs",description:"List visualizations for the team, optionally filtered by area or tag.",inputSchema:{area:K.enum(G).optional(),tag:K.string().optional(),limit:K.number().optional(),cursor:K.string().optional()}},async(B)=>{try{let J=new URLSearchParams;if(B.area)J.set("area",B.area);if(B.tag)J.set("tag",B.tag);if(B.limit!==void 0)J.set("limit",String(B.limit));if(B.cursor)J.set("cursor",B.cursor);let Q=J.toString();return X(await W(`/v1/figs${Q?`?${Q}`:""}`))}catch(J){return Y(J)}});V.registerTool("figura_get_fig",{title:"Figura: get fig",description:"Fetch a single visualization by id.",inputSchema:{id:K.string().describe("The fig id.")}},async(B)=>{try{return X(await W(`/v1/figs/${encodeURIComponent(B.id)}`))}catch(J){return Y(J)}});V.registerTool("figura_comment",{title:"Figura: comment",description:"Add a comment to a visualization.",inputSchema:{fig_id:K.string().describe("The fig id to comment on."),body:K.string().describe("Comment text.")}},async(B)=>{try{return X(await W(`/v1/figs/${encodeURIComponent(B.fig_id)}/comments`,{method:"POST",body:{body:B.body}}))}catch(J){return Y(J)}});V.registerTool("figura_request_feedback",{title:"Figura: request feedback",description:"Ask a teammate to review a fig. Resolve `from` to a team member (by name or email); they get a notification (in-app, push, email) and the discussion happens in the fig's comment thread. Use this when the user says they want a specific person's feedback/eyes/review on a fig. Returns { ok, request: { to, status }, figUrl }.",inputSchema:{id:K.string().describe("The fig id to request feedback on."),from:K.string().describe("The teammate to ask, by name or email (resolved within the team)."),note:K.string().optional().describe("Optional message for them (e.g. what to look at).")}},async(B)=>{try{let J={from:B.from};if(B.note!==void 0)J.note=B.note;return X(await W(`/v1/figs/${encodeURIComponent(B.id)}/request-feedback`,{method:"POST",body:J}))}catch(J){return Y(J)}});V.registerTool("figura_list_sources",{title:"Figura: list sources",description:"List the company-brain source-spine connectors for the team, with event counts and last-synced times.",inputSchema:{}},async()=>{try{return X(await W("/v1/sources"))}catch(B){return Y(B)}});V.registerTool("figura_sync_source",{title:"Figura: sync source",description:"Ingest new events from a connected source into the spine. Returns { ingested, fetched, nextCursor }.",inputSchema:{id:K.string().describe("The source id to sync (from figura_list_sources).")}},async(B)=>{try{return X(await W(`/v1/sources/${encodeURIComponent(B.id)}/sync`,{method:"POST"}))}catch(J){return Y(J)}});V.registerTool("figura_update_fig",{title:"Figura: update fig",description:"Update a fig's metadata in place (title/description/area/tags/status) and optionally replace its HTML. Set status='archived' to soft-delete.",inputSchema:{id:K.string().describe("The fig id to update."),title:K.string().optional(),description:K.string().optional(),area:K.enum(G).optional(),tags:K.array(K.string()).optional().describe("Replaces the existing tags."),status:K.enum(["draft","published","archived"]).optional(),html:K.string().optional().describe("Replace the rendered HTML in place.")}},async(B)=>{try{let J={};if(B.title!==void 0)J.title=B.title;if(B.description!==void 0)J.description=B.description;if(B.area!==void 0)J.area=B.area;if(B.tags!==void 0)J.tags=B.tags;if(B.status!==void 0)J.status=B.status;if(B.html!==void 0)J.html=B.html;return X(await W(`/v1/figs/${encodeURIComponent(B.id)}`,{method:"PATCH",body:J}))}catch(J){return Y(J)}});V.registerTool("figura_delete_fig",{title:"Figura: delete fig",description:"Archive a fig (soft-delete; leaves the library, public link stops resolving) or permanently delete it with hard=true.",inputSchema:{id:K.string().describe("The fig id to delete."),hard:K.boolean().optional().describe("Permanently delete instead of archive.")}},async(B)=>{try{return X(await W(`/v1/figs/${encodeURIComponent(B.id)}${B.hard?"?hard=true":""}`,{method:"DELETE"}))}catch(J){return Y(J)}});await V.connect(new l);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "figura-mcp",
+  "version": "0.2.0",
+  "description": "Model Context Protocol server for the Figura visualization SaaS",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://figura.so",
+  "keywords": [
+    "figura",
+    "mcp",
+    "model-context-protocol",
+    "visualization",
+    "saas",
+    "claude"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "figura-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --target=node --minify --packages=external --outfile=dist/index.js",
+    "dev": "bun run src/index.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.7.9",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}