@offrouter/mcp 0.1.0 → 0.2.0

package/README.md

@@ -60,12 +60,14 @@ Pick one by setting an environment variable. If you set both, the key is used.
 | `OFFROUTER_NETWORK` | both | Only pay on `base` or only on `robinhood` |
 | `OFFROUTER_MAX_TOKENS` | `2048` | Output budget when the agent doesn't set one |
 | `OFFROUTER_E2EE` | `on` | Set to `off` to send prompts to the gateway in the clear |
+| `OFFROUTER_IMAGE_DIR` | a temp folder | Where `generate_image` saves its images |
 | `OFFROUTER_BASE_URL` | `https://offrouter.org` | API to talk to |
 
 ## Tools
 
-- **list_models** lists the models with context length and price per million tokens.
+- **list_models** lists the models with context length and price per million tokens, and the image models with their price per image.
 - **ask** sends a prompt to one model and returns the answer, what it cost, and a link to its signed receipt.
+- **generate_image** makes 1 to 4 images from a text prompt on a private image model (like `flux-2-klein`), priced per image. The images come back inline and are saved as files. Image models don't take end to end encryption yet, so the prompt reaches the gateway in the clear; it's still served in the TEE and nothing is stored. Needs a key or a wallet.
 - **compare** runs the same prompt on 2 to 4 models in parallel, so you can see the answers and costs side by side.
 - **account** shows the key balance and recent spend, the wallet address and cap, or what's left on the demo.
 - **verify_enclave** checks the enclave from your machine right now and shows the key your prompts are encrypted to.

package/dist/client.js

@@ -18,19 +18,60 @@ export class OffRouter {
     config;
     enclave;
     wallet;
-    models = null;
+    catalog = null;
     constructor(config) {
         this.config = config;
         this.enclave = new EnclaveCache(config.baseUrl);
         this.wallet = config.mode === 'wallet' ? makeWallet(config) : null;
     }
-    async listModels() {
-        if (!this.models || Date.now() - this.models.at > MODELS_TTL_MS) {
-            const list = this.getJson('/v1/models').then((b) => (b.data ?? []).filter((m) => m.type !== 'image'));
-            this.models = { at: Date.now(), list };
-            list.catch(() => (this.models = null));
+    all() {
+        if (!this.catalog || Date.now() - this.catalog.at > MODELS_TTL_MS) {
+            const list = this.getJson('/v1/models').then((b) => (b.data ?? []));
+            this.catalog = { at: Date.now(), list };
+            list.catch(() => (this.catalog = null));
         }
-        return this.models.list;
+        return this.catalog.list;
+    }
+    /** The chat models. Image models are served by generateImage, so they are left out. */
+    async listModels() {
+        return (await this.all()).filter((m) => m.type !== 'image');
+    }
+    async listImageModels() {
+        return (await this.all()).filter((m) => m.type === 'image');
+    }
+    /**
+     * Generate images. Image models do not take end to end encryption yet, so the prompt reaches
+     * the gateway in the clear; it is still served inside the TEE and nothing is stored.
+     */
+    async generateImage(input) {
+        const { mode } = this.config;
+        if (mode === 'demo')
+            throw new ApiError('Image generation needs a key or a wallet: the free demo only serves one chat model. Set OFFROUTER_API_KEY or OFFROUTER_WALLET_KEY.', 402);
+        const models = await this.listImageModels();
+        const model = input.model ?? models[0]?.id;
+        if (!model)
+            throw new ApiError('OffRouter has no image model right now.', 404, 'model_not_found');
+        const entry = models.find((m) => m.id === model);
+        if (!entry)
+            throw new ApiError(`There is no image model called "${model}". Image models: ${models.map((m) => m.id).join(', ') || 'none'}.`, 404, 'model_not_found');
+        const headers = { 'content-type': 'application/json' };
+        if (mode === 'key')
+            headers.authorization = `Bearer ${this.config.apiKey}`;
+        const body = { model, prompt: input.prompt, n: input.n ?? 1, size: input.size ?? '1024x1024', response_format: 'b64_json' };
+        const res = await this.post('/v1/images/generations', headers, body);
+        const out = await res.json();
+        const images = (out.data ?? [])
+            .filter((d) => typeof d?.b64_json === 'string' && d.b64_json)
+            .map((d) => ({ data: d.b64_json, mimeType: mimeOf(d.b64_json), ...(d.revised_prompt ? { revisedPrompt: String(d.revised_prompt) } : {}) }));
+        const charge = res.headers.get('x-offrouter-charge-usd');
+        return {
+            model,
+            images,
+            chargeUsd: charge == null ? null : Number(charge),
+            receiptUrl: res.headers.get('x-offrouter-receipt-url'),
+            paidWith: mode,
+            transaction: mode === 'wallet' ? settlement(res.headers)?.transaction : undefined,
+        };
     }
     /** Balance and recent usage of the prepaid key. */
     keyInfo() {
@@ -102,28 +143,7 @@ export class OffRouter {
             Object.assign(headers, session.headers);
         }
         const path = mode === 'demo' ? '/v1/demo/chat' : '/v1/chat/completions';
-        const doFetch = mode === 'wallet' ? this.wallet.fetch : fetch;
-        let res;
-        try {
-            res = await doFetch(`${this.config.baseUrl}${path}`, { method: 'POST', headers, body: JSON.stringify(payload) });
-        }
-        catch (e) {
-            const msg = e.message || String(e);
-            if (mode === 'wallet' && /spendControls|maxAmountPerPayment/.test(msg)) {
-                throw new Error(`Not paid: this call is quoted above the $${this.config.maxUsd} cap per call. Lower max_tokens or raise OFFROUTER_MAX_USD.`);
-            }
-            if (mode === 'wallet')
-                throw new Error(`Payment failed: ${msg.replace(/\.+$/, '')}.`);
-            throw e;
-        }
-        if (!res.ok) {
-            const err = await apiError(res);
-            if (mode === 'wallet' && res.status === 402) {
-                const why = /insufficient_balance/.test(err.message) ? 'it does not hold enough' : err.message.replace(/\.+$/, '');
-                throw new ApiError(`The wallet ${this.wallet.address} could not pay: ${why}. Fund it with USDC on Base or USDG on Robinhood Chain.`, 402, err.code);
-            }
-            throw err;
-        }
+        const res = await this.post(path, headers, payload);
         if (session && !session.applied(res.headers))
             throw new Error('The enclave did not confirm it encrypted the answer, so it was not read.');
         let text = '';
@@ -159,6 +179,33 @@ export class OffRouter {
             demoRemaining: remaining == null ? undefined : Number(remaining),
         };
     }
+    /** POST, paid from the wallet in wallet mode, with payment failures turned into readable errors. */
+    async post(path, headers, payload) {
+        const { mode } = this.config;
+        const doFetch = mode === 'wallet' ? this.wallet.fetch : fetch;
+        let res;
+        try {
+            res = await doFetch(`${this.config.baseUrl}${path}`, { method: 'POST', headers, body: JSON.stringify(payload) });
+        }
+        catch (e) {
+            const msg = e.message || String(e);
+            if (mode === 'wallet' && /spendControls|maxAmountPerPayment/.test(msg)) {
+                throw new Error(`Not paid: this call is quoted above the $${this.config.maxUsd} cap per call. Lower max_tokens (or n, for images) or raise OFFROUTER_MAX_USD.`);
+            }
+            if (mode === 'wallet')
+                throw new Error(`Payment failed: ${msg.replace(/\.+$/, '')}.`);
+            throw e;
+        }
+        if (!res.ok) {
+            const err = await apiError(res);
+            if (mode === 'wallet' && res.status === 402) {
+                const why = /insufficient_balance/.test(err.message) ? 'it does not hold enough' : err.message.replace(/\.+$/, '');
+                throw new ApiError(`The wallet ${this.wallet.address} could not pay: ${why}. Fund it with USDC on Base or USDG on Robinhood Chain.`, 402, err.code);
+            }
+            throw err;
+        }
+        return res;
+    }
     async getJson(path, headers = {}) {
         const res = await fetch(`${this.config.baseUrl}${path}`, { headers: { accept: 'application/json', ...headers } });
         if (!res.ok)
@@ -166,6 +213,16 @@ export class OffRouter {
         return res.json();
     }
 }
+/** PNG, JPEG or WebP, from the first bytes. */
+function mimeOf(b64) {
+    if (b64.startsWith('iVBOR'))
+        return 'image/png';
+    if (b64.startsWith('/9j/'))
+        return 'image/jpeg';
+    if (b64.startsWith('UklGR'))
+        return 'image/webp';
+    return 'image/png';
+}
 async function apiError(res) {
     const body = await res.json().catch(() => null);
     const err = body?.error;

package/dist/config.js

@@ -1,5 +1,7 @@
 // Everything is configured through environment variables, so it fits in the
 // "env" block of any MCP client config.
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 const off = (v) => !!v && ['0', 'false', 'off', 'no'].includes(v.trim().toLowerCase());
 export function loadConfig(env = process.env) {
     const baseUrl = (env.OFFROUTER_BASE_URL || 'https://offrouter.org').replace(/\/+$/, '');
@@ -28,5 +30,6 @@ export function loadConfig(env = process.env) {
         network: network,
         defaultMaxTokens,
         e2ee: !off(env.OFFROUTER_E2EE),
+        imageDir: env.OFFROUTER_IMAGE_DIR?.trim() || join(tmpdir(), 'offrouter-images'),
     };
 }

package/dist/server.js

@@ -1,6 +1,8 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';
 const MAX_COMPARE = 4;
 const text = (t) => ({ content: [{ type: 'text', text: t }] });
 const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
@@ -19,6 +21,18 @@ function footer(r) {
         parts.push(`receipt ${r.receiptUrl}`);
     return parts.join(' · ');
 }
+function imageFooter(r) {
+    const parts = [r.model, `${r.images.length} image${r.images.length === 1 ? '' : 's'}`];
+    if (r.chargeUsd != null)
+        parts.push(usd(r.chargeUsd));
+    if (r.transaction && !r.transaction.startsWith('dryrun_'))
+        parts.push(`paid in tx ${r.transaction}`);
+    parts.push('served in a TEE, prompt not end to end encrypted');
+    if (r.receiptUrl)
+        parts.push(`receipt ${r.receiptUrl}`);
+    return parts.join(' · ');
+}
+const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' };
 const date = (sec) => (sec ? new Date(sec * 1000).toISOString().slice(0, 16).replace('T', ' ') : 'never');
 /** Where it stands: ready once it passed its evaluation and has run well for a day. */
 function standing(a) {
@@ -55,6 +69,7 @@ function instructions(api) {
         api.config.e2ee ? 'Prompts are encrypted on this machine to a key the enclave proves it holds, so the gateway only sees ciphertext.' : '',
         how,
         'Use list_models to pick a model, then ask for one answer or compare to run the same prompt on several models.',
+        'generate_image makes images from a text prompt on a private image model.',
         'list_agents and get_agent show the private agents builders have published on OffRouter Studio.',
     ]
         .filter(Boolean)
@@ -79,13 +94,16 @@ export function createServer(api) {
         }
         const q = search?.toLowerCase() ?? '';
         const rows = models.filter((m) => !q || m.id.toLowerCase().includes(q));
-        if (!rows.length)
+        if (!rows.length && !(await api.listImageModels().catch(() => [])).some((m) => m.id.toLowerCase().includes(q)))
             return text(`No models match "${search}".`);
         const lines = rows.map((m) => `${m.id} | ${Math.round(m.context_length / 1000)}k ctx | ${usd(m.input_usdc_per_mtok)} in / ${usd(m.output_usdc_per_mtok)} out per M tokens` +
             ((m.input_modalities ?? []).length > 1 ? ` | reads ${m.input_modalities.slice(1).join(' and ')}` : '') +
             (m.discount_pct ? ` | ${m.discount_pct}% off` : '') +
             (api.config.e2ee && !m.e2ee?.model ? ' | no e2ee' : ''));
-        return text(`${rows.length} private models, all served in a GPU TEE:\n\n${lines.join('\n')}`);
+        const images = (await api.listImageModels().catch(() => [])).filter((m) => !q || m.id.toLowerCase().includes(q));
+        const imageLines = images.map((m) => `${m.id} | up to ${m.max_images} per call | ${usd(m.usdc_per_image)} per image`);
+        return text(`${rows.length} private models, all served in a GPU TEE:\n\n${lines.join('\n')}` +
+            (imageLines.length ? `\n\nImage models, for generate_image:\n\n${imageLines.join('\n')}` : ''));
     });
     const chatShape = {
         prompt: z.string().min(1).describe('The user message.'),
@@ -128,6 +146,51 @@ export function createServer(api) {
         const sections = results.map((r, i) => r.status === 'fulfilled' ? `## ${ids[i]}\n\n${r.value.text || '(no text)'}\n\n${footer(r.value)}` : `## ${ids[i]}\n\nError: ${r.reason.message}`);
         return { content: [{ type: 'text', text: sections.join('\n\n---\n\n') }], isError: results.every((r) => r.status === 'rejected') };
     });
+    server.registerTool('generate_image', {
+        title: 'Generate an image',
+        description: 'Generate images from a text prompt on a private OffRouter image model. It runs inside a GPU TEE and nothing is stored. Priced per image (see list_models). ' +
+            'The images come back inline and are saved as files, whose paths are returned. Image models do not take end to end encryption yet, so the prompt reaches the gateway in the clear.',
+        inputSchema: {
+            prompt: z.string().min(1).max(4000).describe('What to draw.'),
+            model: z.string().optional().describe('Image model id from list_models, like "flux-2-klein". Defaults to the first one.'),
+            n: z.number().int().min(1).max(4).optional().describe('How many images, 1 by default.'),
+            size: z
+                .string()
+                .regex(/^\d{3,4}x\d{3,4}$/)
+                .optional()
+                .describe('WIDTHxHEIGHT, each side a multiple of 16 from 256 to 2048. Defaults to 1024x1024.'),
+            save_dir: z.string().optional().describe('Folder to save the images in. Defaults to OFFROUTER_IMAGE_DIR, or a temp folder.'),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async ({ save_dir, ...args }) => {
+        try {
+            const r = await api.generateImage(args);
+            if (!r.images.length)
+                return fail(`${r.model} returned no image, so nothing was charged.`);
+            const dir = resolve(save_dir ?? api.config.imageDir);
+            await mkdir(dir, { recursive: true });
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            const paths = [];
+            for (const [i, img] of r.images.entries()) {
+                const file = join(dir, `${r.model}-${stamp}${r.images.length > 1 ? `-${i + 1}` : ''}.${EXT[img.mimeType] ?? 'png'}`);
+                await writeFile(file, Buffer.from(img.data, 'base64'));
+                paths.push(file);
+            }
+            const revised = r.images.map((img) => img.revisedPrompt).filter(Boolean);
+            return {
+                content: [
+                    ...r.images.map((img) => ({ type: 'image', data: img.data, mimeType: img.mimeType })),
+                    {
+                        type: 'text',
+                        text: [`Saved to:\n${paths.join('\n')}`, revised.length ? `Revised prompt: ${revised[0]}` : '', imageFooter(r)].filter(Boolean).join('\n\n'),
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
     server.registerTool('account', {
         title: 'Account',
         description: 'Show how this server pays for calls: the prepaid key balance and recent spend, the wallet address and per call cap, or what is left on the free demo.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offrouter/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for OffRouter private inference. Every model runs in a GPU TEE, and your prompts are encrypted to the enclave before they leave your machine.",
   "license": "MIT",
   "author": "OffRouter",