frameforge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arun
+
+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,75 @@
+# frameforge
+
+MCP server for generating UI mockups using Google Gemini image generation (Imagen / Nano Banana).
+
+Generates high-fidelity web UI mockup PNGs and returns them inline in Claude Code.
+
+## Install
+
+```bash
+npx -y frameforge
+```
+
+## Setup
+
+Add to `~/.claude/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "frameforge": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "frameforge"],
+      "env": {
+        "GEMINI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Local development
+
+```json
+{
+  "mcpServers": {
+    "frameforge": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/frameforge/dist/index.js"],
+      "env": {
+        "GEMINI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Tool: `generate_ui_preview`
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `prompt` | string | yes | — | Description of the UI to generate |
+| `component_name` | string | yes | — | Name used in the output filename |
+| `style_hints` | string | no | — | Style guidance (e.g. "dark mode", "mobile") |
+| `aspect_ratio` | string | no | "16:9" | Aspect ratio for the image |
+| `model` | string | no | "gemini-2.0-flash-exp" | Gemini model ID |
+| `output_dir` | string | no | "./previews" | Directory to save PNGs |
+
+## Example
+
+In Claude Code:
+
+> Generate a UI preview of a dashboard with a sidebar, header with search bar, and a grid of analytics cards showing revenue, users, and conversion metrics.
+
+The tool returns an inline image visible directly in the terminal, and saves the PNG to `./previews/`.
+
+## Requirements
+
+- Node.js 18+
+- `GEMINI_API_KEY` environment variable
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { GoogleGenAI, Modality } from "@google/genai";
+import { z } from "zod";
+import { writeFile, mkdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+const SYSTEM_PROMPT = `Generate a clean, high-fidelity web UI mockup. Use a modern SaaS design aesthetic: clean typography, ample whitespace, subtle shadows, professional color palette. Show the component as it would appear in a real web application. Do not include browser chrome or device frames unless explicitly asked.`;
+const apiKey = process.env.GEMINI_API_KEY;
+if (!apiKey) {
+    console.error("frameforge: GEMINI_API_KEY environment variable is required");
+    process.exit(1);
+}
+const ai = new GoogleGenAI({ apiKey });
+const server = new McpServer({
+    name: "frameforge",
+    version: "0.1.0",
+});
+server.registerTool("generate_ui_preview", {
+    title: "Generate UI Preview",
+    description: "Generate a high-fidelity UI mockup image using Google Gemini image generation. Returns an inline image and saves the PNG to disk.",
+    inputSchema: {
+        prompt: z.string().describe("Description of the UI component or page to generate"),
+        component_name: z.string().describe("Name for the component (used in the output filename)"),
+        style_hints: z
+            .string()
+            .optional()
+            .describe("Additional style guidance (e.g. 'dark mode', 'mobile layout', 'minimal')"),
+        aspect_ratio: z
+            .string()
+            .optional()
+            .default("16:9")
+            .describe("Aspect ratio for the generated image"),
+        model: z
+            .string()
+            .optional()
+            .default("gemini-2.0-flash-exp")
+            .describe("Gemini model to use for image generation"),
+        output_dir: z
+            .string()
+            .optional()
+            .default("./previews")
+            .describe("Directory to save the generated image"),
+    },
+}, async (args) => {
+    const { prompt, component_name, style_hints, aspect_ratio, model, output_dir } = args;
+    const fullPrompt = [
+        SYSTEM_PROMPT,
+        style_hints ? `Style hints: ${style_hints}` : "",
+        `Aspect ratio: ${aspect_ratio}`,
+        prompt,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    console.error(`frameforge: Generating "${component_name}" with model ${model}...`);
+    const response = await ai.models.generateContent({
+        model,
+        contents: fullPrompt,
+        config: {
+            responseModalities: [Modality.IMAGE, Modality.TEXT],
+        },
+    });
+    const parts = response.candidates?.[0]?.content?.parts;
+    if (!parts || parts.length === 0) {
+        return {
+            content: [{ type: "text", text: "Error: No content returned from Gemini." }],
+            isError: true,
+        };
+    }
+    const imagePart = parts.find((p) => p.inlineData?.mimeType?.startsWith("image/"));
+    if (!imagePart?.inlineData) {
+        const textParts = parts
+            .filter((p) => p.text)
+            .map((p) => p.text)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: No image generated. Model response:\n${textParts || "(empty)"}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const { data, mimeType } = imagePart.inlineData;
+    if (!data || !mimeType) {
+        return {
+            content: [{ type: "text", text: "Error: Image data is empty." }],
+            isError: true,
+        };
+    }
+    // Save to disk
+    const resolvedDir = resolve(output_dir);
+    await mkdir(resolvedDir, { recursive: true });
+    const timestamp = Date.now();
+    const filename = `${component_name}-${timestamp}.png`;
+    const filepath = join(resolvedDir, filename);
+    await writeFile(filepath, Buffer.from(data, "base64"));
+    console.error(`frameforge: Saved ${filepath}`);
+    return {
+        content: [
+            { type: "image", data, mimeType },
+            { type: "text", text: `Saved: ${filepath}` },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("frameforge: MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("frameforge: Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "frameforge",
+  "version": "0.1.0",
+  "description": "MCP server for generating UI mockups using Google Gemini image generation",
+  "type": "module",
+  "bin": {
+    "frameforge": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "gemini",
+    "ui-preview",
+    "image-generation",
+    "claude",
+    "mockup"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@google/genai": "^1.40.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}