AI导哈

图像摘要MCP服务器

一个接受图像文件并将其发送到OpenAI兼容的聊天完成端点进行分析、描述和比较任务的模型上下文协议（MCP）服务器。

  • by jettoblack
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 jettoblack/image_mcp

使用说明

图像摘要MCP服务器

一种模型上下文协议（MCP）服务器，接受图像文件并将其发送到与OpenAI兼容的聊天完成端点，以进行分析、描述和比较任务。

用例

许多用于代理编码的LLM仅支持文本，缺乏对图像输入的支持。此工具允许您使用专门用于描述和分析图像的辅助模型，而无需为您的主模型使用多模态LLM。它通过任何支持OpenAI聊天完成端点的服务器（包括llama.cp/llama swap、Ollama、openwebui、OpenRouter等）支持云和本地LLM。

对于本地型号，gemma3:4b-it-qat运行良好，占用空间相对较小，性能快速（即使仅在CPU上）。

特性

  • 通过统一接收图像 image_url 具有多种输入格式的参数
  • 支持 custom_prompt 执行除一般描述之外的特定任务
  • 将图像发送到OpenAI兼容的聊天完成端点
  • 返回详细的图像描述
  • 可配置的端点URL、API密钥和模型
  • 配置命令行界面
  • 全面的错误处理

从NPM快速安装

将此添加到您的全局 mcp_settings.json 或项目 mcp.json:

  "image_summarization": {
    "command": "npx",
    "args": [
      "-y",
      "@jettoblack/image_mcp",
      "--api-key",
      "key",
      "--base-url",
      "http://localhost:8080/v1",
      "--model",
      "gemma3:4b-it-qat"
    ]
  }

至少，配置基本url、API密钥和模型以指向您选择的服务器。

对于慢速本地模型，您可能还需要增加超时和最大重试设置。

配置

MCP服务器可以使用环境变量或命令行参数进行配置。

环境变量

  • OPENAI_API_KEY：OpenAI兼容服务的API密钥
  • OPENAI_BASE_URL：OpenAI兼容服务的基本URL（默认值： http://localhost:9292/v1)
  • OPENAI_MODEL：用于图像分析的模型
  • OPENAI_TIMEOUT：请求超时（毫秒）（默认值：60000）。运行本地模型时，您可能需要增加此值。
  • OPENAI_MAX_RETRIES：最大重试次数（默认值：3）

命令行参数

npx -y @jettoblack/image_mcp \
  --api-key your-api-key \
  --base-url https://api.openai.com/v1 \
  --model gpt-4-vision-preview \
  --timeout 60000 \
  --max-retries 5

配置优先

  1. 命令行参数
  2. 环境变量
  3. 默认值

用法

MCP工具

服务器提供两种图像分析工具：

summarize_image

详细分析和描述单个图像。

参数

  • image_url （string）：要分析的图像文件的URL。支持：
    • 绝对文件路径
    • 文件：//URL
    • HTTP/HTTPS URL（将被下载并转换为base64）
    • 带有base64编码图像文件的数据URL
  • custom_prompt （字符串，可选）：使用自定义提示代替默认图像描述提示

示例用法

使用文件路径：

{
  "name": "summarize_image",
  "arguments": {
    "image_url": "/path/to/your/image.jpg"
  }
}

使用文件：//URL:

{
  "name": "summarize_image",
  "arguments": {
    "image_url": "file:///path/to/your/image.jpg"
  }
}

使用HTTP/HTTPS URL：

{
  "name": "summarize_image",
  "arguments": {
    "image_url": "https://example.com/image.jpg"
  }
}

使用base64的数据URL：

{
  "name": "summarize_image",
  "arguments": {
    "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

使用自定义提示：

{
  "name": "summarize_image",
  "arguments": {
    "image_url": "/path/to/your/image.jpg",
    "custom_prompt": "What objects are visible in this image?"
  }
}

compare_images

比较2个或多个图像，并描述它们的异同。

参数
  • image_urls （字符串数组）：要比较的图像URL数组（至少需要2个图像）。每个URL支持：
    • 绝对文件路径
    • 文件：//URL
    • HTTP/HTTPS URL（将被下载并转换为base64）
    • 带有base64编码图像文件的数据URL
  • custom_prompt （字符串，可选）：使用自定义提示代替默认图像比较提示
示例用法

比较两张图片：

{
  "name": "compare_images",
  "arguments": {
    "image_urls": [
      "/path/to/image1.jpg",
      "/path/to/image2.jpg"
    ]
  }
}

使用自定义提示比较多个图像：

{
  "name": "compare_images",
  "arguments": {
    "image_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "custom_prompt": "Compare these UI screenshots and describe the differences in color themes."
  }
}

开发人员设置

  1. 克隆存储库：
git clone https://github.com/jettoblack/image_mcp.git
cd image_mcp
  1. 安装依赖项：
npm install
  1. 构建项目：
npm run build
  1. 启动服务器
node build/index.js

服务器将启动并监听stdio上的MCP协议通信。

MCP工具安装（本地开发构建）

将此添加到您的全局mcp_settings.json或项目mcp.json中：

  "image_summarizer": {
    "command": "node",
    "args": [
      "/path/to/image_mcp/build/index.js",
      "--api-key",
      "key",
      "--base-url",
      "http://localhost:9292/v1",
      "--model",
      "gemma3:4b-it-qat"
    ]
  }

测试

运行测试

运行测试套件：

npm test

测试套件包括：

  • 图像处理功能的单元测试
  • 需要模拟服务器的集成测试
  • 两者的测试 summarize_image 和 compare_images 工具

模拟服务器测试

该项目包括一个用于测试目的的模拟OpenAI兼容服务器。

  1. 在单独的终端中启动模拟服务器：
node tests/mock-server.js

模拟服务器将启动 http://localhost:9293 并为以下对象提供端点：

  • GET /v1/models -列出可用型号
  • POST /v1/chat/completions -支持图像的模拟聊天完成
  • POST /v1/test/image-process -图像处理验证的测试端点
  1. 为模拟服务器设置环境变量：
export OPENAI_BASE_URL=http://localhost:9293/v1
export OPENAI_API_KEY=test-key
export OPENAI_MODEL=test-model-vision
  1. 运行集成测试：
npm test tests/integration.test.ts

真正的OpenAI兼容服务器测试

要使用真正的OpenAI兼容端点进行测试：

  1. 设置环境变量：
export OPENAI_API_KEY=your-actual-api-key
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_MODEL=gpt-4-vision-preview

或者对于其他与OpenAI兼容的服务：

export OPENAI_API_KEY=your-service-api-key
export OPENAI_BASE_URL=https://your-service-endpoint/v1
export OPENAI_MODEL=your-vision-model
  1. 启动MCP服务器：
node build/index.js
  1. 使用MCP客户端发送测试请求或直接测试工具。

手动测试

您可以使用以下工具手动测试MCP服务器 curl 或MCP客户端：

# Test with a local image file
curl -X POST http://localhost:8080/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "summarize_image",
      "arguments": {
        "image_url": "/path/to/your/test/image.jpg"
      }
    }
  }'

api参考

OpenAI兼容的API集成

服务器向OpenAI兼容的聊天完成端点发送请求，其结构如下：

{
  "model": "your-model",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe this image in detail, including all text."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,..."
          }
        }
      ]
    }
  ],
  "stream": false
}

支持的图像格式

  • JPEG（.jpg、.JPEG）
  • PNG（.PNG）
  • GIF（.GIF）
  • WebP（.WebP）
  • SVG（.SVG）
  • BMP（.BMP）
  • TIFF（.TIFF）

错误处理

该服务器包括全面的错误处理功能，用于：

  • 图像文件无效
  • 不支持的图像格式
  • 缺少API密钥
  • 网络连接问题
  • API响应错误

发展

项目结构

src/
├── config.ts          # Configuration management
├── image-processor.ts # Image processing utilities
├── index.ts          # Main MCP server
└── openai-client.ts  # OpenAI-compatible API client

建筑

npm run build

测试

npm test

许可证

该项目根据MIT许可证获得许可。

贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

支持

有关问题和疑问，请在GitHub存储库上打开问题。

提示

提示/捐款总是很感激，以帮助资助未来的发展。

相关 MCP