Baidu iRAG MCP Server

Genera imágenes usando la API de iRAG de Baidu a través de una interfaz MCP estandarizada.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Baidu iRAG

Un servidor MCP (Model Context Protocol) basado en la API de generación de imágenes Baidu iRAG, que permite a los clientes MCP (como Claude Desktop) invocar el servicio de generación de imágenes de Baidu a través de una interfaz estandarizada.

🚨 Aviso importante

¡Asegúrese de realizar una prueba real de la API antes de usarlo!

Las pruebas básicas solo verifican que el servidor se inicia. Para garantizar su total funcionalidad, necesita:

  1. Obtener una clave de API real de Baidu
  2. Ejecutar npm run test:api para realizar una prueba real de la API
  3. Verificar la generación de imágenes y la conversión a Base64

Para obtener una guía de configuración detallada, consulte: FINAL_SETUP.md

Características

  • 🎨 Compatible con la API de generación de imágenes Baidu iRAG
  • 🔧 Implementación completa del protocolo MCP
  • 📝 Compatible con múltiples modelos (irag-1.0, flux.1-schnell)
  • 🖼️ Configuración flexible del tamaño de imagen
  • 🔄 Mecanismo de reintento automático
  • 📊 Registro de logs completo
  • ✅ Validación integral de parámetros
  • 🧪 Cobertura de pruebas completa

Modelos compatibles

  • irag-1.0: Modelo de generación de imágenes desarrollado por Baidu
  • flux.1-schnell: Modelo de generación rápida con más parámetros avanzados

Instalación

Requisitos previos

  • Node.js >= 18.0.0
  • npm o yarn

Clonar el proyecto

git clone <repository-url>
cd irag-mcp-server

Instalar dependencias

npm install

Compilar el proyecto

npm run build

Configuración

1. Obtener la clave de API de Baidu

  1. Visite la consola de Baidu AI Cloud
  2. Cree una clave de API y seleccione Qianfan ModelBuilder
  3. Configure los recursos de la aplicación correspondiente
  4. Copie la clave de API (formato: bce-v3/ALTAK-****/****)

2. Configuración de variables de entorno

Copie la plantilla de variables de entorno:

cp .env.example .env

Edite el archivo .env:

# 必需配置
BAIDU_API_KEY=bce-v3/ALTAK-your-access-key/your-secret-key

# 图片资源配置
RESOURCE_MODE=local          # local: 保存到本地文件 | url: 仅返回URL和base64
BASE_PATH=                   # 自定义保存路径（可选，默认为桌面/irag-images）
MODEL=irag-1.0              # 默认模型: irag-1.0 | flux.1-schnell

# 可选配置
SERVER_NAME=irag-mcp-server
SERVER_VERSION=1.0.0
LOG_LEVEL=info
LOG_FILE=logs/server.log
API_TIMEOUT=30000
MAX_RETRIES=3

Notas sobre la configuración de guardado de imágenes

  • RESOURCE_MODE=local: Las imágenes se guardan en el sistema de archivos local, devolviendo tanto los datos base64 como la ruta del archivo
  • RESOURCE_MODE=url: Solo devuelve la URL de la imagen y los datos base64, sin guardar archivos locales
  • BASE_PATH: Ruta personalizada para guardar imágenes; si se deja vacía, se usa la ruta predeterminada (carpeta irag-images en el escritorio del usuario)
  • MODEL: Establece el modelo de generación de imágenes predeterminado
    • irag-1.0: Modelo propio de Baidu, buena versatilidad y velocidad
    • flux.1-schnell: Admite más parámetros avanzados, mayor calidad

Uso

Iniciar el servidor

# 开发模式
npm run dev

# 生产模式
npm start

Configuración del cliente MCP

Configuración de Claude Desktop

Agregue lo siguiente al archivo de configuración de Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "irag-image-generator": {
      "command": "node",
      "args": ["/path/to/irag-mcp-server/dist/index.js"],
      "env": {
        "BAIDU_API_KEY": "bce-v3/ALTAK-your-access-key/your-secret-key"
      }
    }
  }
}

Referencia de la API

Herramienta generate_image

Herramienta MCP para generar imágenes.

Parámetros

Nombre del parámetroTipoObligatorioValor predeterminadoDescripción
promptstring✅-Prompt de generación de imagen
refer_imagestring❌-URL de imagen de referencia
ninteger❌1Cantidad de imágenes a generar (1-4)
sizestring❌1024x1024Tamaño de la imagen
stepsinteger❌-Pasos de muestreo (1-50, solo flux.1-schnell)
seedinteger❌-Semilla aleatoria (solo flux.1-schnell)
guidancenumber❌3.5Valor de densidad de guía (0-30, solo flux.1-schnell)

Nota: El modelo se configura mediante el parámetro MODEL en el archivo de configuración, no se especifica en la solicitud.

Tamaños de imagen compatibles

  • 512x512, 768x768, 1024x768, 1024x1024

Ejemplo de uso

{
  "name": "generate_image",
  "arguments": {
    "prompt": "一只可爱的橘猫坐在窗台上，阳光透过窗户洒在它身上",
    "size": "1024x1024",
    "n": 2
  }
}

Desarrollo

Estructura del proyecto

src/
├── client/          # API客户端
├── config/          # 配置管理
├── server/          # MCP服务器
├── types/           # 类型定义
├── utils/           # 工具函数
├── __tests__/       # 测试文件
└── index.ts         # 主入口

Comandos de desarrollo

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 监听测试
npm run test:watch

# 代码检查
npm run lint

# 修复代码风格
npm run lint:fix

# 清理构建文件
npm run clean

Pruebas

Ejecutar todas las pruebas:

npm test

Ver la cobertura de pruebas:

npm test -- --coverage

Solución de problemas

Problemas comunes

  1. Clave de API no válida

    • Asegúrese de que el formato de la clave de API sea correcto: bce-v3/ALTAK-****/****
    • Verifique que la clave de API tenga configurados los recursos de Qianfan ModelBuilder

  2. Tiempo de espera de conexión agotado

    • Verifique la conexión de red
    • Aumente el valor de configuración de API_TIMEOUT

  3. Error en la generación de imágenes

    • Verifique que el prompt cumpla con los requisitos
    • Confirme que los parámetros del modelo estén configurados correctamente

  4. Error de validación de Base64

    • El servidor descargará automáticamente la imagen y la convertirá a formato base64
    • Si la descarga falla, se devolverá un mensaje de error y la URL original
    • Verifique la conexión de red y la accesibilidad de la URL de la imagen

  5. Problemas de conexión del cliente MCP

    • Asegúrese de que la ruta del archivo de configuración de Claude Desktop sea correcta
    • Verifique la versión de Node.js (se requiere >=18.0.0)
    • Confirme que el proyecto se haya compilado correctamente (ejecute npm run build)

Depuración de logs

Establezca el nivel de registro en debug:

LOG_LEVEL=debug

Consulte los registros detallados de llamadas a la API y el proceso de descarga de imágenes.

Licencia

Licencia MIT

Contribuciones

¡Bienvenidos los Issues y Pull Requests!

Registro de cambios

v1.0.0

  • Lanzamiento de la versión inicial
  • Compatibilidad con la API de generación de imágenes Baidu iRAG
  • Implementación completa del protocolo MCP
  • Compatibilidad con múltiples modelos y configuración de parámetros