mcp-sight 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nicepkg
+
+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,61 @@
+# mcp-sight
+
+Give Claude Code the power of sight — describe images using any vision-capable LLM (OpenAI-compatible API).
+
+## Setup
+
+Add to `~/.claude/settings.json` or `<project>/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-sight": {
+      "command": "bunx",
+      "args": ["mcp-sight"],
+      "env": {
+        "VISION_API_KEY": "sk-your-api-key",
+        "VISION_BASE_URL": "https://api.openai.com/v1",
+        "VISION_MODEL": "gpt-4o"
+      }
+    }
+  }
+}
+```
+
+Or use the `claude mcp add` command:
+
+```bash
+claude mcp add mcp-sight \
+  --scope user \
+  --env VISION_API_KEY=sk-your-api-key \
+  --env VISION_BASE_URL=https://api.openai.com/v1 \
+  --env VISION_MODEL=gpt-4o \
+  -- bunx mcp-sight
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `VISION_API_KEY` | **Yes** | — | API key for the vision provider |
+| `VISION_BASE_URL` | No | `https://api.openai.com/v1` | OpenAI-compatible API base URL |
+| `VISION_MODEL` | No | `mimo-v2.5` | Model ID for vision requests |
+
+## Tool: `describe_image`
+
+When you send an image to Claude Code, it can call this tool to "see" it.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `image_path` | string | Yes | Absolute path to the image file |
+| `prompt` | string | No | What to focus on in the image |
+| `context` | string | No | Background context from your conversation |
+| `detail_level` | `"brief"` \| `"standard"` \| `"detailed"` | No | How much detail (default: `"standard"`) |
+
+## Supported Image Formats
+
+JPEG, PNG, GIF, WebP, BMP, SVG, TIFF, ICO, HEIC, HEIF
+
+## License
+
+MIT

package/bin/mcp-vision.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// npm-compatible bin entry — bun handles TS import when run via bun
+import("../src/index.ts");

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mcp-sight",
+  "version": "1.0.0",
+  "description": "MCP server that gives Claude Code sight — describe images using a vision-capable LLM",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "mcp-sight": "bin/mcp-vision.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0",
+    "@modelcontextprotocol/sdk": "^1.29",
+    "ai": "^6.0",
+    "zod": "^3.25"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.9.1"
+  },
+  "keywords": [
+    "mcp",
+    "vision",
+    "image-description",
+    "model-context-protocol",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/momo1037/mcp-sight.git"
+  }
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod/v4";
+import { generateText } from "ai";
+import { createOpenAI } from "@ai-sdk/openai";
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+
+// ─── Configuration from environment ───────────────────────────────
+
+const VISION_API_KEY = process.env.VISION_API_KEY;
+const VISION_BASE_URL =
+  process.env.VISION_BASE_URL || "https://api.openai.com/v1";
+const VISION_MODEL = process.env.VISION_MODEL || "mimo-v2.5";
+
+if (!VISION_API_KEY) {
+  console.error("ERROR: VISION_API_KEY environment variable is required");
+  process.exit(1);
+}
+
+// ─── Media type detection ──────────────────────────────────────────
+
+const MIME_MAP: Record<string, string> = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".svg": "image/svg+xml",
+  ".tiff": "image/tiff",
+  ".tif": "image/tiff",
+  ".ico": "image/x-icon",
+  ".heic": "image/heic",
+  ".heif": "image/heif",
+};
+
+function getMediaType(filePath: string): string {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_MAP[ext] || "image/png";
+}
+
+// ─── Detail-level prompts ──────────────────────────────────────────
+
+const SYSTEM_PROMPTS: Record<string, string> = {
+  brief:
+    "You are a concise image describer. Reply in 1-2 short sentences. " +
+    "Focus only on the most important subject and action in the image. " +
+    "Be direct and brief.",
+
+  standard:
+    "You are a helpful image describer. Describe the image in detail — " +
+    "cover main subjects, composition, colors, setting, and any notable elements. " +
+    "Be thorough but focused. Do not add interpretation beyond what is visible.",
+
+  detailed:
+    "You are an expert visual analyst. Provide an extremely thorough, " +
+    "comprehensive description. Cover: main subjects, background, composition, " +
+    "lighting/contrast, colors/palette, textures, mood/atmosphere, " +
+    "spatial relationships, any text visible (transcribe exactly), " +
+    "and subtle details that might be overlooked. Be exhaustive.",
+};
+
+// ─── OpenAI client ─────────────────────────────────────────────────
+
+const openai = createOpenAI({
+  apiKey: VISION_API_KEY,
+  baseURL: VISION_BASE_URL,
+});
+
+// ─── MCP Server ────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: "mcp-sight",
+  version: "1.0.0",
+});
+
+server.tool(
+  "describe_image",
+  "Describe an image file using a vision-capable large language model. " +
+    "Provide the absolute path to an image file on disk, and optionally a " +
+    "specific question or context to guide the description.",
+  {
+    image_path: z.string().describe(
+      "Absolute path to the image file to describe (e.g. C:/Users/Admin/pic.png)"
+    ),
+    prompt: z
+      .string()
+      .optional()
+      .describe(
+        "Specific question or instruction for the vision model. " +
+          'Defaults to "Describe this image in detail."'
+      ),
+    context: z
+      .string()
+      .optional()
+      .describe(
+        "User's original question or background context. " +
+          "This helps the model understand what the user is ultimately trying to accomplish."
+      ),
+    detail_level: z
+      .enum(["brief", "standard", "detailed"])
+      .optional()
+      .describe(
+        "Level of detail in the description. " +
+          "'brief' = 1-2 sentences, " +
+          "'standard' = thorough description, " +
+          "'detailed' = exhaustive visual analysis. " +
+          "Defaults to 'standard'."
+      ),
+  },
+  async ({ image_path, prompt, context, detail_level }) => {
+    // 1. Read image file
+    let buffer: Buffer;
+    let mediaType: string;
+    try {
+      buffer = readFileSync(image_path);
+      mediaType = getMediaType(image_path);
+    } catch (err: any) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to read image file at "${image_path}": ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // 2. Construct prompts
+    const level = detail_level || "standard";
+    const systemPrompt = SYSTEM_PROMPTS[level];
+
+    let userPrompt = prompt || "Describe this image in detail.";
+    if (context) {
+      userPrompt = [
+        "Background context (the user is asking about this):",
+        context,
+        "",
+        "Specific request:",
+        userPrompt,
+      ].join("\n");
+    }
+
+    // 3. Call vision model
+    try {
+      const result = await generateText({
+        model: openai.chat(VISION_MODEL),
+        system: systemPrompt,
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: userPrompt },
+              { type: "image", image: buffer, mediaType },
+            ],
+          },
+        ],
+      });
+
+      return {
+        content: [{ type: "text", text: result.text }],
+      };
+    } catch (err: any) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Vision model API error: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ─── Start ─────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`mcp-sight ready (model: ${VISION_MODEL}, base: ${VISION_BASE_URL})`);
+}
+
+main().catch((err) => {
+  console.error("Fatal error starting mcp-vision:", err);
+  process.exit(1);
+});