mcp-hydrocoder-vision 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP HydroCoder Vision
+
+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,129 @@
+# MCP HydroCoder Vision
+
+A vision-language MCP server that enables Claude Code to analyze images using **Qwen3 VL 4B** model running locally via LM Studio.
+
+## Features
+
+- 🔍 **Image Analysis** - Describe images in detail
+- 📝 **Text Extraction (OCR)** - Extract text from images in multiple languages
+- 💻 **UI to Code** - Generate HTML/CSS/JS code from UI/design screenshots
+- 🏠 **100% Local** - All processing happens on your machine, no cloud API needed
+- ⚡ **Fast** - Qwen3 VL 4B runs efficiently on 8GB VRAM
+
+## Prerequisites
+
+1. **LM Studio** installed and running
+2. **Qwen3 VL 4B** model loaded in LM Studio
+3. **Node.js 18+**
+
+## Installation
+
+```bash
+# Navigate to the project directory
+cd C:\workspace\develop\ccExtensions\mcpHydroVision
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Configuration
+
+### 1. Start LM Studio
+
+1. Open LM Studio
+2. Download and load `Qwen3-VL-4B-Instruct` model
+3. Start the local server (default: `http://localhost:1234`)
+
+### 2. Configure Claude Code
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "hydrocoder-vision": {
+      "command": "node",
+      "args": ["C:/workspace/develop/ccExtensions/mcpHydroVision/dist/index.js"],
+      "env": {
+        "LM_STUDIO_URL": "http://localhost:1234/v1/chat/completions",
+        "VISION_MODEL": "Qwen3-VL-4B-Instruct"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+### Available Tools
+
+#### `analyzeImage`
+
+Analyze an image and get a detailed description.
+
+```
+/analyzeImage imagePath: "C:/path/to/image.png" prompt: "What's in this image?"
+```
+
+#### `extractText`
+
+Extract text from an image (OCR).
+
+```
+/extractText imagePath: "C:/path/to/document.png" language: "English"
+```
+
+#### `describeForCode`
+
+Generate code from a UI/design screenshot.
+
+```
+/describeForCode imagePath: "C:/path/to/design.png" framework: "Vue"
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LM_STUDIO_URL` | `http://localhost:1234/v1/chat/completions` | LM Studio API endpoint |
+| `VISION_MODEL` | `Qwen3-VL-4B-Instruct` | Model name to use |
+
+## Development
+
+```bash
+# Run in development mode (watch mode)
+npm run dev
+
+# Build for production
+npm run build
+
+# Start the built server
+npm start
+```
+
+## Troubleshooting
+
+### "Request failed: ECONNREFUSED"
+
+- Make sure LM Studio is running
+- Check that the local server is enabled
+- Verify the `LM_STUDIO_URL` is correct
+
+### "No response from model"
+
+- Ensure Qwen3 VL 4B model is loaded in LM Studio
+- Check LM Studio logs for errors
+- Try a simpler prompt first
+
+### Image not found
+
+- Use absolute paths
+- Ensure the file exists and is accessible
+- Check file permissions
+
+## License
+
+MIT

package/README_CN.md

@@ -0,0 +1,136 @@
+# MCP HydroCoder Vision
+
+基于 **Qwen3 VL 4B** 模型的本地视觉语言 MCP 服务器，让 Claude Code 能够识别和分析图像。
+
+## 功能特性
+
+- 🔍 **图像分析** - 详细描述图像内容
+- 📝 **文字提取 (OCR)** - 支持多种语言的文字提取
+- 💻 **UI 转代码** - 从 UI/设计截图生成 HTML/CSS/JS 代码
+- 🏠 **100% 本地** - 所有处理在本地完成，无需云端 API
+- ⚡ **快速** - Qwen3 VL 4B 在 8GB 显存上高效运行
+
+## 前置要求
+
+1. **LM Studio** 已安装并运行
+2. **Qwen3 VL 4B** 模型已加载到 LM Studio
+3. **Node.js 18+**
+
+## 安装步骤
+
+```bash
+# 进入项目目录
+cd C:\workspace\develop\ccExtensions\mcpHydroVision
+
+# 安装依赖
+npm install
+
+# 构建项目
+npm run build
+```
+
+## 配置说明
+
+### 1. 启动 LM Studio
+
+1. 打开 LM Studio
+2. 下载并加载 `Qwen3-VL-4B-Instruct` 模型
+3. 启动本地服务器（默认：`http://localhost:1234`）
+
+### 2. 配置 Claude Code
+
+在 `~/.claude/settings.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "hydrocoder-vision": {
+      "command": "node",
+      "args": ["C:/workspace/develop/ccExtensions/mcpHydroVision/dist/index.js"],
+      "env": {
+        "LM_STUDIO_URL": "http://localhost:1234/v1/chat/completions",
+        "VISION_MODEL": "Qwen3-VL-4B-Instruct"
+      }
+    }
+  }
+}
+```
+
+## 使用方法
+
+### 可用工具
+
+#### `analyzeImage` - 图像分析
+
+分析图像并获取详细描述。
+
+```
+/analyzeImage imagePath: "C:/path/to/image.png" prompt: "这张图片里有什么？"
+```
+
+#### `extractText` - 文字提取
+
+从图像中提取文字（OCR）。
+
+```
+/extractText imagePath: "C:/path/to/document.png" language: "Chinese"
+```
+
+#### `describeForCode` - UI 转代码
+
+从 UI/设计截图生成代码。
+
+```
+/describeForCode imagePath: "C:/path/to/design.png" framework: "Vue"
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|----------|---------|-------------|
+| `LM_STUDIO_URL` | `http://localhost:1234/v1/chat/completions` | LM Studio API 端点 |
+| `VISION_MODEL` | `Qwen3-VL-4B-Instruct` | 使用的模型名称 |
+
+## 开发命令
+
+```bash
+# 开发模式（监听模式）
+npm run dev
+
+# 生产构建
+npm run build
+
+# 启动服务器
+npm start
+```
+
+## 常见问题
+
+### "Request failed: ECONNREFUSED"
+
+- 确保 LM Studio 正在运行
+- 检查本地服务器已启用
+- 验证 `LM_STUDIO_URL` 配置正确
+
+### "No response from model"
+
+- 确保 Qwen3 VL 4B 模型已在 LM Studio 中加载
+- 检查 LM Studio 日志
+- 先尝试简单的提示
+
+### 图像未找到
+
+- 使用绝对路径
+- 确保文件存在且可访问
+- 检查文件权限
+
+## 技术栈
+
+- **MCP SDK** - Model Context Protocol
+- **Qwen3 VL 4B** - 视觉语言模型
+- **LM Studio** - 本地模型推理
+- **TypeScript** - 类型安全
+
+## 许可证
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "mcp-hydrocoder-vision",
+  "version": "0.1.0",
+  "description": "Vision MCP Server for Claude Code - Qwen3 VL 4B integration",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "mcp-hydrocoder-vision": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "README_CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "vision",
+    "image",
+    "claude",
+    "qwen"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "tsx": "^4.7.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+/**
+ * MCP HydroCoder Vision Server
+ *
+ * A vision-language MCP server that connects to LM Studio running Qwen3 VL 4B
+ * for local image analysis and understanding.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+// LM Studio API configuration
+const LM_STUDIO_URL = process.env.LM_STUDIO_URL || 'http://localhost:1234/v1/chat/completions';
+const DEFAULT_MODEL = process.env.VISION_MODEL || 'Qwen3-VL-4B-Instruct';
+
+// Image MIME type mapping
+const MIME_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+};
+
+/**
+ * Get MIME type from file extension
+ */
+function getMimeType(filePath: string): string {
+  const ext = '.' + filePath.split('.').pop()?.toLowerCase();
+  return MIME_TYPES[ext] || 'image/png';
+}
+
+/**
+ * Read file as base64 (Node.js)
+ */
+async function fileToBase64(filePath: string): Promise<string> {
+  const fs = await import('fs');
+  const path = await import('path');
+
+  // Handle Windows paths
+  const normalizedPath = filePath.replace(/\//g, '\\');
+  const absolutePath = path.isAbsolute(normalizedPath)
+    ? normalizedPath
+    : path.resolve(process.cwd(), normalizedPath);
+
+  const buffer = fs.readFileSync(absolutePath);
+  return buffer.toString('base64');
+}
+
+/**
+ * Call LM Studio API for image analysis
+ */
+async function analyzeImageWithLMStudio(
+  imageDataBase64: string,
+  mimeType: string,
+  prompt: string
+): Promise<string> {
+  const http = await import('http');
+  const https = await import('https');
+  const { URL } = await import('url');
+
+  return new Promise((resolve, reject) => {
+    const url = new URL(LM_STUDIO_URL);
+    const client = url.protocol === 'https:' ? https : http;
+
+    const requestBody = JSON.stringify({
+      model: DEFAULT_MODEL,
+      messages: [{
+        role: 'user',
+        content: [
+          { type: 'text', text: prompt },
+          {
+            type: 'image_url',
+            image_url: {
+              url: `data:${mimeType};base64,${imageDataBase64}`
+            }
+          }
+        ]
+      }],
+      max_tokens: 2048,
+      temperature: 0.7,
+    });
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(requestBody),
+      },
+    };
+
+    const req = client.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const result = JSON.parse(data);
+          resolve(result.choices?.[0]?.message?.content || 'No response from model');
+        } catch (e) {
+          reject(new Error(`Failed to parse response: ${e}`));
+        }
+      });
+    });
+
+    req.on('error', (e) => {
+      reject(new Error(`Request failed: ${e.message}. Make sure LM Studio is running with Qwen3 VL 4B loaded.`));
+    });
+
+    req.write(requestBody);
+    req.end();
+  });
+}
+
+// Input schemas
+const AnalyzeImageInputSchema = z.object({
+  imagePath: z.string().describe('Path to the image file to analyze'),
+  prompt: z.string().optional().describe('Optional analysis prompt (default: "Describe this image in detail")'),
+});
+
+const ExtractTextInputSchema = z.object({
+  imagePath: z.string().describe('Path to the image file containing text'),
+  language: z.string().optional().describe('Expected language of the text (optional)'),
+});
+
+const DescribeForCodeInputSchema = z.object({
+  imagePath: z.string().describe('Path to the UI/design image'),
+  framework: z.string().optional().describe('Target framework (e.g., "React", "Vue", "HTML/CSS")'),
+});
+
+// Create server instance
+const server = new Server(
+  {
+    name: 'mcp-hydrocoder-vision',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Tool handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'analyzeImage': {
+        const validated = AnalyzeImageInputSchema.parse(args);
+        const mimeType = getMimeType(validated.imagePath);
+        const imageData = await fileToBase64(validated.imagePath);
+        const prompt = validated.prompt || 'Describe this image in detail.';
+
+        const result = await analyzeImageWithLMStudio(imageData, mimeType, prompt);
+        return {
+          content: [{ type: 'text', text: result }],
+        };
+      }
+
+      case 'extractText': {
+        const validated = ExtractTextInputSchema.parse(args);
+        const mimeType = getMimeType(validated.imagePath);
+        const imageData = await fileToBase64(validated.imagePath);
+        const prompt = validated.language
+          ? `Extract all text from this image. The text is in ${validated.language}.`
+          : 'Extract all text from this image (OCR).';
+
+        const result = await analyzeImageWithLMStudio(imageData, mimeType, prompt);
+        return {
+          content: [{ type: 'text', text: result }],
+        };
+      }
+
+      case 'describeForCode': {
+        const validated = DescribeForCodeInputSchema.parse(args);
+        const mimeType = getMimeType(validated.imagePath);
+        const imageData = await fileToBase64(validated.imagePath);
+        const framework = validated.framework || 'HTML/CSS/JavaScript';
+        const prompt = `Analyze this UI/design image and generate ${framework} code that replicates it. Focus on structure, styling, and layout.`;
+
+        const result = await analyzeImageWithLMStudio(imageData, mimeType, prompt);
+        return {
+          content: [{ type: 'text', text: result }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(', ')}`);
+    }
+    throw error;
+  }
+});
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'analyzeImage',
+        description: 'Analyze an image and return a detailed description. Uses local Qwen3 VL 4B model via LM Studio.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            imagePath: {
+              type: 'string',
+              description: 'Path to the image file to analyze',
+            },
+            prompt: {
+              type: 'string',
+              description: 'Optional analysis prompt (default: "Describe this image in detail")',
+            },
+          },
+          required: ['imagePath'],
+        },
+      },
+      {
+        name: 'extractText',
+        description: 'Extract text from an image (OCR). Supports multiple languages.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            imagePath: {
+              type: 'string',
+              description: 'Path to the image file containing text',
+            },
+            language: {
+              type: 'string',
+              description: 'Expected language of the text (optional)',
+            },
+          },
+          required: ['imagePath'],
+        },
+      },
+      {
+        name: 'describeForCode',
+        description: 'Analyze a UI/design image and generate corresponding code (HTML/CSS/JS, Vue, React, etc.).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            imagePath: {
+              type: 'string',
+              description: 'Path to the UI/design image',
+            },
+            framework: {
+              type: 'string',
+              description: 'Target framework (e.g., "React", "Vue", "HTML/CSS")',
+            },
+          },
+          required: ['imagePath'],
+        },
+      },
+    ],
+  };
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP HydroCoder Vision Server running on stdio');
+  console.error(`LM Studio URL: ${LM_STUDIO_URL}`);
+  console.error(`Model: ${DEFAULT_MODEL}`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});