figura-mcp 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{existsSync as T,promises as N,readFileSync as I}from"node:fs";import{homedir as P}from"node:os";import{dirname as j,join as U}from"node:path";import S from"axios";import{McpServer as m}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as O}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as Q}from"zod";var l="https://api.figura.so",F="mcp",R=U(P(),".figura","config.json"),u=U(".figura","config.json");async function C(B){try{let K=JSON.parse(await N.readFile(B,"utf8"));if(K&&typeof K==="object")return K}catch{}return{}}async function b(B=process.cwd()){let K=P(),W=B;for(;;){if(W!==K){let J=U(W,u);try{return await N.access(J),J}catch{}}let q=j(W);if(q===W)return null;W=q}}function f(B=process.cwd()){let K=B;for(;;){if(T(U(K,".git")))return!0;let W=j(K);if(W===K)return!1;K=W}}async function E(){let B=await b(),K=B?await C(B):{},W=await C(R),q={...W,...K},J=process.env.FIGURA_TOKEN||q.token||void 0,L=process.env.FIGURA_TOKEN?"env":K.token?"project":W.token?"global":"none",G=(process.env.FIGURA_API_URL||q.apiUrl||l).replace(/\/+$/,"");return{token:J,apiUrl:G,team:q.team,source:L,configPath:L==="project"?B:L==="global"?R:null}}async function Y(B,K={}){let W=await E(),q=W.token;if(!q)throw Error("No Figura token. Run `figura link` in this repo (or `figura login`, or set FIGURA_TOKEN).");if((K.method??"GET").toUpperCase()!=="GET"&&W.source==="global"&&f()&&process.env.FIGURA_ALLOW_GLOBAL!=="1")throw Error(`this project isn't linked to a Figura team — the global credential${W.team?` (team '${W.team}')`:""} would receive this write. Ask the user to run \`figura link\` in this repo (or set FIGURA_ALLOW_GLOBAL=1 to use the global team deliberately).`);let L=`${W.apiUrl}${B.startsWith("/")?"":"/"}${B}`,G={Accept:"application/json",Authorization:`Bearer ${q}`,"X-Figura-Source":F},A;if(K.body!==void 0)G["Content-Type"]="application/json",A=JSON.stringify(K.body);let H=await S.request({url:L,method:K.method??"GET",headers:G,data:A,validateStatus:()=>!0,transformRequest:[(D)=>D],transformResponse:[(D)=>D]}),x=typeof H.data==="string"?H.data:"",V=void 0;if(x)try{V=JSON.parse(x)}catch{V=x}if(H.status<200||H.status>=300){let D=V&&typeof V==="object"&&V!==null&&"error"in V?String(V.error):typeof V==="string"&&V?V:H.statusText||`HTTP ${H.status}`;throw Error(`${D} (HTTP ${H.status})`)}return V}function Z(B){return{content:[{type:"text",text:JSON.stringify(B,null,2)}]}}function $(B){return{content:[{type:"text",text:B instanceof Error?B.message:String(B)}],isError:!0}}var w=()=>Q.string().optional().describe("Product area / surface the fig belongs to, e.g. 'dashboard', 'settings', 'onboarding'. Free text."),M=["portrait","landscape","both"],_=["single","compare","variations"],v=(()=>{try{let B=JSON.parse(I(new URL("../package.json",import.meta.url),"utf8"));return typeof B.version==="string"?B.version:"0.0.0"}catch{return"0.0.0"}})(),X=new m({name:"figura",version:v});X.registerTool("figura_whoami",{title:"Figura: whoami",description:"Return the identity (team, actor, scopes) for the configured Figura token, plus `binding` — which config tier supplied it (env | project | global). A `global` binding means this project is not linked to a team and writes will be refused; ask the user to run `figura link` in the repo.",inputSchema:{}},async()=>{try{let B=await Y("/v1/whoami"),{source:K,configPath:W}=await E();return Z({...B,binding:{source:K,configPath:W}})}catch(B){return $(B)}});X.registerTool("figura_set_brand",{title:"Figura: set brand profile",description:'Set (upsert) the team brand profile that the fig generator renders against. Use this to "introduce a repo to Figura": scan the codebase for its design system, synthesize the brand, then push it here. `name` is required; `appDescription` is a one-clause product summary; `tokensBlock` is the freeform design-token reference (colors + hex + role, type scale + faces, spacing, the brand gradient, plus voice/conventions). This is a partial merge — fields you omit keep their saved value (pass an explicit empty string to clear one), so a name-only update will not wipe existing tokens. Editing the team brand — confirm with the user before calling.',inputSchema:{name:Q.string().describe("Brand / app name (required)."),appDescription:Q.string().optional().describe("One clause on what the product is + who it is for."),tokensBlock:Q.string().optional().describe("Freeform plain-text design-token reference: colors (hex + role), type scale + faces, spacing, the brand gradient, and voice/conventions. Injected verbatim into the fig-generation prompt.")}},async(B)=>{try{let K={name:B.name};if(B.appDescription!==void 0)K.appDescription=B.appDescription;if(B.tokensBlock!==void 0)K.tokensBlock=B.tokensBlock;return Z(await Y("/brand",{method:"PUT",body:K}))}catch(K){return $(K)}});X.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:Q.string().describe("The full HTML document for the visualization."),title:Q.string().optional().describe("Title (otherwise derived from the HTML)."),description:Q.string().optional(),area:w(),tags:Q.array(Q.string()).optional(),orientation:Q.enum(M).optional(),mode:Q.enum(_).optional(),model:Q.string().optional().describe("Model attribution."),issue:Q.number().optional().describe("Linked issue number."),publish:Q.boolean().optional().describe("Publish to a shareable public URL on create (requires a paid plan).")}},async(B)=>{try{let K={html:B.html};for(let W of["title","description","area","tags","orientation","mode","model","issue","publish"])if(B[W]!==void 0)K[W]=B[W];return Z(await Y("/v1/figs",{method:"POST",body:K}))}catch(K){return $(K)}});X.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:Q.string().describe("A natural-language brief describing the screen/UI to generate."),area:w(),orientation:Q.enum(M).optional(),mode:Q.enum(_).optional(),title:Q.string().optional().describe("Title (otherwise derived from the generated HTML)."),fidelity:Q.enum(["fast","high"]).optional().describe("Generation fidelity (default fast)."),publish:Q.boolean().optional().describe("Publish to a shareable public URL on create (requires a paid plan).")}},async(B)=>{try{let K={prompt:B.prompt};for(let W of["area","orientation","mode","title","fidelity","publish"])if(B[W]!==void 0)K[W]=B[W];return Z(await Y("/v1/figs/generate",{method:"POST",body:K}))}catch(K){return $(K)}});X.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:Q.string().describe("The fig id to create a new revision of."),html:Q.string().describe("The full updated HTML document."),title:Q.string().optional().describe("Title (otherwise derived from the HTML)."),description:Q.string().optional(),area:Q.string().optional().describe("Product area / surface; free text. Inherited from the parent if omitted."),tags:Q.array(Q.string()).optional(),orientation:Q.enum(M).optional().describe("Inherited from the parent if omitted."),mode:Q.enum(_).optional(),model:Q.string().optional().describe("Model attribution."),issue:Q.number().optional().describe("Linked issue number."),publish:Q.boolean().optional().describe("Publish the new revision to a shareable public URL (requires a paid plan).")}},async(B)=>{try{let K={html:B.html};for(let W of["title","description","area","tags","orientation","mode","model","issue","publish"])if(B[W]!==void 0)K[W]=B[W];return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}/revise`,{method:"POST",body:K}))}catch(K){return $(K)}});X.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:Q.string().describe("Any fig id in the chain.")}},async(B)=>{try{return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}/revisions`))}catch(K){return $(K)}});X.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:Q.string().describe("The fig id to publish."),isPublic:Q.boolean().optional().describe("Set false to unpublish (make private). Defaults to true (publish).")}},async(B)=>{try{let K={};if(B.isPublic!==void 0)K.isPublic=B.isPublic;return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}/publish`,{method:"POST",body:K}))}catch(K){return $(K)}});X.registerTool("figura_list_figs",{title:"Figura: list figs",description:"List visualizations for the team, optionally filtered by area or tag.",inputSchema:{area:w(),tag:Q.string().optional(),limit:Q.number().optional(),cursor:Q.string().optional()}},async(B)=>{try{let K=new URLSearchParams;if(B.area)K.set("area",B.area);if(B.tag)K.set("tag",B.tag);if(B.limit!==void 0)K.set("limit",String(B.limit));if(B.cursor)K.set("cursor",B.cursor);let W=K.toString();return Z(await Y(`/v1/figs${W?`?${W}`:""}`))}catch(K){return $(K)}});X.registerTool("figura_get_fig",{title:"Figura: get fig",description:"Fetch a single visualization by id.",inputSchema:{id:Q.string().describe("The fig id.")}},async(B)=>{try{return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}`))}catch(K){return $(K)}});X.registerTool("figura_comment",{title:"Figura: comment",description:"Add a comment to a visualization.",inputSchema:{fig_id:Q.string().describe("The fig id to comment on."),body:Q.string().describe("Comment text.")}},async(B)=>{try{return Z(await Y(`/v1/figs/${encodeURIComponent(B.fig_id)}/comments`,{method:"POST",body:{body:B.body}}))}catch(K){return $(K)}});X.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:Q.string().describe("The fig id to request feedback on."),from:Q.string().describe("The teammate to ask, by name or email (resolved within the team)."),note:Q.string().optional().describe("Optional message for them (e.g. what to look at).")}},async(B)=>{try{let K={from:B.from};if(B.note!==void 0)K.note=B.note;return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}/request-feedback`,{method:"POST",body:K}))}catch(K){return $(K)}});X.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 Z(await Y("/v1/sources"))}catch(B){return $(B)}});X.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:Q.string().describe("The source id to sync (from figura_list_sources).")}},async(B)=>{try{return Z(await Y(`/v1/sources/${encodeURIComponent(B.id)}/sync`,{method:"POST"}))}catch(K){return $(K)}});X.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:Q.string().describe("The fig id to update."),title:Q.string().optional(),description:Q.string().optional(),area:w(),tags:Q.array(Q.string()).optional().describe("Replaces the existing tags."),status:Q.enum(["draft","published","archived"]).optional(),html:Q.string().optional().describe("Replace the rendered HTML in place.")}},async(B)=>{try{let K={};if(B.title!==void 0)K.title=B.title;if(B.description!==void 0)K.description=B.description;if(B.area!==void 0)K.area=B.area;if(B.tags!==void 0)K.tags=B.tags;if(B.status!==void 0)K.status=B.status;if(B.html!==void 0)K.html=B.html;return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}`,{method:"PATCH",body:K}))}catch(K){return $(K)}});X.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:Q.string().describe("The fig id to delete."),hard:Q.boolean().optional().describe("Permanently delete instead of archive.")}},async(B)=>{try{return Z(await Y(`/v1/figs/${encodeURIComponent(B.id)}${B.hard?"?hard=true":""}`,{method:"DELETE"}))}catch(K){return $(K)}});await X.connect(new O);
+import{existsSync as m,promises as U,readFileSync as y}from"node:fs";import{homedir as E}from"node:os";import{dirname as I,join as N}from"node:path";import _ from"axios";import{McpServer as h}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as n}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as W}from"zod";var l="https://api.figura.so",z="mcp",A=N(E(),".figura","config.json"),u=N(".figura","config.json");async function F(K){try{let Q=JSON.parse(await U.readFile(K,"utf8"));if(Q&&typeof Q==="object")return Q}catch{}return{}}async function p(K=process.cwd()){let Q=E(),Z=K;for(;;){if(Z!==Q){let q=N(Z,u);try{return await U.access(q),q}catch{}}let $=I(Z);if($===Z)return null;Z=$}}function i(K=process.cwd()){let Q=K;for(;;){if(m(N(Q,".git")))return!0;let Z=I(Q);if(Z===Q)return!1;Q=Z}}async function f(){let K=await p(),Q=K?await F(K):{},Z=await F(A),$={...Z,...Q},q=process.env.FIGURA_TOKEN||$.token||void 0,G=process.env.FIGURA_TOKEN?"env":Q.token?"project":Z.token?"global":"none",w=(process.env.FIGURA_API_URL||$.apiUrl||l).replace(/\/+$/,"");return{token:q,apiUrl:w,team:$.team,source:G,configPath:G==="project"?K:G==="global"?A:null}}async function H(K,Q={}){let Z=await f(),$=Z.token;if(!$)throw Error("No Figura token. Run `figura link` in this repo (or `figura login`, or set FIGURA_TOKEN).");if((Q.method??"GET").toUpperCase()!=="GET"&&Z.source==="global"&&i()&&process.env.FIGURA_ALLOW_GLOBAL!=="1")throw Error(`this project isn't linked to a Figura team — the global credential${Z.team?` (team '${Z.team}')`:""} would receive this write. Ask the user to run \`figura link\` in this repo (or set FIGURA_ALLOW_GLOBAL=1 to use the global team deliberately).`);let G=`${Z.apiUrl}${K.startsWith("/")?"":"/"}${K}`,w={Accept:"application/json",Authorization:`Bearer ${$}`,"X-Figura-Source":z},R;if(Q.body!==void 0)w["Content-Type"]="application/json",R=JSON.stringify(Q.body);let B=await _.request({url:G,method:Q.method??"GET",headers:w,data:R,validateStatus:()=>!0,transformRequest:[(J)=>J],transformResponse:[(J)=>J]}),C=typeof B.data==="string"?B.data:"",Y=void 0;if(C)try{Y=JSON.parse(C)}catch{Y=C}if(B.status<200||B.status>=300){let J=Y&&typeof Y==="object"&&Y!==null&&"error"in Y?String(Y.error):typeof Y==="string"&&Y?Y:B.statusText||`HTTP ${B.status}`;throw Error(`${J} (HTTP ${B.status})`)}return Y}var v=2500,c=600000,d=60000,j=(K)=>new Promise((Q)=>setTimeout(Q,K));async function t(K){let Q=Date.now(),Z=null;for(;;){let $;try{$=await H(`/v1/jobs/${encodeURIComponent(K)}`),Z=null}catch(q){if(Z??=Date.now(),Date.now()-Z>=d){let G=q instanceof Error?q.message:String(q);throw Error(`Lost contact with the Figura API while waiting for job ${K} (${G}). `+`The job may still complete — resume by checking GET /v1/jobs/${K} instead of regenerating.`)}await j(v);continue}if($.status==="done")return $;if($.status==="error")throw Error($.error||"The generation job failed. Please retry.");if(Date.now()-Q>c)throw Error(`Timed out waiting for job ${K} — it may still complete; `+`check GET /v1/jobs/${K} instead of regenerating.`);await j(v)}}function V(K){return{content:[{type:"text",text:JSON.stringify(K,null,2)}]}}function X(K){return{content:[{type:"text",text:K instanceof Error?K.message:String(K)}],isError:!0}}var x=()=>W.string().optional().describe("Product area / surface the fig belongs to, e.g. 'dashboard', 'settings', 'onboarding'. Free text."),M=["portrait","landscape","both"],P=["single","compare","variations"],g=(()=>{try{let K=JSON.parse(y(new URL("../package.json",import.meta.url),"utf8"));return typeof K.version==="string"?K.version:"0.0.0"}catch{return"0.0.0"}})(),D=new h({name:"figura",version:g});D.registerTool("figura_whoami",{title:"Figura: whoami",description:"Return the identity (team, actor, scopes) for the configured Figura token, plus `binding` — which config tier supplied it (env | project | global). A `global` binding means this project is not linked to a team and writes will be refused; ask the user to run `figura link` in the repo.",inputSchema:{}},async()=>{try{let K=await H("/v1/whoami"),{source:Q,configPath:Z}=await f();return V({...K,binding:{source:Q,configPath:Z}})}catch(K){return X(K)}});D.registerTool("figura_set_brand",{title:"Figura: set brand profile",description:'Set (upsert) the team brand profile that the fig generator renders against. Use this to "introduce a repo to Figura": scan the codebase for its design system, synthesize the brand, then push it here. `name` is required; `appDescription` is a one-clause product summary; `tokensBlock` is the freeform design-token reference (colors + hex + role, type scale + faces, spacing, the brand gradient, plus voice/conventions). This is a partial merge — fields you omit keep their saved value (pass an explicit empty string to clear one), so a name-only update will not wipe existing tokens. Editing the team brand — confirm with the user before calling.',inputSchema:{name:W.string().describe("Brand / app name (required)."),appDescription:W.string().optional().describe("One clause on what the product is + who it is for."),tokensBlock:W.string().optional().describe("Freeform plain-text design-token reference: colors (hex + role), type scale + faces, spacing, the brand gradient, and voice/conventions. Injected verbatim into the fig-generation prompt.")}},async(K)=>{try{let Q={name:K.name};if(K.appDescription!==void 0)Q.appDescription=K.appDescription;if(K.tokensBlock!==void 0)Q.tokensBlock=K.tokensBlock;return V(await H("/brand",{method:"PUT",body:Q}))}catch(Q){return X(Q)}});var o={png:"image/png",jpg:"image/jpeg",jpeg:"image/jpeg",gif:"image/gif",webp:"image/webp",avif:"image/avif",svg:"image/svg+xml"},L=5242880;function O(K){let Q=K.split(/[?#]/)[0].split(".").pop()?.toLowerCase()??"";return o[Q]}async function k(K,Q){let Z,$=Q;if(/^https?:\/\//i.test(K)){let q=await _.get(K,{responseType:"arraybuffer",maxContentLength:L,timeout:30000});if(Z=Buffer.from(q.data).toString("base64"),!$){let G=String(q.headers["content-type"]??"").split(";")[0].trim().toLowerCase();$=G.startsWith("image/")?G:O(K)}}else{let{size:q}=await U.stat(K);if(q>L)throw Error(`'${K}' is ${(q/1048576).toFixed(1)}MB — over the ${L/1048576}MB asset limit.`);if(Z=(await U.readFile(K)).toString("base64"),!$)$=O(K)}if(!$)throw Error(`Could not determine an image content-type for '${K}' — pass contentType (e.g. image/png).`);return{data:Z,contentType:$}}async function a(K,Q){let{data:Z,contentType:$}=await k(K,Q),q=await H("/v1/assets",{method:"POST",body:{data:Z,contentType:$}});if(!q||typeof q.url!=="string")throw Error("Asset upload did not return a URL.");return q.url}var S=()=>W.array(W.object({source:W.string().describe("The image — a local file path or an http(s) URL (e.g. a screenshot)."),match:W.string().optional().describe('Exact string in the HTML to replace with the hosted URL (defaults to `source` — i.e. write <img src="<source>"> in the HTML).')})).optional().describe("Images to attach: each is uploaded to durable figura hosting (stable non-expiring URL, allowed by the fig CSP) and substituted into the HTML in place of `match`/`source`. Use for real screenshots/photos/logos instead of base64 data-URIs (HTML size cap) or external URLs (expire/CSP-blocked).");async function T(K,Q){if(!Q?.length)return{html:K,uploaded:[]};let Z=K,$=[];for(let q of Q){let G=q.match??q.source;if(!Z.includes(G))throw Error(`images: '${G}' does not occur in the html — reference it (e.g. <img src="${G}">) so it can be swapped for the hosted URL, or set 'match'.`);let w=await a(q.source);Z=Z.split(G).join(w),$.push({source:q.source,url:w})}return{html:Z,uploaded:$}}function b(K,Q){if(!Q.length)return K;if(K&&typeof K==="object"&&!Array.isArray(K))return{...K,assets:Q};return{result:K,assets:Q}}D.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. To include REAL images (screenshots/photos/logos), pass them via `images` — they are uploaded to durable figura hosting and their stable URLs substituted into the HTML. TIP — injected components: if your HTML shows phone frames (a compare/multi-screen mock), wrap each state in <div class="fig-device portrait|landscape"><div class="fig-screen">…</div><div class="fig-di"></div><div class="fig-homebar"></div></div> and do NOT style those classes — Figura injects accurate iPhone frame CSS at save. Same for an iOS status bar (<div class="fig-statusbar" data-time="9:41"></div>), a compare control bar (.fig-controls/.fig-seg), and the .frame-web browser window.',inputSchema:{html:W.string().describe("The full HTML document for the visualization."),images:S(),title:W.string().optional().describe("Title (otherwise derived from the HTML)."),description:W.string().optional(),area:x(),tags:W.array(W.string()).optional(),orientation:W.enum(M).optional(),mode:W.enum(P).optional(),model:W.string().optional().describe("Model attribution."),device:W.string().optional().describe("Catalog iPhone id the fig targets (e.g. 'iphone-16', 'iphone-17-pro', 'iphone-se-3') — keys the injected frame/safe-area geometry."),issue:W.number().optional().describe("Linked issue number."),publish:W.boolean().optional().describe("Publish to a shareable public URL on create (requires a paid plan).")}},async(K)=>{try{let{html:Q,uploaded:Z}=await T(K.html,K.images),$={html:Q};for(let q of["title","description","area","tags","orientation","mode","model","device","issue","publish"])if(K[q]!==void 0)$[q]=K[q];return V(b(await H("/v1/figs",{method:"POST",body:$}),Z))}catch(Q){return X(Q)}});D.registerTool("figura_upload_asset",{title:"Figura: upload asset",description:"Upload a durable image asset and get back a STABLE, figura-hosted URL that never expires — use it in a fig's <img src> instead of a base64 data-URI (bloats the HTML past the publish size) or an external URL that expires (Instagram/CDN signed links). The fig CSP allows figura-hosted images. Provide `path` (a local image file), `url` (an http(s) image to fetch and re-host), or `data` (base64 bytes) + `contentType`. Accepts png/jpeg/gif/webp/avif/svg, up to 5MB. Returns `{ url }`.",inputSchema:{path:W.string().optional().describe("Local path to an image file to upload (content-type inferred from the extension)."),url:W.string().optional().describe("http(s) URL of an image to fetch and re-host (alternative to `path`) — use for expiring/signed source URLs so the fig keeps rendering after they die."),data:W.string().optional().describe("Base64-encoded image bytes (alternative to `path`/`url`). Requires `contentType`."),contentType:W.string().optional().describe("MIME type, e.g. image/png. Required with `data`; inferred from the extension/response for `path`/`url`.")}},async(K)=>{try{let Q=K.path??K.url;if(Q){let{data:Z,contentType:$}=await k(Q,K.contentType);return V(await H("/v1/assets",{method:"POST",body:{data:Z,contentType:$}}))}if(!K.data)throw Error("Provide `path` (a local image file), `url` (an http(s) image), or `data` (base64 bytes).");if(!K.contentType)throw Error("`contentType` is required with `data` — e.g. image/png.");return V(await H("/v1/assets",{method:"POST",body:{data:K.data,contentType:K.contentType}}))}catch(Q){return X(Q)}});D.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. SPENDS TEAM CREDITS: only use when the user explicitly opts for a server render; otherwise default to writing the HTML yourself and landing it with figura_create_fig (free, uses the calling model). Runs as an async server job; this call polls until the fig lands (typically 30–90s). Returns the created fig (id, slug); publish:true publishes it with a shareable url. Requires an active paid subscription.",inputSchema:{prompt:W.string().describe("A natural-language brief describing the screen/UI to generate."),area:x(),orientation:W.enum(M).optional(),mode:W.enum(P).optional(),platform:W.enum(["mobile","web"]).optional().describe("Output platform: 'mobile' (iPhone, default) or 'web' (browser frame)."),device:W.string().optional().describe("Catalog iPhone id to target (e.g. 'iphone-16', 'iphone-17-pro', 'iphone-se-3'). Mobile only; default iphone-16."),title:W.string().optional().describe("Title (otherwise derived from the generated HTML)."),fidelity:W.enum(["fast","high"]).optional().describe("Generation fidelity (default fast)."),publish:W.boolean().optional().describe("Publish to a shareable public URL on create (requires a paid plan).")}},async(K)=>{try{let Q={prompt:K.prompt};for(let $ of["area","orientation","mode","platform","device","title","publish"])if(K[$]!==void 0)Q[$]=K[$];if(K.fidelity!==void 0)Q.model=K.fidelity;Q.async=!0;let Z=await H("/v1/figs/generate",{method:"POST",body:Q});if(Z&&typeof Z==="object"&&typeof Z.jobId==="string"){let $=await t(Z.jobId),q=$.result??{};return V(q.fig??$.result)}return V(Z)}catch(Q){return X(Q)}});D.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); publish:true publishes it with a shareable url. The new version joins the original fig's chain — it does not replace it in place. Use list_revisions for the chain (rootFig + every version). To include REAL images (screenshots/photos/logos), pass them via `images` — uploaded to durable figura hosting, stable URLs substituted into the HTML.",inputSchema:{id:W.string().describe("The fig to revise — its id (`fig_…`), a UUID, a share link/URL, or its publicId."),html:W.string().describe("The full updated HTML document."),images:S(),title:W.string().optional().describe("Title (otherwise derived from the HTML)."),description:W.string().optional(),area:W.string().optional().describe("Product area / surface; free text. Inherited from the parent if omitted."),tags:W.array(W.string()).optional(),orientation:W.enum(M).optional().describe("Inherited from the parent if omitted."),mode:W.enum(P).optional(),model:W.string().optional().describe("Model attribution."),issue:W.number().optional().describe("Linked issue number."),publish:W.boolean().optional().describe("Publish the new revision to a shareable public URL (requires a paid plan).")}},async(K)=>{try{let{html:Q,uploaded:Z}=await T(K.html,K.images),$={html:Q};for(let q of["title","description","area","tags","orientation","mode","model","issue","publish"])if(K[q]!==void 0)$[q]=K[q];return V(b(await H(`/v1/figs/${encodeURIComponent(K.id)}/revise`,{method:"POST",body:$}),Z))}catch(Q){return X(Q)}});D.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:W.string().describe("Any fig in the chain — its id (`fig_…`), a UUID, share link/URL, or publicId.")}},async(K)=>{try{return V(await H(`/v1/figs/${encodeURIComponent(K.id)}/revisions`))}catch(Q){return X(Q)}});D.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:W.string().describe("The fig to publish — its id (`fig_…`), a UUID, a share link/URL, or its publicId."),isPublic:W.boolean().optional().describe("Set false to unpublish (make private). Defaults to true (publish).")}},async(K)=>{try{let Q={};if(K.isPublic!==void 0)Q.isPublic=K.isPublic;return V(await H(`/v1/figs/${encodeURIComponent(K.id)}/publish`,{method:"POST",body:Q}))}catch(Q){return X(Q)}});D.registerTool("figura_list_figs",{title:"Figura: list figs",description:"List visualizations for the team, optionally filtered by area or tag.",inputSchema:{area:x(),tag:W.string().optional(),limit:W.number().optional(),cursor:W.string().optional()}},async(K)=>{try{let Q=new URLSearchParams;if(K.area)Q.set("area",K.area);if(K.tag)Q.set("tag",K.tag);if(K.limit!==void 0)Q.set("limit",String(K.limit));if(K.cursor)Q.set("cursor",K.cursor);let Z=Q.toString();return V(await H(`/v1/figs${Z?`?${Z}`:""}`))}catch(Q){return X(Q)}});D.registerTool("figura_get_fig",{title:"Figura: get fig",description:"Fetch a single visualization by id.",inputSchema:{id:W.string().describe("The fig — its id (`fig_…`), a UUID, a share link/URL, or its publicId.")}},async(K)=>{try{return V(await H(`/v1/figs/${encodeURIComponent(K.id)}`))}catch(Q){return X(Q)}});D.registerTool("figura_comment",{title:"Figura: comment",description:"Add a comment to a visualization.",inputSchema:{fig_id:W.string().describe("The fig to comment on — its id (`fig_…`), a UUID, a share link/URL, or its publicId."),body:W.string().describe("Comment text.")}},async(K)=>{try{return V(await H(`/v1/figs/${encodeURIComponent(K.fig_id)}/comments`,{method:"POST",body:{body:K.body}}))}catch(Q){return X(Q)}});D.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:W.string().describe("The fig to request feedback on — its id (`fig_…`), a UUID, a share link/URL, or its publicId."),from:W.string().describe("The teammate to ask, by name or email (resolved within the team)."),note:W.string().optional().describe("Optional message for them (e.g. what to look at).")}},async(K)=>{try{let Q={from:K.from};if(K.note!==void 0)Q.note=K.note;return V(await H(`/v1/figs/${encodeURIComponent(K.id)}/request-feedback`,{method:"POST",body:Q}))}catch(Q){return X(Q)}});D.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 V(await H("/v1/sources"))}catch(K){return X(K)}});D.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:W.string().describe("The source id to sync (from figura_list_sources).")}},async(K)=>{try{return V(await H(`/v1/sources/${encodeURIComponent(K.id)}/sync`,{method:"POST"}))}catch(Q){return X(Q)}});D.registerTool("figura_update_fig",{title:"Figura: update fig",description:"Update a fig's METADATA only (title/description/area/tags/status). Set status='archived' to soft-delete. To change the fig's HTML, use figura_revise_fig — it saves a new version and never destroys the old one. update cannot touch the HTML.",inputSchema:{id:W.string().describe("The fig to update — its id (`fig_…`), a UUID, a share link/URL, or its publicId."),title:W.string().optional(),description:W.string().optional(),area:x(),tags:W.array(W.string()).optional().describe("Replaces the existing tags."),status:W.enum(["draft","published","archived"]).optional()}},async(K)=>{try{let Q={};if(K.title!==void 0)Q.title=K.title;if(K.description!==void 0)Q.description=K.description;if(K.area!==void 0)Q.area=K.area;if(K.tags!==void 0)Q.tags=K.tags;if(K.status!==void 0)Q.status=K.status;return V(await H(`/v1/figs/${encodeURIComponent(K.id)}`,{method:"PATCH",body:Q}))}catch(Q){return X(Q)}});D.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:W.string().describe("The fig to delete — its id (`fig_…`), a UUID, a share link/URL, or its publicId."),hard:W.boolean().optional().describe("Permanently delete instead of archive.")}},async(K)=>{try{return V(await H(`/v1/figs/${encodeURIComponent(K.id)}${K.hard?"?hard=true":""}`,{method:"DELETE"}))}catch(Q){return X(Q)}});await D.connect(new n);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Model Context Protocol server for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",