meltflex-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MeltFlex
+
+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,71 @@
+# meltflex-mcp
+
+MeltFlex AI as an **MCP server + CLI** — generate photorealistic interior-design redesigns directly from your AI agent (Claude Code, Cursor, Codex, and any MCP-compatible client).
+
+Each user connects **their own** MeltFlex account; every generation is billed to that account's credits. The server is a thin client over the public MeltFlex API — it enforces nothing itself, so credits and access are always governed server-side.
+
+## Install & authenticate
+
+```bash
+# Authenticate once (stored in ~/.meltflex/config.json, chmod 600)
+npx -y meltflex-mcp auth mf_sk_xxxxxxxxxxxx
+npx -y meltflex-mcp whoami
+```
+
+Get an API key at <https://www.meltflexai.com/settings> (Growth plan or higher).
+Alternatively, skip `auth` and provide `MELTFLEX_API_KEY` via the client's `env` block (below).
+
+## Add to Claude Code
+
+```bash
+claude mcp add meltflex -- npx -y meltflex-mcp
+```
+
+…or add it to your MCP config (`.mcp.json` / client settings):
+
+```json
+{
+  "mcpServers": {
+    "meltflex": {
+      "command": "npx",
+      "args": ["-y", "meltflex-mcp"],
+      "env": { "MELTFLEX_API_KEY": "mf_sk_xxxxxxxxxxxx" }
+    }
+  }
+}
+```
+
+Cursor / Codex / other MCP clients use the same `command` + `args` + `env` shape.
+
+## Tools
+
+| Tool | What it does | Cost |
+|------|--------------|------|
+| `generate_interior` | Restyle a room photo into a photorealistic redesign. Inputs: `prompt`, `image` (path/URL/data-URL), optional `reference_images`, optional `output_path`. Saves the result to disk. | 10 credits |
+| `check_credits` | Report the account's credit balance and per-operation costs. | free |
+
+## Config / environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MELTFLEX_API_KEY` | — | API key (`mf_sk_...`). Overrides the config file. |
+| `MELTFLEX_BASE_URL` | `https://www.meltflexai.com` | Override for staging/self-host. |
+
+## Local development
+
+```bash
+npm install
+npm run build
+node dist/cli.js whoami          # sanity check the CLI
+node dist/cli.js                 # run the MCP server on stdio
+```
+
+## Architecture
+
+```
+your agent ──stdio/MCP──► meltflex-mcp ──HTTPS Bearer mf_sk_──► api.meltflexai.com
+                                                                 /api/v1/generate
+                                                                 /api/v1/credits
+```
+
+The MCP layer adds **no** new attack surface: anything it can do is already doable with a `curl` against the same API using the same key. Credit enforcement, refunds, and rate limits all live in the MeltFlex backend.

package/dist/api.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { loadConfig } from './config.js';
+const EXT_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    gif: 'image/gif',
+};
+/**
+ * Normalize any supported image input into a `data:image/...;base64,...` URL.
+ * Accepts: an existing data URL, an http(s) URL (fetched), or a local file path.
+ * Converting everything to a data URL guarantees every reference image is honored
+ * by the backend (which otherwise prefers URLs over base64 and won't mix them).
+ */
+async function resolveToDataUrl(input) {
+    if (/^data:image\//i.test(input))
+        return input;
+    if (/^https?:\/\//i.test(input)) {
+        const r = await fetch(input);
+        if (!r.ok)
+            throw new Error(`Failed to fetch image ${input} (HTTP ${r.status})`);
+        const buf = Buffer.from(await r.arrayBuffer());
+        const mime = r.headers.get('content-type')?.split(';')[0] || 'image/jpeg';
+        return `data:${mime};base64,${buf.toString('base64')}`;
+    }
+    // Treat as a local file path.
+    const ext = input.split('.').pop()?.toLowerCase() ?? 'png';
+    const mime = EXT_MIME[ext] ?? 'image/png';
+    const buf = readFileSync(input); // throws a clear ENOENT if the path is wrong
+    return `data:${mime};base64,${buf.toString('base64')}`;
+}
+export class MeltflexClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    static fromConfig() {
+        const { apiKey, baseUrl } = loadConfig();
+        if (!apiKey) {
+            throw new Error('No MeltFlex API key configured. Run `meltflex auth <mf_sk_...>` or set the MELTFLEX_API_KEY environment variable. Get a key at https://www.meltflexai.com/settings (Growth plan or higher).');
+        }
+        return new MeltflexClient(apiKey, baseUrl);
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    async generate(params) {
+        const body = { prompt: params.prompt };
+        body.image = await resolveToDataUrl(params.image);
+        if (params.referenceImages?.length) {
+            body.referenceImages = await Promise.all(params.referenceImages.map(resolveToDataUrl));
+        }
+        if (params.referenceProducts?.length) {
+            body.referenceProducts = params.referenceProducts;
+        }
+        const res = await fetch(`${this.baseUrl}/api/v1/generate`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        const json = (await res.json().catch(() => ({})));
+        if (!res.ok || !json?.success) {
+            throw new Error(json?.message || json?.error || `Generation failed (HTTP ${res.status})`);
+        }
+        return { image: json.image, creditsUsed: json.creditsUsed };
+    }
+    async credits() {
+        const res = await fetch(`${this.baseUrl}/api/v1/credits`, {
+            headers: this.headers(),
+        });
+        const json = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            throw new Error(json?.error || `Credits check failed (HTTP ${res.status})`);
+        }
+        return json;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { MeltflexClient } from './api.js';
+import { saveImage } from './util.js';
+import { saveApiKey, loadConfig, CONFIG_PATH } from './config.js';
+const USAGE = `MeltFlex AI — generate photorealistic interiors from your terminal or AI agent.
+
+Usage:
+  meltflex                          Start the MCP server over stdio (used by AI agents)
+  meltflex auth <mf_sk_...>          Save your MeltFlex API key
+  meltflex whoami                   Show authentication status
+  meltflex credits                  Show your credit balance and costs
+  meltflex generate [options]       Generate a redesigned interior
+
+generate options:
+  -i, --image <path|url>            Source room photo (file path, http(s) URL, or data URL)  [required]
+  -p, --prompt <text>               Redesign instruction                                      [required]
+  -r, --ref <path|url>              Reference furniture image (repeatable, up to 10)
+  -o, --out <path>                  Where to save the result (default ./meltflex-output/)
+
+Get an API key at https://www.meltflexai.com/settings (Growth plan or higher).
+Config file: ${CONFIG_PATH}
+`;
+/** Minimal flag parser supporting repeatable --ref. */
+function parseFlags(argv) {
+    const alias = {
+        '-i': 'image', '-p': 'prompt', '-r': 'ref', '-o': 'out',
+        '--image': 'image', '--prompt': 'prompt', '--ref': 'ref', '--out': 'out',
+    };
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const key = alias[argv[i]];
+        if (!key)
+            continue;
+        const val = argv[++i];
+        if (val === undefined)
+            continue;
+        if (key === 'ref') {
+            (out.ref ??= []);
+            out.ref.push(val);
+        }
+        else {
+            out[key] = val;
+        }
+    }
+    return out;
+}
+async function runServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the JSON-RPC channel — only log to stderr.
+    console.error('[meltflex] MCP server running on stdio');
+}
+async function cmdGenerate(argv) {
+    const f = parseFlags(argv);
+    const image = f.image;
+    const prompt = f.prompt;
+    if (!image || !prompt) {
+        console.error('Error: --image and --prompt are required.\n\n' + USAGE);
+        process.exit(1);
+    }
+    const refs = f.ref ?? [];
+    const client = MeltflexClient.fromConfig();
+    console.error('Generating…');
+    const { image: dataUrl, creditsUsed } = await client.generate({
+        prompt,
+        image,
+        referenceImages: refs.length ? refs : undefined,
+    });
+    const target = saveImage(dataUrl, f.out);
+    console.log(`✅ Saved to ${target}`);
+    console.log(`Credits used: ${creditsUsed}`);
+}
+async function cmdCredits() {
+    const client = MeltflexClient.fromConfig();
+    const c = await client.credits();
+    console.log(`MeltFlex account${c.email ? ` (${c.email})` : ''}`);
+    console.log(`Balance: ${c.balance} credits  (earned ${c.totalEarned}, spent ${c.totalSpent})`);
+    if (c.costs) {
+        console.log('Cost per operation:');
+        for (const [k, v] of Object.entries(c.costs))
+            console.log(`  • ${k}: ${v}`);
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case undefined:
+        case 'serve':
+        case 'mcp':
+            return runServer();
+        case 'auth': {
+            const key = rest[0]?.trim();
+            if (!key || !key.startsWith('mf_sk_')) {
+                console.error('Usage: meltflex auth <mf_sk_...>\nGet your API key at https://www.meltflexai.com/settings (Growth plan or higher).');
+                process.exit(1);
+            }
+            console.log(`✅ API key saved to ${saveApiKey(key)}`);
+            return;
+        }
+        case 'whoami': {
+            const { apiKey, baseUrl } = loadConfig();
+            console.log(apiKey
+                ? `Authenticated (key ${apiKey.slice(0, 12)}…) → ${baseUrl}`
+                : 'Not authenticated. Run: meltflex auth <mf_sk_...>');
+            return;
+        }
+        case 'credits':
+            return cmdCredits();
+        case 'generate':
+            return cmdGenerate(rest);
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(USAGE);
+            return;
+        default:
+            console.error(`Unknown command: ${cmd}\n\n${USAGE}`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(`[meltflex] ${err?.message ?? err}`);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,42 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, } from 'node:fs';
+const CONFIG_DIR = join(homedir(), '.meltflex');
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+export const DEFAULT_BASE_URL = 'https://www.meltflexai.com';
+function readFile() {
+    if (!existsSync(CONFIG_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve config. Environment variables win over the on-disk config file so
+ * that hosted/CI setups (e.g. an `env` block in the MCP client config) work
+ * without an interactive `meltflex auth` step.
+ */
+export function loadConfig() {
+    const file = readFile();
+    return {
+        apiKey: process.env.MELTFLEX_API_KEY || file.apiKey,
+        baseUrl: process.env.MELTFLEX_BASE_URL || file.baseUrl || DEFAULT_BASE_URL,
+    };
+}
+/** Persist the API key to ~/.meltflex/config.json with owner-only perms. */
+export function saveApiKey(apiKey) {
+    if (!existsSync(CONFIG_DIR))
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    const next = { ...readFile(), apiKey };
+    writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2));
+    try {
+        chmodSync(CONFIG_PATH, 0o600);
+    }
+    catch {
+        /* best-effort on platforms without POSIX perms */
+    }
+    return CONFIG_PATH;
+}

package/dist/server.js

@@ -0,0 +1,99 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { MeltflexClient } from './api.js';
+import { saveImage } from './util.js';
+export function createServer() {
+    const server = new McpServer({ name: 'meltflex', version: '0.1.0' });
+    server.registerTool('generate_interior', {
+        title: 'Generate interior design',
+        description: 'Transform a room photo into a redesigned, photorealistic interior using MeltFlex AI. ' +
+            'Provide a source room photo (local file path, http(s) URL, or data:image URL) and a prompt ' +
+            'describing the desired style or changes. Optionally provide reference furniture/decor images ' +
+            'to place specific products into the room. Costs 10 MeltFlex credits per generation. ' +
+            'The result is saved to disk and the file path is returned.',
+        inputSchema: {
+            prompt: z
+                .string()
+                .describe('What to do to the room, e.g. "Redesign in warm Scandinavian style with light oak floors and a beige linen sofa". Room structure (walls, windows, doors) is preserved unless you say otherwise.'),
+            image: z
+                .string()
+                .describe('Source room photo: a local file path, an http(s) URL, or a data:image/...;base64,... URL.'),
+            reference_images: z
+                .array(z.string())
+                .optional()
+                .describe('Optional furniture/decor reference images (file paths or URLs) whose exact appearance should be placed into the room.'),
+            output_path: z
+                .string()
+                .optional()
+                .describe('Where to save the result image. Defaults to ./meltflex-output/interior-<timestamp>.<ext> in the current working directory.'),
+        },
+    }, async ({ prompt, image, reference_images, output_path }) => {
+        try {
+            const client = MeltflexClient.fromConfig();
+            const { image: dataUrl, creditsUsed } = await client.generate({
+                prompt,
+                image,
+                referenceImages: reference_images,
+            });
+            const target = saveImage(dataUrl, output_path);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✅ Interior generated and saved to:\n${target}\n\nCredits used: ${creditsUsed}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `MeltFlex generation failed: ${err?.message ?? String(err)}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.registerTool('check_credits', {
+        title: 'Check MeltFlex credits',
+        description: 'Check the current MeltFlex credit balance and the per-operation credit costs for the authenticated account.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const client = MeltflexClient.fromConfig();
+            const c = await client.credits();
+            const costLines = c.costs
+                ? '\n\nCost per operation:\n' +
+                    Object.entries(c.costs)
+                        .map(([k, v]) => `  • ${k}: ${v} credits`)
+                        .join('\n')
+                : '';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `MeltFlex account${c.email ? ` (${c.email})` : ''}\n` +
+                            `Balance: ${c.balance} credits\n` +
+                            `Total earned: ${c.totalEarned} • Total spent: ${c.totalSpent}` +
+                            costLines,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Could not fetch credits: ${err?.message ?? String(err)}`,
+                    },
+                ],
+            };
+        }
+    });
+    return server;
+}

package/dist/util.js

@@ -0,0 +1,39 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+/** Filesystem-safe timestamp like 2026-06-02_16-02-11. */
+export function timestamp() {
+    return new Date()
+        .toISOString()
+        .replace(/[:.]/g, '-')
+        .replace('T', '_')
+        .slice(0, 19);
+}
+/** Decode a `data:image/...;base64,...` URL into a Buffer + a file extension. */
+export function dataUrlToBuffer(dataUrl) {
+    const m = dataUrl.match(/^data:image\/(\w+);base64,(.+)$/);
+    if (!m)
+        throw new Error('Unexpected image format (expected a data:image/... URL)');
+    return {
+        buffer: Buffer.from(m[2], 'base64'),
+        ext: m[1] === 'jpeg' ? 'jpg' : m[1],
+    };
+}
+/**
+ * Resolve where to write a generated image. If `outputPath` is given it is used
+ * (relative paths are resolved against cwd); otherwise a timestamped file under
+ * ./meltflex-output is returned.
+ */
+export function resolveOutputPath(outputPath, ext) {
+    if (outputPath && outputPath.trim()) {
+        return isAbsolute(outputPath) ? outputPath : join(process.cwd(), outputPath);
+    }
+    return join(process.cwd(), 'meltflex-output', `interior-${timestamp()}.${ext}`);
+}
+/** Decode a result data URL and write it to disk, creating parent dirs. Returns the path. */
+export function saveImage(dataUrl, outputPath) {
+    const { buffer, ext } = dataUrlToBuffer(dataUrl);
+    const target = resolveOutputPath(outputPath, ext);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, buffer);
+    return target;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "meltflex-mcp",
+  "version": "0.1.0",
+  "description": "MeltFlex AI — generate photorealistic interior designs from your AI agent. MCP server + CLI.",
+  "type": "module",
+  "bin": {
+    "meltflex": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsc && node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MeltFlexDevs/MeltFlex_architecture.git",
+    "directory": "meltflex-app/meltflex-mcp"
+  },
+  "homepage": "https://www.meltflexai.com/mcp",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "meltflex",
+    "interior-design",
+    "ai",
+    "claude"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: meltflex
+description: Generate photorealistic interior-design redesigns from a room photo using MeltFlex AI. Use when the user wants to restyle, redesign, or virtually stage a room, place specific furniture into a photo, or check their MeltFlex credit balance.
+---
+
+# MeltFlex AI
+
+MeltFlex turns a real room photo into a redesigned, photorealistic interior. This skill drives the MeltFlex MCP server.
+
+## Setup (once)
+
+The MCP server must be connected and authenticated. The user authenticates to **their own** MeltFlex account; all generations are billed to their account credits.
+
+```bash
+npx -y meltflex-mcp auth mf_sk_xxxxxxxx   # or set MELTFLEX_API_KEY
+```
+
+If a tool reports "No MeltFlex API key configured", tell the user to run the command above. API keys come from https://www.meltflexai.com/settings (Growth plan or higher).
+
+## Tools
+
+### `generate_interior`
+Transform a room photo. Cost: **10 credits** per generation.
+- `prompt` (required) — the redesign instruction. Room structure (walls, windows, doors, flooring) is preserved unless the prompt says otherwise.
+- `image` (required) — source room photo: local file path, http(s) URL, or `data:image` URL.
+- `reference_images` (optional) — furniture/decor images to place exactly into the room.
+- `output_path` (optional) — where to save the result. Defaults to `./meltflex-output/`.
+
+### `check_credits`
+Returns the account's credit balance and per-operation costs. Use this before a batch of generations, or when the user asks about credits.
+
+## How to work with the user
+
+1. **Always need a source photo.** If the user describes a room but gives no image, ask for a file path or URL — MeltFlex restyles an existing photo, it does not generate rooms from scratch.
+2. **Write specific prompts.** Translate vague requests into concrete style language: materials, colors, furniture, lighting, mood. E.g. "make it cozy" → "Warm Scandinavian living room: light oak floor, beige linen sofa, cream wool rug, soft diffused daylight."
+3. **Reference furniture** — when the user wants a *specific* product placed, pass its image(s) in `reference_images`.
+4. **Report the saved path** and credits used after each generation. Offer iterations (the user can refine the prompt and regenerate).
+5. **Low on credits?** If a generation fails with an insufficient-credits error, tell the user the balance and point them to https://www.meltflexai.com/settings.
+
+## Example
+
+> User: "Here's my living room /Users/me/room.jpg — make it modern minimalist."
+
+Call `generate_interior` with:
+- `prompt`: "Modern minimalist living room: white walls, polished concrete floor, low-profile grey sofa, single statement floor lamp, decluttered, natural light. Preserve windows and doors."
+- `image`: "/Users/me/room.jpg"