@figviz/figviz-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Figviz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# Figviz MCP server
+
+Generate clear, **labeled science & math diagrams** (biology, chemistry, physics,
+K-12 math, lab setups, graphic organizers) straight from your AI assistant, via
+the [Figviz](https://figviz.com) API.
+
+Works with any [Model Context Protocol](https://modelcontextprotocol.io) client —
+Claude Desktop, Cursor, Cline, Windsurf, and more.
+
+## What it does
+
+Exposes one tool:
+
+- **`generate_diagram`** — describe a diagram in plain text and get back a hosted
+  image URL. Options: `quality` (`1k` / `2k` / `4k`) and `aspectRatio`
+  (e.g. `16:9`, `1:1`).
+
+Example prompts:
+
+- "labeled plant cell cross-section for 8th grade"
+- "convex lens ray diagram, object between F and 2F"
+- "acid–base titration setup for high school chemistry"
+- "KWL chart graphic organizer, blank"
+
+## Get an API key
+
+Create a free key (includes 3 credits) at **https://figviz.com/settings/api**.
+Figviz is pay-as-you-go — no subscription, credits never expire.
+
+## Install
+
+Run it with `npx` (no install needed):
+
+```bash
+FIGVIZ_API_KEY=fvk_xxx npx -y figviz-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "figviz": {
+      "command": "npx",
+      "args": ["-y", "figviz-mcp"],
+      "env": { "FIGVIZ_API_KEY": "fvk_xxx" }
+    }
+  }
+}
+```
+
+### Cursor / Cline / Windsurf
+
+Add the same server entry to your client's MCP config (`mcp.json` or the MCP
+settings UI):
+
+```json
+{
+  "mcpServers": {
+    "figviz": {
+      "command": "npx",
+      "args": ["-y", "figviz-mcp"],
+      "env": { "FIGVIZ_API_KEY": "fvk_xxx" }
+    }
+  }
+}
+```
+
+Then ask your assistant: *"Use figviz to generate a labeled animal cell diagram
+for 7th grade."*
+
+## Environment variables
+
+| Variable          | Required | Default              | Description                       |
+| ----------------- | -------- | -------------------- | --------------------------------- |
+| `FIGVIZ_API_KEY`  | yes      | —                    | Your `fvk_…` key from figviz.com  |
+| `FIGVIZ_API_BASE` | no       | `https://figviz.com` | Override the API host (advanced)  |
+
+## Credits & pricing
+
+Each diagram costs 1 credit (4k costs 1.5). Buy credit packs at
+https://figviz.com/pricing. The MCP shares the same balance as your Figviz
+account.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Figviz MCP server.
+ *
+ * Exposes a `generate_diagram` tool so MCP clients (Claude Desktop, Cursor,
+ * Cline, Windsurf, etc.) can generate labeled science & math diagrams from a
+ * text description via the Figviz public API.
+ *
+ * Auth: set FIGVIZ_API_KEY (get a free key with 3 credits at
+ * https://figviz.com/settings/api). Optional FIGVIZ_API_BASE overrides the host.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_BASE = (process.env.FIGVIZ_API_BASE ?? 'https://figviz.com').replace(/\/+$/, '');
+const API_KEY = process.env.FIGVIZ_API_KEY;
+const GET_KEY_URL = 'https://figviz.com/settings/api';
+const PRICING_URL = 'https://figviz.com/pricing';
+const server = new McpServer({ name: 'figviz', version: '0.1.0' });
+server.registerTool('generate_diagram', {
+    title: 'Generate a science or math diagram',
+    description: 'Generate a clear, labeled science or math diagram (biology, chemistry, physics, K-12 math, lab setups, graphic organizers) from a plain-text description using Figviz. Returns hosted image URL(s). Requires the FIGVIZ_API_KEY environment variable.',
+    inputSchema: {
+        prompt: z
+            .string()
+            .min(3)
+            .describe("What to draw, e.g. 'labeled plant cell cross-section for 8th grade' or 'convex lens ray diagram, object between F and 2F'"),
+        quality: z
+            .enum(['1k', '2k', '4k'])
+            .optional()
+            .describe('Resolution. 4k costs 1.5 credits; 1k/2k cost 1. Default 1k.'),
+        aspectRatio: z
+            .string()
+            .optional()
+            .describe("Aspect ratio, e.g. '16:9', '1:1', '4:3'. Omit for auto."),
+    },
+}, async ({ prompt, quality, aspectRatio }) => {
+    if (!API_KEY) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `FIGVIZ_API_KEY is not set. Get a free key (3 credits included) at ${GET_KEY_URL}, then set the FIGVIZ_API_KEY environment variable in your MCP client config.`,
+                },
+            ],
+        };
+    }
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/generate`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${API_KEY}`,
+            },
+            body: JSON.stringify({ prompt, quality, aspectRatio }),
+        });
+        const data = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const base = data?.error ?? `Request failed (HTTP ${res.status}).`;
+            let hint = '';
+            if (res.status === 402)
+                hint = ` Buy a credit pack at ${PRICING_URL}.`;
+            else if (res.status === 401)
+                hint = ` Check your FIGVIZ_API_KEY (get one at ${GET_KEY_URL}).`;
+            return {
+                isError: true,
+                content: [{ type: 'text', text: base + hint }],
+            };
+        }
+        const images = data?.images ?? [];
+        if (images.length === 0) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No image was generated. Try rephrasing the prompt with a clearer subject and grade level.',
+                    },
+                ],
+            };
+        }
+        const body = images
+            .map((img) => `![${img.prompt}](${img.url})\n${img.url}`)
+            .join('\n\n');
+        const credits = typeof data?.credits_remaining === 'number'
+            ? `\n\nCredits remaining: ${data.credits_remaining}`
+            : '';
+        return {
+            content: [{ type: 'text', text: `${body}${credits}` }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Network error contacting Figviz: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Logs go to stderr so they don't corrupt the stdio JSON-RPC stream.
+    console.error('Figviz MCP server running on stdio');
+}
+main().catch((err) => {
+    console.error('Fatal error starting Figviz MCP server:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@figviz/figviz-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Figviz — generate labeled science & math diagrams (biology, chemistry, physics, K-12 math) from text via the Figviz API.",
+  "type": "module",
+  "bin": {
+    "figviz-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "figviz",
+    "diagram",
+    "diagram-generator",
+    "science",
+    "education",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "author": "Figviz <support@figviz.com>",
+  "homepage": "https://figviz.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jyjyxt/figviz-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jyjyxt/figviz-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}