z_ai_vision_mcp_server_clone 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# z_ai_vision_mcp_server_clone
+
+OpenAI-compatible MCP server for running image analysis tools against your own vision model endpoint.
+
+## Tools
+
+- `ui_to_artifact`
+- `extract_text_from_screenshot`
+- `diagnose_error_screenshot`
+- `understand_technical_diagram`
+- `analyze_data_visualization`
+- `ui_diff_check`
+- `analyze_image`
+
+## Configuration
+
+Set either `VISION_ENDPOINT` or `VISION_BASE_URL`.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `VISION_ENDPOINT` | Yes, unless `VISION_BASE_URL` is set | Full chat completions endpoint. |
+| `VISION_BASE_URL` | Yes, unless `VISION_ENDPOINT` is set | Base URL; `/chat/completions` is appended. |
+| `VISION_MODEL` | Yes | Vision model name sent in the request body. |
+| `VISION_API_KEY` | No | Bearer token. Omit for local endpoints that do not require auth. |
+| `VISION_PROVIDER` | No | Label for your provider. Defaults to `custom`. |
+| `VISION_MAX_IMAGE_MB` | No | Local image size limit. Defaults to `5`. |
+| `VISION_TIMEOUT_MS` | No | Request timeout. Defaults to `300000`. |
+| `VISION_TEMPERATURE` | No | Optional model temperature. |
+| `VISION_TOP_P` | No | Optional model top_p. |
+| `VISION_MAX_TOKENS` | No | Optional max_tokens. |
+
+You can also place these values in a local `.env` file in the working directory where the server starts. Real environment variables override `.env` values.
+
+## Run
+
+```bash
+npm install
+npm run build
+VISION_ENDPOINT=http://localhost:11434/v1/chat/completions VISION_MODEL=llava npm start
+```
+
+Or with `.env`:
+
+```bash
+npm start
+```
+
+## MCP Client Example
+
+```json
+{
+  "mcpServers": {
+    "z-ai-vision-clone": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/z_ai_vision_mcp_server_clone/build/src/server.js"],
+      "env": {
+        "VISION_ENDPOINT": "http://localhost:11434/v1/chat/completions",
+        "VISION_MODEL": "llava"
+      }
+    }
+  }
+}
+```

package/build/src/server.js

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import * as z from "zod/v4";
+export const IMAGE_TOOL_NAMES = [
+    "ui_to_artifact",
+    "extract_text_from_screenshot",
+    "diagnose_error_screenshot",
+    "understand_technical_diagram",
+    "analyze_data_visualization",
+    "ui_diff_check",
+    "analyze_image",
+];
+const imageSourceSchema = z.string().min(1);
+const promptSchema = z.string().min(1);
+const mimeTypes = {
+    ".gif": "image/gif",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+};
+const prompts = {
+    analyzeImage: "Analyze the provided image according to the user request. Be precise, practical, and mention uncertainty when details are not visible.",
+    textExtraction: "Extract visible text from the screenshot. Preserve code, logs, whitespace, line breaks, and ordering as accurately as possible.",
+    errorDiagnosis: "Diagnose the error shown in the screenshot. Identify the likely cause, the relevant evidence, and concrete next steps.",
+    diagram: "Explain the technical diagram. Identify components, relationships, flow, assumptions, and any unclear parts.",
+    dataVisualization: "Analyze the chart or dashboard. Extract the key metrics, trends, comparisons, anomalies, and business implications.",
+    uiDiff: "Compare the reference UI and actual UI. Report visible differences, severity, likely causes, and fixes.",
+    uiArtifact: {
+        code: "Turn the UI screenshot into implementation guidance or frontend code. Keep the result faithful to the visible layout and states.",
+        prompt: "Write a clear prompt that another AI system can use to recreate the UI screenshot.",
+        spec: "Extract a design specification from the UI screenshot, including layout, spacing, typography, colors, and component behavior.",
+        description: "Describe the UI screenshot in natural language with enough detail to understand its structure and purpose.",
+    },
+};
+export function loadVisionConfig(env = loadRuntimeEnvironment()) {
+    const endpoint = env.VISION_ENDPOINT || endpointFromBaseUrl(env.VISION_BASE_URL);
+    if (!endpoint) {
+        throw new Error("VISION_ENDPOINT or VISION_BASE_URL is required");
+    }
+    const model = env.VISION_MODEL;
+    if (!model) {
+        throw new Error("VISION_MODEL is required");
+    }
+    return {
+        provider: env.VISION_PROVIDER || "custom",
+        endpoint,
+        model,
+        apiKey: env.VISION_API_KEY || env.OPENAI_API_KEY,
+        maxImageBytes: readMegabytes(env.VISION_MAX_IMAGE_MB, 5) * 1024 * 1024,
+        timeoutMs: readNumber(env.VISION_TIMEOUT_MS, 300_000),
+        temperature: readOptionalNumber(env.VISION_TEMPERATURE),
+        topP: readOptionalNumber(env.VISION_TOP_P),
+        maxTokens: readOptionalNumber(env.VISION_MAX_TOKENS),
+    };
+}
+function loadRuntimeEnvironment() {
+    return { ...readDotEnvFile(), ...process.env };
+}
+function readDotEnvFile() {
+    let text;
+    try {
+        text = readFileSync(".env", "utf8");
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? error.code : undefined;
+        if (code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+    const env = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const index = line.indexOf("=");
+        if (index < 1) {
+            continue;
+        }
+        const key = line.slice(0, index).trim();
+        let value = line.slice(index + 1).trim();
+        if ((value.startsWith("\"") && value.endsWith("\"")) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return env;
+}
+function endpointFromBaseUrl(baseUrl) {
+    if (!baseUrl) {
+        return undefined;
+    }
+    return `${baseUrl.replace(/\/+$/, "")}/chat/completions`;
+}
+function readMegabytes(value, fallback) {
+    const numberValue = readNumber(value, fallback);
+    if (numberValue <= 0) {
+        throw new Error("VISION_MAX_IMAGE_MB must be greater than 0");
+    }
+    return numberValue;
+}
+function readNumber(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const numberValue = Number(value);
+    if (!Number.isFinite(numberValue)) {
+        throw new Error(`Invalid numeric environment value: ${value}`);
+    }
+    return numberValue;
+}
+function readOptionalNumber(value) {
+    return value ? readNumber(value, 0) : undefined;
+}
+function isRemoteUrl(source) {
+    try {
+        const url = new URL(source);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+export async function imageContentFromSource(source, maxBytes = 5 * 1024 * 1024) {
+    if (isRemoteUrl(source)) {
+        return { type: "image_url", image_url: { url: source } };
+    }
+    const stats = await stat(source);
+    if (!stats.isFile()) {
+        throw new Error(`Image source is not a file: ${source}`);
+    }
+    if (stats.size > maxBytes) {
+        throw new Error(`Image file is too large: ${(stats.size / 1024 / 1024).toFixed(2)}MB`);
+    }
+    const extension = extname(source).toLowerCase();
+    const mimeType = mimeTypes[extension];
+    if (!mimeType) {
+        throw new Error(`Unsupported image format: ${extension || "(none)"}`);
+    }
+    const bytes = await readFile(source);
+    return {
+        type: "image_url",
+        image_url: { url: `data:${mimeType};base64,${bytes.toString("base64")}` },
+    };
+}
+export function buildVisionMessages(systemPrompt, prompt, images) {
+    return [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: [...images, { type: "text", text: prompt }] },
+    ];
+}
+async function analyzeImageSources(config, sources, systemPrompt, prompt) {
+    const images = [];
+    for (const source of sources) {
+        images.push(await imageContentFromSource(source, config.maxImageBytes));
+    }
+    return callVisionEndpoint(config, buildVisionMessages(systemPrompt, prompt, images));
+}
+async function callVisionEndpoint(config, messages) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+        headers.Authorization = `Bearer ${config.apiKey}`;
+    }
+    const body = {
+        model: config.model,
+        messages,
+        stream: false,
+    };
+    if (config.temperature !== undefined) {
+        body.temperature = config.temperature;
+    }
+    if (config.topP !== undefined) {
+        body.top_p = config.topP;
+    }
+    if (config.maxTokens !== undefined) {
+        body.max_tokens = config.maxTokens;
+    }
+    try {
+        const response = await fetch(config.endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+        }
+        return extractVisionText(await response.json());
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Vision endpoint timed out after ${config.timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function extractVisionText(payload) {
+    const root = asRecord(payload);
+    const choices = root ? root.choices : undefined;
+    if (!Array.isArray(choices) || choices.length === 0) {
+        throw new Error("Vision endpoint response did not include choices");
+    }
+    const firstChoice = asRecord(choices[0]);
+    const message = asRecord(firstChoice?.message);
+    const content = message?.content;
+    if (typeof content === "string" && content.trim()) {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        const text = content
+            .map((part) => asRecord(part)?.text)
+            .filter((part) => typeof part === "string")
+            .join("\n")
+            .trim();
+        if (text) {
+            return text;
+        }
+    }
+    throw new Error("Vision endpoint response did not include message content");
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : undefined;
+}
+function toolResponse(text) {
+    return { content: [{ type: "text", text }] };
+}
+function toolError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+function withOptionalHint(prompt, tag, value) {
+    return value?.trim() ? `${prompt}\n\n<${tag}>${value}</${tag}>` : prompt;
+}
+export function createServer(configLoader = loadVisionConfig) {
+    const server = new McpServer({
+        name: "custom-vision-mcp-server",
+        version: "0.1.0",
+    });
+    const analyze = async (sources, systemPrompt, prompt) => analyzeImageSources(configLoader(), sources, systemPrompt, prompt);
+    server.registerTool("ui_to_artifact", {
+        title: "UI to Artifact",
+        description: "Convert a UI screenshot into code guidance, a recreation prompt, a design spec, or a description.",
+        inputSchema: {
+            image_source: imageSourceSchema,
+            output_type: z.enum(["code", "prompt", "spec", "description"]),
+            prompt: promptSchema,
+        },
+    }, async ({ image_source, output_type, prompt }) => {
+        try {
+            return toolResponse(await analyze([image_source], prompts.uiArtifact[output_type], prompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.registerTool("extract_text_from_screenshot", {
+        title: "Extract Text from Screenshot",
+        description: "Extract visible text from a screenshot, including code, logs, terminal output, and documents.",
+        inputSchema: {
+            image_source: imageSourceSchema,
+            prompt: promptSchema,
+            programming_language: z.string().optional(),
+        },
+    }, async ({ image_source, prompt, programming_language }) => {
+        try {
+            const enhancedPrompt = withOptionalHint(prompt, "programming_language", programming_language);
+            return toolResponse(await analyze([image_source], prompts.textExtraction, enhancedPrompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.registerTool("diagnose_error_screenshot", {
+        title: "Diagnose Error Screenshot",
+        description: "Analyze an error screenshot and suggest likely causes and fixes.",
+        inputSchema: {
+            image_source: imageSourceSchema,
+            prompt: promptSchema,
+            context: z.string().optional(),
+        },
+    }, async ({ image_source, prompt, context }) => {
+        try {
+            const enhancedPrompt = withOptionalHint(prompt, "error_context", context);
+            return toolResponse(await analyze([image_source], prompts.errorDiagnosis, enhancedPrompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.registerTool("understand_technical_diagram", {
+        title: "Understand Technical Diagram",
+        description: "Explain architecture diagrams, flowcharts, UML, ER diagrams, and related technical drawings.",
+        inputSchema: {
+            image_source: imageSourceSchema,
+            prompt: promptSchema,
+            diagram_type: z.string().optional(),
+        },
+    }, async ({ image_source, prompt, diagram_type }) => {
+        try {
+            const enhancedPrompt = withOptionalHint(prompt, "diagram_type", diagram_type);
+            return toolResponse(await analyze([image_source], prompts.diagram, enhancedPrompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.registerTool("analyze_data_visualization", {
+        title: "Analyze Data Visualization",
+        description: "Analyze charts, graphs, and dashboards for metrics, trends, anomalies, and implications.",
+        inputSchema: {
+            image_source: imageSourceSchema,
+            prompt: promptSchema,
+            analysis_focus: z.string().optional(),
+        },
+    }, async ({ image_source, prompt, analysis_focus }) => {
+        try {
+            const enhancedPrompt = withOptionalHint(prompt, "analysis_focus", analysis_focus);
+            return toolResponse(await analyze([image_source], prompts.dataVisualization, enhancedPrompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.registerTool("ui_diff_check", {
+        title: "UI Diff Check",
+        description: "Compare a reference UI screenshot with an actual implementation screenshot.",
+        inputSchema: {
+            expected_image_source: imageSourceSchema,
+            actual_image_source: imageSourceSchema,
+            prompt: promptSchema,
+        },
+    }, async ({ expected_image_source, actual_image_source, prompt }) => {
+        try {
+            const enhancedPrompt = `The first image is the expected reference UI. The second image is the actual UI.\n\n${prompt}`;
+            return toolResponse(await analyze([expected_image_source, actual_image_source], prompts.uiDiff, enhancedPrompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    server.registerTool("analyze_image", {
+        title: "Analyze Image",
+        description: "General-purpose image analysis for cases not covered by the specialized image tools.",
+        inputSchema: {
+            image_source: imageSourceSchema,
+            prompt: promptSchema,
+        },
+    }, async ({ image_source, prompt }) => {
+        try {
+            return toolResponse(await analyze([image_source], prompts.analyzeImage, prompt));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    return server;
+}
+export function redirectConsoleToStderr() {
+    console.log = console.error.bind(console);
+    console.info = console.error.bind(console);
+    console.debug = console.error.bind(console);
+}
+async function main() {
+    redirectConsoleToStderr();
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/build/test/vision.test.js

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { chdir, cwd } from "node:process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { IMAGE_TOOL_NAMES, buildVisionMessages, imageContentFromSource, loadVisionConfig, } from "../src/server.js";
+const expectedTools = [
+    "ui_to_artifact",
+    "extract_text_from_screenshot",
+    "diagnose_error_screenshot",
+    "understand_technical_diagram",
+    "analyze_data_visualization",
+    "ui_diff_check",
+    "analyze_image",
+];
+assert.deepEqual(IMAGE_TOOL_NAMES, expectedTools);
+const config = loadVisionConfig({
+    VISION_PROVIDER: "local",
+    VISION_ENDPOINT: "http://localhost:11434/v1/chat/completions",
+    VISION_MODEL: "llava",
+    VISION_API_KEY: "test-key",
+});
+assert.equal(config.provider, "local");
+assert.equal(config.endpoint, "http://localhost:11434/v1/chat/completions");
+assert.equal(config.model, "llava");
+assert.equal(config.apiKey, "test-key");
+const dir = await mkdtemp(join(tmpdir(), "custom-vision-mcp-"));
+try {
+    const originalCwd = cwd();
+    const envKeys = ["VISION_PROVIDER", "VISION_ENDPOINT", "VISION_BASE_URL", "VISION_MODEL", "VISION_API_KEY"];
+    const originalEnv = Object.fromEntries(envKeys.map((key) => [key, process.env[key]]));
+    for (const key of envKeys) {
+        delete process.env[key];
+    }
+    chdir(dir);
+    await writeFile(".env", "VISION_PROVIDER=file-provider\nVISION_ENDPOINT=http://example.test/v1/chat/completions\nVISION_MODEL=file-model\nVISION_API_KEY=file-key\n");
+    const fileConfig = loadVisionConfig();
+    assert.equal(fileConfig.provider, "file-provider");
+    assert.equal(fileConfig.endpoint, "http://example.test/v1/chat/completions");
+    assert.equal(fileConfig.model, "file-model");
+    assert.equal(fileConfig.apiKey, "file-key");
+    chdir(originalCwd);
+    for (const [key, value] of Object.entries(originalEnv)) {
+        if (value === undefined) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = value;
+        }
+    }
+    const imagePath = join(dir, "sample.png");
+    await writeFile(imagePath, Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+    const localImage = await imageContentFromSource(imagePath);
+    assert.equal(localImage.type, "image_url");
+    assert.match(localImage.image_url.url, /^data:image\/png;base64,/);
+    const remoteImage = await imageContentFromSource("https://example.com/image.webp");
+    assert.deepEqual(remoteImage, {
+        type: "image_url",
+        image_url: { url: "https://example.com/image.webp" },
+    });
+    const messages = buildVisionMessages("System", "Describe it", [localImage]);
+    assert.equal(messages[0]?.role, "system");
+    assert.equal(messages[1]?.role, "user");
+    assert.equal(messages[1]?.content.at(-1)?.type, "text");
+}
+finally {
+    await rm(dir, { recursive: true, force: true });
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "z_ai_vision_mcp_server_clone",
+  "version": "0.1.0",
+  "description": "OpenAI-compatible MCP server for custom vision model endpoints",
+  "main": "build/src/server.js",
+  "type": "module",
+  "bin": {
+    "z_ai_vision_mcp_server_clone": "build/src/server.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1orzero/z_ai_vision_mcp_server_clone.git"
+  },
+  "bugs": {
+    "url": "https://github.com/1orzero/z_ai_vision_mcp_server_clone/issues"
+  },
+  "homepage": "https://github.com/1orzero/z_ai_vision_mcp_server_clone#readme",
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node build/src/server.js",
+    "test": "npm run build && node build/test/vision.test.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}