luma-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jochen
+
+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,328 @@
+# Luma MCP
+
+基于智谱 GLM-4.5V 的视觉理解 MCP 服务器，为不支持图片理解的 AI 助手提供视觉能力。
+
+[English](./docs/README_EN.md) | 中文
+
+## 特性
+
+- **简单设计**: 单一 `analyze_image` 工具处理所有图片分析任务
+- **智能理解**: 自动识别代码、UI、错误等不同场景
+- **全面支持**: 代码截图、界面设计、错误诊断、通用图片
+- **标准 MCP 协议**: 无缝集成 Claude Desktop、Cline 等 MCP 客户端
+- **GLM-4.5V 驱动**: 中文理解优秀，API 性价比高
+- **URL 支持**: 支持本地文件和远程图片 URL
+- **重试机制**: 内置指数退避重试，提高可靠性
+- **思考模式**: 默认启用深度分析
+
+## 快速开始
+
+### 前置要求
+
+- Node.js >= 18.0.0
+- 智谱 AI API Key ([获取地址](https://open.bigmodel.cn/))
+
+### 安装
+
+#### 方式 1: 本地开发（推荐用于测试）
+
+```bash
+git clone https://github.com/JochenYang/luma-mcp.git
+cd luma-mcp
+npm install
+npm run build
+```
+
+#### 方式 2: 使用 npx（需要先发布到 npm）
+
+```bash
+npx luma-mcp
+```
+
+### 配置
+
+#### Claude Desktop
+
+**Windows 配置文件位置**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**macOS 配置文件位置**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**使用 npx（推荐）**:
+
+```json
+{
+  "mcpServers": {
+    "luma": {
+      "command": "npx",
+      "args": ["-y", "luma-mcp"],
+      "env": {
+        "ZHIPU_API_KEY": "your-zhipu-api-key"
+      }
+    }
+  }
+}
+```
+
+**本地开发**:
+
+```json
+{
+  "mcpServers": {
+    "luma": {
+      "command": "node",
+      "args": ["D:\\codes\\Luma_mcp\\build\\index.js"],
+      "env": {
+        "ZHIPU_API_KEY": "your-zhipu-api-key"
+      }
+    }
+  }
+}
+```
+
+配置完成后重启 Claude Desktop。
+
+#### Cline (VSCode)
+
+**使用 npx（推荐）**:
+
+在项目根目录或 `.vscode/` 目录下创建 `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "luma": {
+      "command": "npx",
+      "args": ["-y", "luma-mcp"],
+      "env": {
+        "ZHIPU_API_KEY": "your-zhipu-api-key"
+      }
+    }
+  }
+}
+```
+
+**本地开发**:
+
+```json
+{
+  "mcpServers": {
+    "luma": {
+      "command": "node",
+      "args": ["D:\\codes\\Luma_mcp\\build\\index.js"],
+      "env": {
+        "ZHIPU_API_KEY": "your-zhipu-api-key"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code (命令行)
+
+```bash
+claude mcp add -s user luma-mcp --env ZHIPU_API_KEY=your-api-key -- npx -y luma-mcp
+```
+
+#### 其他工具
+
+更多 MCP 客户端配置方法请参考[智谱官方文档](https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server#claude-code)
+
+## 使用方法
+
+### 重要提示
+
+**MCP 工具调用机制**:
+- MCP 工具需要 AI 模型**主动调用**才会执行
+- 如果使用的 AI 模型本身支持视觉（如 Claude 4.5 Sonnet），它会优先使用自己的视觉能力
+- Luma MCP 主要服务于**不支持视觉的模型**（如 GPT-4、Claude Opus 等文本模型）
+
+**如何确保工具被调用**:
+1. 明确提及工具：`使用 Luma 分析这张图片`
+2. 提供图片路径：`请分析 ./screenshot.png 中的代码错误`
+3. 使用工具名称：`用 analyze_image 工具查看这张图片`
+
+**注意**: 直接在聊天框粘贴图片，非视觉模型不会自动调用 Luma，需要明确指示。
+
+### 在 Claude Desktop 中使用
+
+配置完成后，在 Claude 对话中可以这样使用：
+
+**推荐用法（明确指示）**:
+```
+用户: 使用 Luma 分析 ./code-error.png，这段代码为什么报错？
+Claude: [调用 Luma 分析图片，返回详细分析]
+```
+
+**或提供图片路径**:
+```
+用户: 请分析 https://example.com/screenshot.jpg 中的界面问题
+Claude: [自动调用 analyze_image 工具]
+```
+
+### 本地测试
+
+不需要 MCP 客户端即可测试：
+
+```bash
+# 设置 API Key
+export ZHIPU_API_KEY="your-api-key"  # macOS/Linux
+$env:ZHIPU_API_KEY="your-api-key"    # Windows PowerShell
+
+# 测试本地图片
+npm run test:local ./test.png
+
+# 测试并提问
+npm run test:local ./code-error.png "这段代码有什么问题？"
+
+# 测试远程URL
+npm run test:local https://example.com/image.jpg
+```
+
+## 工具说明
+
+### analyze_image
+
+分析图片内容的通用工具。
+
+**参数**:
+
+- `image_source` (必需): 图片路径或 URL
+  - 支持格式: JPG, PNG, WebP, GIF
+  - 本地文件: 绝对路径或相对路径
+  - 远程图片: https:// 开头的 URL
+- `question` (可选): 关于图片的问题或分析指令
+
+**示例**:
+
+```typescript
+// 通用分析
+analyze_image({
+  image_source: "./screenshot.png"
+})
+
+// 代码分析
+analyze_image({
+  image_source: "./code-error.png",
+  question: "这段代码为什么报错？请提供修复建议"
+})
+
+// UI 分析
+analyze_image({
+  image_source: "https://example.com/ui.png",
+  question: "分析这个界面的布局和可用性问题"
+})
+```
+
+## 环境变量
+
+| 变量名                  | 必需 | 默认值     | 说明                 |
+|-------------------------|------|------------|----------------------|
+| `ZHIPU_API_KEY`         | 是   | -          | 智谱 AI 的 API 密钥  |
+| `ZHIPU_MODEL`           | 否   | `glm-4.5v` | 使用的模型           |
+| `ZHIPU_MAX_TOKENS`      | 否   | `4096`     | 最大生成 tokens      |
+| `ZHIPU_TEMPERATURE`     | 否   | `0.7`      | 温度参数 (0-1)       |
+| `ZHIPU_TOP_P`           | 否   | `0.7`      | Top-p 参数 (0-1)     |
+| `ZHIPU_ENABLE_THINKING` | 否   | `false`    | 是否强制启用思考模式 |
+
+注意: 思考模式默认已启用，无需额外配置。
+
+## 开发
+
+```bash
+# 开发模式（监听文件变化）
+npm run watch
+
+# 构建
+npm run build
+
+# 本地测试
+npm run test:local <图片路径> [问题]
+```
+
+## 项目结构
+
+```
+luma-mcp/
+├── src/
+│   ├── index.ts              # MCP 服务器入口
+│   ├── config.ts             # 配置管理
+│   ├── zhipu-client.ts       # GLM-4.5V API 客户端
+│   ├── image-processor.ts    # 图片处理
+│   ├── prompts.ts            # 提示词模板
+│   └── utils/
+│       ├── logger.ts         # 日志工具
+│       └── helpers.ts        # 工具函数
+├── test/
+│   └── test-local.ts         # 本地测试脚本
+├── docs/
+│   ├── design.md             # 设计文档
+│   ├── installation.md       # 安装指南
+│   └── README_EN.md          # 英文文档
+├── build/                    # 编译输出
+└── package.json
+```
+
+## 常见问题
+
+### 如何获取 API Key？
+
+1. 访问 [智谱开放平台](https://open.bigmodel.cn/)
+2. 注册/登录账号
+3. 进入控制台创建 API Key
+4. 复制 API Key 到配置文件
+
+### 支持哪些图片格式？
+
+支持 JPG、PNG、WebP、GIF 格式。建议使用 JPG 格式以获得更好的压缩率。
+
+### 图片大小限制？
+
+- 最大文件大小: 10MB
+- 超过 2MB 的图片会自动压缩
+- 推荐分辨率: 800-2048 像素
+
+### 如何查看日志？
+
+日志文件位置: `~/.luma-mcp/luma-mcp-YYYY-MM-DD.log`
+
+### API 调用失败怎么办？
+
+1. 检查 API Key 是否正确
+2. 确认智谱账户余额充足
+3. 检查网络连接
+4. 查看日志文件了解详细错误信息
+
+### 成本如何？
+
+GLM-4.5V 定价请参考[智谱官方定价](https://open.bigmodel.cn/pricing)。
+
+典型场景估算:
+- 简单图片理解: 500-1000 tokens
+- 代码截图分析: 1500-2500 tokens
+- 详细 UI 分析: 2000-3000 tokens
+
+启用思考模式会增加约 20-30% tokens。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT License
+
+## 相关链接
+
+- [智谱 AI 开放平台](https://open.bigmodel.cn/)
+- [GLM-4.5V 文档](https://docs.bigmodel.cn/cn/guide/models/vlm/glm-4.5v)
+- [MCP 协议文档](https://modelcontextprotocol.io/)
+- [设计文档](./docs/design.md)
+- [安装配置指南](./docs/installation.md)
+
+## 作者
+
+Jochen
+
+---
+
+**注意**: 请勿在公开仓库中提交包含真实 API Key 的配置文件。

package/build/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 配置管理模块
+ * 从环境变量读取配置
+ */
+export interface LumaConfig {
+    apiKey: string;
+    model: string;
+    maxTokens: number;
+    temperature: number;
+    topP: number;
+    enableThinking: boolean;
+}
+/**
+ * 从环境变量加载配置
+ */
+export declare function loadConfig(): LumaConfig;
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAevC"}

package/build/config.js

@@ -0,0 +1,22 @@
+/**
+ * 配置管理模块
+ * 从环境变量读取配置
+ */
+/**
+ * 从环境变量加载配置
+ */
+export function loadConfig() {
+    const apiKey = process.env.ZHIPU_API_KEY;
+    if (!apiKey) {
+        throw new Error('ZHIPU_API_KEY environment variable is required');
+    }
+    return {
+        apiKey,
+        model: process.env.ZHIPU_MODEL || 'glm-4.5v',
+        maxTokens: parseInt(process.env.ZHIPU_MAX_TOKENS || '4096', 10),
+        temperature: parseFloat(process.env.ZHIPU_TEMPERATURE || '0.7'),
+        topP: parseFloat(process.env.ZHIPU_TOP_P || '0.7'),
+        enableThinking: process.env.ZHIPU_ENABLE_THINKING === 'true',
+    };
+}
+//# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAEzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,OAAO;QACL,MAAM;QACN,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,UAAU;QAC5C,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,MAAM,EAAE,EAAE,CAAC;QAC/D,WAAW,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,KAAK,CAAC;QAC/D,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,KAAK,CAAC;QAClD,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,MAAM;KAC7D,CAAC;AACJ,CAAC"}

package/build/image-processor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 图片处理工具
+ * 负责读取、压缩和编码图片
+ * 支持本地文件和远程URL
+ */
+/**
+ * 验证图片来源（文件或URL）
+ */
+export declare function validateImageSource(imageSource: string, maxSizeMB?: number): Promise<void>;
+/**
+ * 将图片转换为 base64 data URL 或返回URL
+ */
+export declare function imageToBase64(imagePath: string): Promise<string>;
+//# sourceMappingURL=image-processor.d.ts.map

package/build/image-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-processor.d.ts","sourceRoot":"","sources":["../src/image-processor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BpG;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBtE"}

package/build/image-processor.js

@@ -0,0 +1,97 @@
+/**
+ * 图片处理工具
+ * 负责读取、压缩和编码图片
+ * 支持本地文件和远程URL
+ */
+import { readFile, stat } from 'fs/promises';
+import sharp from 'sharp';
+import { isUrl } from './utils/helpers.js';
+import { logger } from './utils/logger.js';
+/**
+ * 验证图片来源（文件或URL）
+ */
+export async function validateImageSource(imageSource, maxSizeMB = 10) {
+    // 如果是URL，直接返回
+    if (isUrl(imageSource)) {
+        logger.debug('Image source is URL, skipping validation', { imageSource });
+        return;
+    }
+    // 验证本地文件
+    try {
+        const stats = await stat(imageSource);
+        const fileSizeMB = stats.size / (1024 * 1024);
+        if (fileSizeMB > maxSizeMB) {
+            throw new Error(`Image file too large: ${fileSizeMB.toFixed(2)}MB (max: ${maxSizeMB}MB)`);
+        }
+        // 验证文件格式
+        const ext = imageSource.toLowerCase().split('.').pop();
+        const supportedFormats = ['jpg', 'jpeg', 'png', 'webp', 'gif'];
+        if (!ext || !supportedFormats.includes(ext)) {
+            throw new Error(`Unsupported image format: ${ext}. Supported: ${supportedFormats.join(', ')}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Image file not found: ${imageSource}`);
+        }
+        throw error;
+    }
+}
+/**
+ * 将图片转换为 base64 data URL 或返回URL
+ */
+export async function imageToBase64(imagePath) {
+    try {
+        // 如果是URL，直接返回
+        if (isUrl(imagePath)) {
+            logger.info('Using remote image URL', { url: imagePath });
+            return imagePath;
+        }
+        // 本地文件：读取并编码
+        let imageBuffer = await readFile(imagePath);
+        // 检查文件大小，如果超过 2MB 则压缩
+        if (imageBuffer.length > 2 * 1024 * 1024) {
+            logger.info('Compressing large image', { originalSize: `${(imageBuffer.length / (1024 * 1024)).toFixed(2)}MB` });
+            imageBuffer = Buffer.from(await compressImage(imageBuffer));
+        }
+        // 转换为 base64
+        const base64 = imageBuffer.toString('base64');
+        const mimeType = getMimeType(imagePath);
+        return `data:${mimeType};base64,${base64}`;
+    }
+    catch (error) {
+        throw new Error(`Failed to process image: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * 压缩图片
+ */
+async function compressImage(imageBuffer) {
+    return sharp(imageBuffer)
+        .resize(2048, 2048, {
+        fit: 'inside',
+        withoutEnlargement: true
+    })
+        .jpeg({ quality: 85 })
+        .toBuffer();
+}
+/**
+ * 根据文件扩展名获取 MIME 类型
+ */
+function getMimeType(filePath) {
+    const ext = filePath.toLowerCase().split('.').pop();
+    switch (ext) {
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'png':
+            return 'image/png';
+        case 'webp':
+            return 'image/webp';
+        case 'gif':
+            return 'image/gif';
+        default:
+            return 'image/jpeg'; // 默认使用 jpeg
+    }
+}
+//# sourceMappingURL=image-processor.js.map

package/build/image-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-processor.js","sourceRoot":"","sources":["../src/image-processor.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Luma MCP Server
+ * 视觉理解 MCP 服务器，powered by GLM-4.5V
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/build/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Luma MCP Server
+ * 视觉理解 MCP 服务器，powered by GLM-4.5V
+ */
+// 第一件事：重定向console到stderr，避免污染MCP的stdout
+import { setupConsoleRedirection, logger } from './utils/logger.js';
+setupConsoleRedirection();
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig } from './config.js';
+import { ZhipuClient } from './zhipu-client.js';
+import { imageToBase64, validateImageSource } from './image-processor.js';
+import { buildAnalysisPrompt } from './prompts.js';
+import { withRetry, createSuccessResponse, createErrorResponse } from './utils/helpers.js';
+/**
+ * 创建 MCP 服务器
+ */
+async function createServer() {
+    logger.info('Initializing Luma MCP Server');
+    // 加载配置
+    const config = loadConfig();
+    const zhipuClient = new ZhipuClient(config);
+    // 创建服务器 - 使用 McpServer
+    const server = new McpServer({
+        name: 'luma-mcp',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // 创建带重试的分析函数
+    const analyzeWithRetry = withRetry(async (imageSource, question) => {
+        // 1. 验证图片来源
+        await validateImageSource(imageSource);
+        // 2. 处理图片（读取或返回URL）
+        const imageDataUrl = await imageToBase64(imageSource);
+        // 3. 构建提示词
+        const prompt = buildAnalysisPrompt(question);
+        // 4. 调用 GLM-4.5V 分析图片
+        return await zhipuClient.analyzeImage(imageDataUrl, prompt);
+    }, 2, // 最多重试2次
+    1000 // 初始延迟1秒
+    );
+    // 注册工具 - 使用 McpServer.tool() API
+    server.tool('analyze_image', `使用智谱GLM-4.5V视觉模型分析图片内容。
+
+**何时自动调用此工具**：
+1. 用户提供了图片文件路径（包括临时路径、相对路径、绝对路径）
+2. 用户提供了图片URL（https://开头）
+3. 用户粘贴了图片到聊天框（会生成临时路径）
+4. 用户要求分析、理解、查看、识别图片内容
+5. 用户询问关于图片中的代码、UI、错误信息等问题
+
+**支持场景**：代码截图、UI界面、错误信息、通用图片分析。
+**支持格式**：JPG、PNG、WebP、GIF。
+**支持来源**：本地文件、远程URL、临时文件（包括截图）。
+
+如果你是不支持视觉的AI模型，看到图片路径时应主动调用此工具来分析图片内容。`, {
+        image_source: z.string().describe('图片来源：本地文件路径（含临时路径）或远程URL。例如："./image.png"、"/tmp/screenshot.png"、"C:\\Users\\...\\image.jpg"、"https://example.com/pic.jpg"'),
+        question: z.string().optional().describe('可选：用户的问题或分析指令。例如："这段代码为什么报错？"、"分析这个UI设计的问题"、"识别图片中的文字"'),
+    }, async (params) => {
+        try {
+            logger.info('Analyzing image', {
+                source: params.image_source,
+                hasQuestion: !!params.question,
+            });
+            // 执行分析（带重试）
+            const result = await analyzeWithRetry(params.image_source, params.question);
+            logger.info('Image analysis completed successfully');
+            return createSuccessResponse(result);
+        }
+        catch (error) {
+            logger.error('Image analysis failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return createErrorResponse(error instanceof Error ? error.message : 'Unknown error');
+        }
+    });
+    return server;
+}
+/**
+ * 主函数
+ */
+async function main() {
+    try {
+        const server = await createServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logger.info('Luma MCP server started successfully on stdio');
+    }
+    catch (error) {
+        logger.error('Failed to start Luma MCP server', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+    }
+}
+// 全局错误处理
+process.on('uncaughtException', (error) => {
+    logger.error('Uncaught exception', { error: error.message, stack: error.stack });
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled rejection', { reason });
+    process.exit(1);
+});
+process.on('SIGINT', () => {
+    logger.info('Received SIGINT, shutting down gracefully');
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    logger.info('Received SIGTERM, shutting down gracefully');
+    process.exit(0);
+});
+main();
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/prompts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 提示词模板
+ * 参考 Claude Sonnet 4.5 的视觉理解方法
+ */
+/**
+ * 构建图片分析提示词
+ */
+export declare function buildAnalysisPrompt(question?: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/build/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAkC7D"}

package/build/prompts.js

@@ -0,0 +1,44 @@
+/**
+ * 提示词模板
+ * 参考 Claude Sonnet 4.5 的视觉理解方法
+ */
+/**
+ * 构建图片分析提示词
+ */
+export function buildAnalysisPrompt(question) {
+    if (question) {
+        // 有用户问题时，直接回答问题
+        return `
+<image_analysis>
+请仔细观察这张图片，并回答以下问题：
+
+${question}
+
+分析要求：
+1. 系统性观察：从整体到细节，全面观察图片内容
+2. 准确识别：精确识别所有文字、符号、代码、数字等
+3. 结构化输出：使用清晰的标题和列表组织信息
+4. 中文表达：使用清晰准确的中文描述
+5. 具体可执行：如果涉及代码或问题，提供具体的解决方案
+
+请开始分析：
+</image_analysis>
+`.trim();
+    }
+    else {
+        // 没有问题时，通用描述
+        return `
+<image_analysis>
+请详细描述这张图片的内容，包括：
+
+1. **主要内容**：图片展示了什么
+2. **关键元素**：重要的视觉元素、文字、符号
+3. **布局结构**：元素的组织和排列
+4. **文字内容**：提取所有可见文字
+
+请用中文清晰描述。
+</image_analysis>
+`.trim();
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/build/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,gBAAgB;QAChB,OAAO;;;;EAIT,QAAQ;;;;;;;;;;;CAWT,CAAC,IAAI,EAAE,CAAC;IACP,CAAC;SAAM,CAAC;QACN,aAAa;QACb,OAAO;;;;;;;;;;;CAWV,CAAC,IAAI,EAAE,CAAC;IACP,CAAC;AACH,CAAC"}

package/build/utils/helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 工具函数
+ */
+/**
+ * 带重试机制的异步函数包装器
+ */
+export declare function withRetry<T>(fn: (...args: any[]) => Promise<T>, maxRetries?: number, initialDelay?: number): (...args: any[]) => Promise<T>;
+/**
+ * 检查字符串是否为 URL
+ */
+export declare function isUrl(source: string): boolean;
+/**
+ * 创建成功响应
+ */
+export declare function createSuccessResponse(data: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * 创建错误响应
+ */
+export declare function createErrorResponse(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+//# sourceMappingURL=helpers.d.ts.map

package/build/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,UAAU,GAAE,MAAU,EACtB,YAAY,GAAE,MAAa,GAC1B,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAsBhC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAO7C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM;;;;;EAIjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM;;;;;;EAKlD"}

package/build/utils/helpers.js

@@ -0,0 +1,56 @@
+/**
+ * 工具函数
+ */
+/**
+ * 带重试机制的异步函数包装器
+ */
+export function withRetry(fn, maxRetries = 2, initialDelay = 1000) {
+    return async (...args) => {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn(...args);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (attempt === maxRetries) {
+                    throw lastError;
+                }
+                // 指数退避
+                const delay = initialDelay * Math.pow(2, attempt);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+        throw lastError;
+    };
+}
+/**
+ * 检查字符串是否为 URL
+ */
+export function isUrl(source) {
+    try {
+        const url = new URL(source);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 创建成功响应
+ */
+export function createSuccessResponse(data) {
+    return {
+        content: [{ type: 'text', text: data }],
+    };
+}
+/**
+ * 创建错误响应
+ */
+export function createErrorResponse(message) {
+    return {
+        content: [{ type: 'text', text: `错误: ${message}` }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/build/utils/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,EAAkC,EAClC,aAAqB,CAAC,EACtB,eAAuB,IAAI;IAE3B,OAAO,KAAK,EAAE,GAAG,IAAW,EAAc,EAAE;QAC1C,IAAI,SAAgB,CAAC;QAErB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YACvD,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAEtE,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;oBAC3B,MAAM,SAAS,CAAC;gBAClB,CAAC;gBAED,OAAO;gBACP,MAAM,KAAK,GAAG,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBAClD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QAED,MAAM,SAAU,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,MAAc;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;KACjD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,OAAO,EAAE,EAAE,CAAC;QAC5D,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/build/utils/logger.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 日志工具
+ * 将日志输出到 stderr，避免污染 MCP 的 stdout JSON 通信
+ */
+declare class Logger {
+    private logFilePath?;
+    constructor();
+    private initLogFile;
+    private write;
+    info(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+}
+export declare const logger: Logger;
+/**
+ * 重定向 console 到 logger，避免污染 stdout
+ */
+export declare function setupConsoleRedirection(): void;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/build/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,cAAM,MAAM;IACV,OAAO,CAAC,WAAW,CAAC,CAAS;;IAM7B,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,KAAK;IAkBb,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAIpC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAIrC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAIpC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;CAGtC;AAED,eAAO,MAAM,MAAM,QAAe,CAAC;AAEnC;;GAEG;AACH,wBAAgB,uBAAuB,SAMtC"}

package/build/utils/logger.js

@@ -0,0 +1,67 @@
+/**
+ * 日志工具
+ * 将日志输出到 stderr，避免污染 MCP 的 stdout JSON 通信
+ */
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+class Logger {
+    logFilePath;
+    constructor() {
+        this.initLogFile();
+    }
+    initLogFile() {
+        try {
+            const homeDir = homedir();
+            const now = new Date();
+            const dateStr = now.toISOString().split('T')[0]; // YYYY-MM-DD
+            const logDir = join(homeDir, '.luma-mcp');
+            mkdirSync(logDir, { recursive: true });
+            this.logFilePath = join(logDir, `luma-mcp-${dateStr}.log`);
+        }
+        catch (error) {
+            // 如果无法创建日志文件，只输出到 stderr
+            process.stderr.write(`[WARN] Failed to initialize log file: ${error}\n`);
+        }
+    }
+    write(level, message, ...args) {
+        const timestamp = new Date().toISOString();
+        const argsStr = args.length > 0 ? ` ${JSON.stringify(args)}` : '';
+        const logMessage = `[${timestamp}] ${level.toUpperCase()}: ${message}${argsStr}`;
+        // 输出到 stderr
+        process.stderr.write(logMessage + '\n');
+        // 写入日志文件
+        if (this.logFilePath) {
+            try {
+                appendFileSync(this.logFilePath, logMessage + '\n');
+            }
+            catch {
+                // 忽略文件写入错误
+            }
+        }
+    }
+    info(message, ...args) {
+        this.write('info', message, ...args);
+    }
+    error(message, ...args) {
+        this.write('error', message, ...args);
+    }
+    warn(message, ...args) {
+        this.write('warn', message, ...args);
+    }
+    debug(message, ...args) {
+        this.write('debug', message, ...args);
+    }
+}
+export const logger = new Logger();
+/**
+ * 重定向 console 到 logger，避免污染 stdout
+ */
+export function setupConsoleRedirection() {
+    console.log = logger.info.bind(logger);
+    console.info = logger.info.bind(logger);
+    console.error = logger.error.bind(logger);
+    console.warn = logger.warn.bind(logger);
+    console.debug = logger.debug.bind(logger);
+}
+//# sourceMappingURL=logger.js.map

package/build/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/build/zhipu-client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 智谱 GLM-4.5V API 客户端
+ */
+import type { LumaConfig } from './config.js';
+/**
+ * 智谱 API 客户端
+ */
+export declare class ZhipuClient {
+    private config;
+    private apiEndpoint;
+    constructor(config: LumaConfig);
+    /**
+     * 分析图片
+     */
+    analyzeImage(imageDataUrl: string, prompt: string, enableThinking?: boolean): Promise<string>;
+}
+//# sourceMappingURL=zhipu-client.d.ts.map

package/build/zhipu-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zhipu-client.d.ts","sourceRoot":"","sources":["../src/zhipu-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4C9C;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,WAAW,CAA2D;gBAElE,MAAM,EAAE,UAAU;IAI9B;;OAEG;IACG,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;CA2EpG"}

package/build/zhipu-client.js

@@ -0,0 +1,83 @@
+/**
+ * 智谱 GLM-4.5V API 客户端
+ */
+import axios from 'axios';
+import { logger } from './utils/logger.js';
+/**
+ * 智谱 API 客户端
+ */
+export class ZhipuClient {
+    config;
+    apiEndpoint = 'https://open.bigmodel.cn/api/paas/v4/chat/completions';
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * 分析图片
+     */
+    async analyzeImage(imageDataUrl, prompt, enableThinking) {
+        const requestBody = {
+            model: this.config.model,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'image_url',
+                            image_url: {
+                                url: imageDataUrl,
+                            },
+                        },
+                        {
+                            type: 'text',
+                            text: prompt,
+                        },
+                    ],
+                },
+            ],
+            temperature: this.config.temperature,
+            max_tokens: this.config.maxTokens,
+            top_p: this.config.topP,
+            thinking: { type: 'enabled' }, // 默认启用 thinking
+        };
+        // 允许显式禁用 thinking
+        if (enableThinking === false) {
+            delete requestBody.thinking;
+        }
+        logger.info('Calling GLM-4.5V API', {
+            model: this.config.model,
+            thinking: !!requestBody.thinking
+        });
+        try {
+            const response = await axios.post(this.apiEndpoint, requestBody, {
+                headers: {
+                    'Authorization': `Bearer ${this.config.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                timeout: 60000, // 60秒超时
+            });
+            if (!response.data.choices || response.data.choices.length === 0) {
+                throw new Error('No response from GLM-4.5V');
+            }
+            const result = response.data.choices[0].message.content;
+            const usage = response.data.usage;
+            logger.info('GLM-4.5V API call successful', {
+                tokens: usage?.total_tokens || 0,
+                model: response.data.model
+            });
+            return result;
+        }
+        catch (error) {
+            logger.error('GLM-4.5V API call failed', {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            if (axios.isAxiosError(error)) {
+                const message = error.response?.data?.error?.message || error.message;
+                const status = error.response?.status;
+                throw new Error(`GLM-4.5V API error (${status || 'unknown'}): ${message}`);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=zhipu-client.js.map

package/build/zhipu-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zhipu-client.js","sourceRoot":"","sources":["../src/zhipu-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "luma-mcp",
+  "version": "1.0.0",
+  "description": "A vision understanding MCP server powered by GLM-4.5V",
+  "type": "module",
+  "bin": {
+    "luma-mcp": "./build/index.js"
+  },
+  "main": "./build/index.js",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build",
+    "test:local": "tsx test/test-local.ts"
+  },
+  "keywords": [
+    "mcp",
+    "vision",
+    "ai",
+    "glm-4.5v",
+    "zhipu",
+    "image-understanding"
+  ],
+  "author": "Jochen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JochenYang/luma-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JochenYang/luma-mcp/issues"
+  },
+  "homepage": "https://github.com/JochenYang/luma-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "axios": "^1.7.9",
+    "sharp": "^0.33.5",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.7.2"
+  }
+}

package/test/test-local.ts

@@ -0,0 +1,88 @@
+/**
+ * Luma MCP 本地测试脚本
+ * 直接测试图片分析功能，不需要MCP客户端
+ */
+
+import { loadConfig } from '../src/config.js';
+import { ZhipuClient } from '../src/zhipu-client.js';
+import { imageToBase64, validateImageSource } from '../src/image-processor.js';
+import { buildAnalysisPrompt } from '../src/prompts.js';
+import { logger } from '../src/utils/logger.js';
+
+async function testImageAnalysis(imagePath: string, question?: string) {
+  console.log('\n==========================================');
+  console.log('🧪 测试 Luma MCP 图片分析');
+  console.log('==========================================\n');
+
+  try {
+    // 1. 加载配置
+    console.log('📝 加载配置...');
+    const config = loadConfig();
+    console.log(`✅ 配置加载成功: 模型 ${config.model}\n`);
+
+    // 2. 验证图片
+    console.log('🔍 验证图片来源...');
+    await validateImageSource(imagePath);
+    console.log(`✅ 图片验证通过: ${imagePath}\n`);
+
+    // 3. 处理图片
+    console.log('🖼️  处理图片...');
+    const imageDataUrl = await imageToBase64(imagePath);
+    const isUrl = imagePath.startsWith('http');
+    console.log(`✅ 图片处理完成: ${isUrl ? 'URL' : 'Base64编码'}\n`);
+
+    // 4. 构建提示词
+    console.log('💬 构建提示词...');
+    const prompt = buildAnalysisPrompt(question);
+    console.log(`✅ 提示词: ${question || '通用描述'}\n`);
+
+    // 5. 调用API
+    console.log('🤖 调用 GLM-4.5V API...');
+    const client = new ZhipuClient(config);
+    const result = await client.analyzeImage(imageDataUrl, prompt);
+
+    // 6. 显示结果
+    console.log('\n==========================================');
+    console.log('📊 分析结果');
+    console.log('==========================================\n');
+    console.log(result);
+    console.log('\n==========================================');
+    console.log('✅ 测试完成！');
+    console.log('==========================================\n');
+
+  } catch (error) {
+    console.error('\n❌ 测试失败:');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// 解析命令行参数
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log(`
+使用方法:
+  npm run test:local <图片路径或URL> [问题]
+
+示例:
+  # 分析本地图片
+  npm run test:local ./test.png
+
+  # 分析本地图片并提问
+  npm run test:local ./code-error.png "这段代码为什么报错？"
+
+  # 分析远程图片
+  npm run test:local https://example.com/image.jpg
+
+环境变量:
+  ZHIPU_API_KEY=your-api-key  # 必需
+  ZHIPU_MODEL=glm-4.5v        # 可选
+  `);
+  process.exit(1);
+}
+
+const imagePath = args[0];
+const question = args.slice(1).join(' ') || undefined;
+
+testImageAnalysis(imagePath, question);