JinDaGe - image-recognition-mcp MCP Details

article

README

🚀 图像识别MCP服务器

本项目是一个基于模型上下文协议（MCP）的服务器，借助与OpenAI兼容的视觉模型，提供由人工智能驱动的图像识别和描述功能。它允许AI助手通过简单的基于URL的接口分析和描述图像，支持OpenAI的视觉模型以及兼容OpenAI的本地模型（如LM Studio、Ollama等），能为图像提供详细描述，方便将图像分析能力集成到AI工作流程中。

🚀 快速开始

本MCP服务器使AI助手能够通过简单的基于URL的接口分析和描述图像。它支持OpenAI的视觉模型以及兼容OpenAI的本地模型（如LM Studio、Ollama等），提供图像的详细描述，便于将图像分析功能集成到你的AI工作流程中。

✨ 主要特性

图像分析：通过URL分析图像并获取详细描述。
灵活的模型支持：可与OpenAI的视觉模型以及兼容OpenAI的本地模型（如LM Studio、Ollama等）配合使用。
MCP协议：完全兼容模型上下文协议标准。
TypeScript构建：采用TypeScript构建，确保类型安全，提供更好的开发体验。
简单的API：提供易于使用的接口，用于请求图像描述。

📦 安装指南

前提条件

Node.js 18+
npm 或 yarn
OpenAI API密钥或本地视觉模型服务器（如LM Studio、Ollama）

MCP客户端配置

要将此服务器与MCP客户端配合使用，请添加以下配置：

{
  "mcpServers": {
    "image-recognition": {
      "command": "npx",
      "args": ["-y", "@akirose/image-recognition-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-api-key-here"
      }
    }
  }
}

若要允许从任何路径访问图像文件，请将 ALLOW_ALL_PATHS 设置为 true：

{
  "mcpServers": {
    "image-recognition": {
      "command": "npx",
      "args": ["-y", "@akirose/image-recognition-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-api-key-here",
        "ALLOW_ALL_PATHS": "true"
      }
    }
  }
}

⚠️ 重要提示

包含API密钥的 env 部分是必需的，这是MCP服务器正常运行的唯一方式。对于本地模型，你可以为 OPENAI_API_KEY 使用任何占位符值，并将 OPENAI_BASE_URL 配置为指向你的本地服务器。

环境变量

服务器支持以下环境变量： | 属性 | 详情 | |------|------| | OPENAI_API_KEY | 你的OpenAI API密钥，或使用本地模型时的任何占位符值（必需） | | OPENAI_BASE_URL | OpenAI API或兼容OpenAI的API服务器的基本URL（可选，默认为OpenAI的官方API）
例如，LM Studio的示例："http://127.0.0.1:1234/v1"；Ollama的示例："http://localhost:11434/v1" | | OPENAI_MODEL | 用于图像识别的视觉模型（可选，默认为 "gpt-5-mini"）
对于OpenAI："gpt-5-mini"、"gpt-4o"、"gpt-4o-mini" 等；对于本地模型："llava"、"qwen/qwen3-vl-4b" 或任何本地可用的视觉模型 | | ALLOWED_IMAGE_PATHS | 允许的本地文件路径的逗号分隔列表（可选，默认为 "./images,./assets"）
例如："./images,./assets,./downloads" | | ALLOW_ALL_PATHS | 设置为 "true" 以允许从任何路径访问图像文件。启用时，出于安全考虑，仅允许使用图像文件扩展名（.jpg、.jpeg、.png、.gif、.webp）（可选，默认为 false） | | ALLOWED_DOMAINS | 允许的URL域名的逗号分隔列表，以增强安全性（可选，默认为允许所有域名）
例如："example.com,cdn.example.com,images.example.org"；未设置时：允许所有域名；设置时：仅允许指定的域名进行基于URL的图像请求 |

💻 使用示例

可用工具

`describe-image`

分析来自URL或本地文件路径的图像，并提供详细描述。参数：

imageUrl（字符串）：要分析的图像的URL或本地文件路径。
prompt（字符串，可选）：关于图像的问题或提示（默认为 "what's in this image?"）。

使用URL的示例：

{
  "tool": "describe-image",
  "arguments": {
    "imageUrl": "https://example.com/image.jpg",
    "prompt": "what's in this image?"
  }
}

使用本地文件的示例：

{
  "tool": "describe-image",
  "arguments": {
    "imageUrl": "./images/my-image.png",
    "prompt": "Describe the objects in this image"
  }
}

响应：

{
  "content": [
    {
      "type": "text",
      "text": "The image shows a beautiful sunset over a mountain landscape with vibrant orange and pink colors in the sky..."
    }
  ]
}

与AI助手集成

此MCP服务器可以与支持MCP协议的各种AI助手集成，例如：

Claude Desktop
其他兼容MCP的AI系统

🔧 技术细节

项目结构

image-recognition-mcp/
├── src/
│   ├── index.ts                # 主服务器实现
│   ├── path-validator.ts       # 路径验证和安全功能
│   └── image-processor.ts      # 图像处理实用工具
├── test/
│   ├── index.test.ts           # 单元测试
│   ├── describe-image-integration.test.ts  # 集成测试
│   ├── test.png                # 测试图像
│   └── README.md               # 测试文档
├── dist/                       # 编译后的JavaScript输出
├── package.json                # 项目依赖和脚本
├── tsconfig.json               # TypeScript配置
└── README.md                   # 本文件

运行测试

项目包括单元测试和集成测试：

# 运行所有测试
npm test

# 仅运行单元测试
npm run test:unit

# 使用本地兼容OpenAI的服务器运行集成测试
npm run test:integration

集成测试要求：

在 http://127.0.0.1:1234/v1 运行的兼容OpenAI的API服务器。
服务器应支持视觉模型（如 qwen/qwen3-vl-4b）。
你可以使用LM Studio、Ollama或其他兼容服务器。
集成测试使用 OPENAI_BASE_URL 和 OPENAI_MODEL 环境变量。

集成测试将：

测试对视觉模型的实际API调用。
使用测试图像（test/test.png）验证图像处理。
使用默认和自定义提示验证完整的MCP工具工作流程。
测试错误处理和边缘情况。

安全特性

服务器包含以下安全特性：

路径验证：将本地文件访问限制在允许的目录中。
扩展名验证：仅允许特定的图像文件扩展名（.jpg、.jpeg、.png、.gif、.webp）。
域名限制：可选的URL域名白名单，以增强安全性。
文件存在性检查：在处理之前验证文件是否存在。

错误处理

服务器包含强大的错误处理机制，用于处理以下情况：

无效的图像URL。
未经授权的文件路径或域名。
网络连接问题。
OpenAI API错误。
无效的输入参数。
不支持的文件格式。

📚 详细文档

故障排除

常见问题

服务器无法启动或无法正常工作：

✅ 检查OpenAI API密钥是否设置：这是问题的首要原因。
```
echo $OPENAI_API_KEY  # 应显示你的API密钥
```
✅ 验证API密钥是否有效：直接使用OpenAI的API进行测试。
✅ 检查API密钥是否有足够的信用额度：确保你的OpenAI账户有可用的信用额度。

“身份验证失败”错误：

OpenAI API密钥缺失或无效。
设置环境变量：export OPENAI_API_KEY="your-key"

贡献代码

分叉仓库。
创建功能分支（git checkout -b feature/amazing-feature）。
提交更改（git commit -m 'Add some amazing feature'）。
推送到分支（git push origin feature/amazing-feature）。
打开拉取请求。

📄 许可证

本项目采用MIT许可证。有关详细信息，请参阅 LICENSE 文件。

支持

如需支持，请在GitHub仓库中打开一个问题或联系维护者。

image-recognition-mcp