Image Recognition MCP

🚀 图像识别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 配置为指向你的本地服务器。

环境变量

服务器支持以下环境变量：

💻 使用示例

可用工具

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"

贡献代码

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

📄 许可证

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

支持

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