npx -y luma-mcp

git clone https://github.com/JochenYang/luma-mcp.git
cd luma-mcp
npm install
npm run build

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": ["-y", "luma-mcp"],
      "env": {
        "MODEL_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "your-api-key"
      }
    }
  }
}

# Zhipu
claude mcp add -s user luma-mcp --env MODEL_PROVIDER=zhipu --env ZHIPU_API_KEY=your-api-key -- npx -y luma-mcp

# SiliconFlow
claude mcp add -s user luma-mcp --env MODEL_PROVIDER=siliconflow --env SILICONFLOW_API_KEY=your-api-key -- npx -y luma-mcp

# Qwen
claude mcp add -s user luma-mcp --env MODEL_PROVIDER=qwen --env DASHSCOPE_API_KEY=your-api-key -- npx -y luma-mcp

# Volcengine
claude mcp add -s user luma-mcp --env MODEL_PROVIDER=volcengine --env VOLCENGINE_API_KEY=your-api-key --env MODEL_NAME=doubao-seed-1-6-vision-250815 -- npx -y luma-mcp

# Hunyuan（新模型在腾讯云 TokenHub，旧混元平台模型已下线）
claude mcp add -s user luma-mcp --env MODEL_PROVIDER=hunyuan --env HUNYUAN_API_KEY=your-api-key --env MODEL_NAME=hy-vision-2.0-instruct -- npx -y luma-mcp

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["<项目路径>/build/index.js"],
      "env": {
        "MODEL_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "your-api-key"
      }
    }
  }
}

# 本地直接运行（HTTP 模式）
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_HTTP_TOKEN=your-token node build/index.js

docker build -t luma-mcp .
docker run -d --name luma-mcp -p 3000:3000 \
  -e MODEL_PROVIDER=zhipu \
  -e ZHIPU_API_KEY=your-api-key \
  -e MCP_HTTP_TOKEN=your-token \
  luma-mcp

{
  "mcpServers": {
    "luma": {
      "type": "http",
      "url": "http://<服务器IP>:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

claude mcp add -s user luma-mcp \
  --env MODEL_PROVIDER=custom \
  --env CUSTOM_API_KEY=sk-your-key \
  --env CUSTOM_BASE_URL=https://your-endpoint.com/v1 \
  --env CUSTOM_MODEL_NAME=your-model \
  -- npx -y luma-mcp

image_understand({
  image_source: "./screenshot.png",
  prompt: "分析这个页面的布局和主要组件结构",
  task_type: "ui",
});

image_understand({
  image_source: "./code-error.png",
  prompt: "这段代码为什么报错？请给出修复建议",
  // task_type 可省略，行为与旧版兼容
});

image_understand({
  image_source: "https://example.com/ui.png",
  prompt: "找出这个界面的可用性问题",
});

# 单元测试（不调用真实 API）
npm run test:unit

# MCP stdio 端到端测试（真实调用 image_understand）
npm run test:mcp

# MCP HTTP 传输测试（无需 API key）
npm run test:http

# 基础测试
npm run test:local ./test.png

# 带问题测试
npm run test:local ./code-error.png "这段代码为什么报错？"

# 远程图片测试
npm run test:local https://example.com/image.jpg

# 检查源码和测试脚本类型
npm run typecheck

luma-mcp/
├── src/
│   ├── index.ts                      # MCP 服务器入口，注册 image_understand
│   ├── http-server.ts                # Streamable HTTP 传输层（鉴权/会话/CORS）
│   ├── config.ts                     # 环境变量加载与校验
│   ├── constants.ts                  # 默认视觉提示词等常量
│   ├── task-types.ts                 # 可选 task_type 路由
│   ├── vision-client.ts              # 视觉模型客户端接口
│   ├── openai-compatible-client.ts   # OpenAI 兼容请求基类
│   ├── zhipu-client.ts               # GLM-4.6V 客户端
│   ├── siliconflow-client.ts         # DeepSeek-OCR 客户端
│   ├── qwen-client.ts                # Qwen3-VL 客户端
│   ├── volcengine-client.ts          # Doubao-Seed-1.6 客户端
│   ├── hunyuan-client.ts             # Hunyuan-Vision 客户端
│   ├── custom-client.ts              # 任意 OpenAI 兼容端点
│   ├── image-processor.ts            # 图片预处理、压缩、多裁剪
│   └── utils/
│       ├── helpers.ts                # 重试、响应格式化、错误脱敏
│       └── logger.ts                 # 日志
├── test/
│   ├── test-local.ts                 # 本地单图/多图测试
│   ├── test-qwen.ts                  # Qwen 客户端测试
│   ├── test-deepseek-raw.ts          # DeepSeek-OCR 原始调用测试
│   ├── test-data-uri.ts              # Data URI 处理测试
│   ├── test-custom.ts                # CustomClient 单元测试
│   ├── test-task-types.ts            # task_type 路由测试
│   ├── test-mcp-stdio.ts             # MCP stdio 端到端测试
│   ├── test-mcp-http.ts              # MCP HTTP 传输测试（无需 API key）
│   └── image-processor-regression.ts # 图片处理回归测试
├── Dockerfile                        # HTTP 模式容器化部署
├── vision-skill/                     # 轻量识图 skill（无 MCP 用户的替代方案）
│   ├── SKILL.md                      # skill 定义：/skill luma-vision 激活
│   └── scripts/vision.js             # 零依赖识图脚本，直连视觉模型 API
├── docs/
│   └── README_EN.md
├── build/                            # 编译产物
├── package.json
└── tsconfig.json

npm run watch
npm run build
npm run typecheck