即梦AI多模态MCP

Un servicio de generación multimodal que utiliza Volcengine Jimeng AI para la generación de imágenes, generación de videos y conversión de imagen a video.

GitHub
29
Prueba este MCPPatrocinado

Documentación

即梦AI多模态MCP

Este es un servicio de generación multimodal basado en 即梦AI de Volcano Engine, que admite generación de imágenes, generación de videos y otras funciones. Se puede utilizar en clientes MCP como Cursor, Claude Desktop, etc., a través del protocolo MCP, o como una biblioteca independiente. Compatible con macOS, Linux, Windows y entornos WSL.

Actualizaciones de versión

v1.0.14

  • Mejora de las definiciones de herramientas MCP, asegurando que todas las herramientas sean visibles en el cliente
  • Optimización del procesamiento de parámetros asíncronos, con modo asíncrono habilitado por defecto para evitar tiempos de espera
  • Adición de información de depuración más detallada para la generación de videos

v1.0.9-beta.1

  • Versión beta: mejora de las definiciones de herramientas MCP, asegurando que todas las herramientas sean visibles en el cliente
  • Optimización del procesamiento de parámetros asíncronos, con modo asíncrono habilitado por defecto para evitar tiempos de espera
  • Adición de información de depuración más detallada para la generación de videos
  • Corrección de problemas de transferencia de parámetros de herramientas

v1.0.5

  • Optimización de la estructura de documentación, proporcionando instrucciones de configuración claras para diferentes plataformas
  • Adición de ejemplos de configuración de PowerShell
  • Proporcionar métodos para configurar variables de entorno permanentes en cada plataforma
  • Adición de notas de configuración multiplataforma

v1.0.4

  • Optimización del inicio del servicio y la respuesta, ahora todas las respuestas utilizan formato JSON estándar
  • Unificación de la estructura de datos para errores y respuestas exitosas
  • Mejora de la legibilidad y capacidad de análisis de los mensajes de error

Funciones principales

  • ✅ Texto a imagen - Genera imágenes de alta calidad a partir de descripciones de texto (modelo: jimeng_t2i_s20pro)
  • ✅ Texto a video - Convierte descripciones de texto en videos fluidos (modelo: jimeng_vgfm_t2v_l20)
  • ✅ Imagen a video - Convierte imágenes estáticas en videos dinámicos (modelo: jimeng_vgfm_i2v_l20)
  • ✅ Soporte multiplataforma - Compatible con macOS, Linux, Windows y entornos WSL
  • 🛠️ Definiciones completas de tipos TypeScript y manejo de errores
  • 🔄 Soporte para procesamiento de tareas asíncronas y seguimiento de estado
  • 🎛️ Control de parámetros personalizados (tamaño, proporción, número de fotogramas, etc.)

Arquitectura del sistema

El siguiente diagrama de flujo muestra el flujo de trabajo y la arquitectura del sistema de 即梦AI多模态MCP:

graph LR
    A[用户输入] --> B[MCP协议解析]
    B --> C{工具选择}
    C -->|图像生成| D[generate-image]
    C -->|视频生成| E[generate-video]
    C -->|提交视频任务| F[submit-video-task]
    C -->|查询视频任务| G[get-video-task]
    
    D --> H[JimengClient]
    E --> H
    F --> H
    G --> H
    
    H --> I{API调用}
    I -->|图生成| J[火山引擎即梦AI<br/>图像生成API]
    I -->|视频生成| K[火山引擎即梦AI<br/>视频生成API]
    I -->|任务查询| L[火山引擎即梦AI<br/>任务状态API]
    
    J --> M[生成结果]
    K --> M
    L --> M
    
    M --> N[返回MCP响应]
    N --> O[用户展示]

Herramientas MCP disponibles

Nombre de la herramientaDescripciónParámetros principales
generate-imageGenerar imagentext, illustration, color, ratio
generate-videoGenerar videoprompt, async, intent_sync
submit-video-taskEnviar tarea de generación de videoprompt
get-video-taskObtener resultado de tarea de videotask_id

Inicio rápido

Instalación

Todas las plataformas (macOS/Linux/Windows):

# NPM全局安装
npm install -g jimeng-ai-mcp

# 或本地安装
git clone https://github.com/freeleepm/jimeng-ai-mcp.git
cd jimeng-mcp
npm install
npm run build

Configuración de variables de entorno

Antes de usar, debe configurar la clave de acceso al servicio 即梦AI de Volcano Engine:

macOS/Linux

# 设置环境变量
export JIMENG_ACCESS_KEY=你的火山引擎访问密钥
export JIMENG_SECRET_KEY=你的火山引擎密钥

# 或创建.env文件
echo "JIMENG_ACCESS_KEY=你的火山引擎访问密钥" > .env
echo "JIMENG_SECRET_KEY=你的火山引擎密钥" >> .env

# 永久设置环境变量（添加到 .bashrc 或 .zshrc）
echo 'export JIMENG_ACCESS_KEY="你的火山引擎访问密钥"' >> ~/.bashrc
echo 'export JIMENG_SECRET_KEY="你的火山引擎密钥"' >> ~/.bashrc
source ~/.bashrc

WSL (Subsistema de Windows para Linux)

# 设置环境变量
export JIMENG_ACCESS_KEY=你的火山引擎访问密钥
export JIMENG_SECRET_KEY=你的火山引擎密钥

# 或创建.env文件
echo "JIMENG_ACCESS_KEY=你的火山引擎访问密钥" > .env
echo "JIMENG_SECRET_KEY=你的火山引擎密钥" >> .env

# 永久设置环境变量（添加到 .bashrc）
echo 'export JIMENG_ACCESS_KEY="你的火山引擎访问密钥"' >> ~/.bashrc
echo 'export JIMENG_SECRET_KEY="你的火山引擎密钥"' >> ~/.bashrc
source ~/.bashrc

Windows

Símbolo del sistema (CMD):

:: 临时设置环境变量（当前会话有效）
set JIMENG_ACCESS_KEY=你的火山引擎访问密钥
set JIMENG_SECRET_KEY=你的火山引擎密钥

:: 创建.env文件
echo JIMENG_ACCESS_KEY=你的火山引擎访问密钥 > .env
echo JIMENG_SECRET_KEY=你的火山引擎密钥 >> .env

:: 永久设置环境变量（管理员命令提示符）
setx JIMENG_ACCESS_KEY "你的火山引擎访问密钥"
setx JIMENG_SECRET_KEY "你的火山引擎密钥"

PowerShell:

# 临时设置环境变量（当前会话有效）
$env:JIMENG_ACCESS_KEY = "你的火山引擎访问密钥"
$env:JIMENG_SECRET_KEY = "你的火山引擎密钥"

# 创建.env文件
"JIMENG_ACCESS_KEY=你的火山引擎访问密钥" | Out-File -FilePath .env -Encoding ASCII
"JIMENG_SECRET_KEY=你的火山引擎密钥" | Out-File -FilePath .env -Encoding ASCII -Append

# 永久设置环境变量（管理员PowerShell）
[Environment]::SetEnvironmentVariable("JIMENG_ACCESS_KEY", "你的火山引擎访问密钥", "User")
[Environment]::SetEnvironmentVariable("JIMENG_SECRET_KEY", "你的火山引擎密钥", "User")

Publicación y gestión de versiones

El proyecto incluye un script publish.sh para simplificar el proceso de publicación y gestión de versiones.

Cómo usar

Ejecute el script en el directorio raíz del proyecto:

./publish.sh

El script mostrará un menú para guiarlo a través de las diferentes operaciones.

Opciones de funciones

  1. Publicar nueva versión (opciones 1-5):

    • patch: Para corregir errores (por ejemplo, 1.0.4 -> 1.0.5).
    • minor: Para agregar funciones compatibles con versiones anteriores (por ejemplo, 1.0.4 -> 1.1.0).
    • major: Para cambios importantes que no son compatibles con versiones anteriores (por ejemplo, 1.0.4 -> 2.0.0).
    • beta: Crear o incrementar una versión de prueba (por ejemplo, 1.0.4 -> 1.0.5-beta.0 o 1.0.5-beta.0 -> 1.0.5-beta.1).
    • Versión personalizada: Ingresar manualmente un nuevo número de versión.

    Después de seleccionar estas opciones, el script automáticamente:

    • Verificará los cambios de Git no confirmados.
    • Actualizará los números de versión en package.json, mcp.json, examples/mcp-server.ts y README.md.
    • Compilará el proyecto.
    • Publicará en npm (las versiones beta usarán la etiqueta beta).
    • Confirmará la actualización de versión y creará una etiqueta de Git.

  2. Cancelar publicación de versión (opción 6):

    • Esta es una operación peligrosa, úsela con precaución.
    • El script le pedirá que ingrese el número de versión a cancelar, admite ingresar múltiples números de versión (separados por espacios).
    • Antes de ejecutar npm unpublish, se solicitará una segunda confirmación.
    • Nota: La política de npm generalmente solo permite cancelar la publicación dentro de las 72 horas posteriores a la publicación.

Configuración del cliente MCP

Configuración de Cursor

macOS/Linux

Cree el archivo mcp-config.json en el directorio de configuración de Cursor:

{
  "mcpServers": {
    "jimeng": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "jimeng-ai-mcp"
      ],
      "env": {
        "JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
        "JIMENG_SECRET_KEY": "你的火山引擎密钥"
      }
    }
  }
}

Windows

Cree el archivo mcp-config.json en el directorio de configuración de Cursor:

{
  "mcpServers": {
    "jimeng": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "jimeng-ai-mcp"
      ],
      "env": {
        "JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
        "JIMENG_SECRET_KEY": "你的火山引擎密钥"
      }
    }
  }
}

WSL (Subsistema de Windows para Linux)

Cree el archivo mcp-config.json en el directorio de configuración de Cursor:

{
  "mcpServers": {
    "jimeng": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "jimeng-ai-mcp"
      ],
      "env": {
        "JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
        "JIMENG_SECRET_KEY": "你的火山引擎密钥"
      }
    }
  }
}

Nota: En el entorno WSL, debe usar el prefijo cmd /c para asegurar que el comando se ejecute correctamente.

Configuración de Claude Desktop

macOS/Linux

Agregue al archivo de configuración claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "jimeng": {
      "command": "npx",
      "args": [
        "-y",
        "jimeng-ai-mcp"
      ],
      "env": {
        "JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
        "JIMENG_SECRET_KEY": "你的火山引擎密钥"
      }
    }
  }
}

Windows

Agregue al archivo de configuración claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "jimeng": {
      "command": "npx",
      "args": [
        "-y",
        "jimeng-ai-mcp"
      ],
      "env": {
        "JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
        "JIMENG_SECRET_KEY": "你的火山引擎密钥"
      }
    }
  }
}

WSL (Subsistema de Windows para Linux)

Agregue al archivo de configuración claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "jimeng": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "jimeng-ai-mcp"
      ],
      "env": {
        "JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
        "JIMENG_SECRET_KEY": "你的火山引擎密钥"
      }
    }
  }
}

Notas de configuración

  • macOS/Linux: Asegúrese de usar las variables de entorno y rutas correctas.
  • Windows:
    • Si encuentra problemas de ruta, verifique que la ruta del comando sea correcta; si es necesario, use la ruta completa.
    • Si usa instalación global, puede cambiar npx -y jimeng-ai-mcp por el comando jimeng-ai-mcp.
  • WSL (Subsistema de Windows para Linux):
    • En el entorno WSL, debe usar el prefijo cmd /c para asegurar que el comando se ejecute correctamente.
    • Asegúrese de que Node.js y npm estén correctamente instalados en el lado de Windows.

Ejemplos de uso de herramientas

En clientes compatibles con MCP (como Cursor, Claude Desktop), puede usar las herramientas de 即梦AI de las siguientes maneras:

Ejemplo de generación de imagen

请使用generate-image工具生成一张图片，图片上显示"创新未来"文字，配饰元素包括科技、星空、光线，背景色调为蓝色，比例为16:9。

Ejemplo de generación de video

请使用generate-video工具生成一段视频，视频内容为"熊猫在竹林中玩耍，阳光明媚，高清写实风格"。

Ejemplo de tarea de video asíncrona

请使用submit-video-task工具提交一个视频生成任务，视频内容为"一只白色的小猪在沙滩上跑动"。提交后使用get-video-task工具查询结果。

Preguntas frecuentes y solución de problemas

1. No se puede instalar o ejecutar mediante npx

Si encuentra el problema de que npx jimeng-ai-mcp no puede encontrar el paquete, intente:

  • Verifique que la conexión de red sea normal y pueda acceder al repositorio de npm
  • Use npm install -g jimeng-ai-mcp para instalar globalmente primero, luego use el comando jimeng-ai-mcp
  • Verifique que la versión de Node.js cumpla con los requisitos (se requiere v14.0.0 o superior)

2. Problemas con variables de entorno

  • Asegúrese de haber configurado correctamente las variables de entorno JIMENG_ACCESS_KEY y JIMENG_SECRET_KEY
  • También debe configurar estas variables de entorno en el archivo de configuración del cliente MCP
  • Puede configurar las variables de entorno creando un archivo .env (el proyecto proporciona .env.example como referencia; asegúrese de que el archivo esté en el directorio de trabajo)

3. Compatibilidad multiplataforma

  • Los usuarios de Windows pueden necesitar ajustar los separadores de ruta (use \\ o /)
  • Los usuarios de WSL deben usar el prefijo cmd /c
  • Asegúrese de que el paquete npm esté correctamente instalado en el entorno del sistema actual

Contribución y desarrollo

¡Bienvenido a contribuir código o sugerir mejoras al proyecto! Aquí está el flujo de desarrollo:

  1. Haga un fork del repositorio del proyecto
  2. Cree una rama de funciones (git checkout -b feature/amazing-feature)
  3. Confirme los cambios (git commit -m 'Add some amazing feature')
  4. Envíe a la rama (git push origin feature/amazing-feature)
  5. Cree un Pull Request

Configuración del entorno de desarrollo

# 克隆仓库
git clone https://github.com/freeleepm/jimeng-ai-mcp.git
cd jimeng-ai-mcp

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 发布到npm（需要npm账户权限）
npm version patch  # 更新版本号
npm publish

Uso de herramientas MCP

generate-image

Herramienta para generar imágenes, genera imágenes según indicaciones de texto.

Parámetros:

  • text: Texto que se mostrará en la imagen
  • illustration: Palabras clave de elementos de ilustración como accesorios de la imagen
  • color: Color de fondo principal de la imagen
  • ratio: Proporción de la imagen, admite: 4:3 (512×384), 3:4 (384×512), 16:9 (512×288), 9:16 (288×512)

Ejemplo:

请使用generate-image工具生成一张图片，图片上显示"创新未来"文字，配饰元素包括科技、星空、光线，背景色调为蓝色，比例为16:9。

generate-video

Herramienta para generar videos, utiliza el modelo de texto a video de 即梦AI.

Parámetros:

  • prompt: Descripción del contenido del video
  • num_frames: Número de fotogramas del video (opcional, predeterminado 16)
  • fps: Velocidad de fotogramas del video (opcional, predeterminado 8)

Ejemplo:

请使用generate-video工具生成一段视频，视频内容为"熊猫在竹林中玩耍"，帧数为16。

generate-image-to-video

Herramienta de imagen a video, convierte imágenes estáticas en videos dinámicos.

Parámetros:

  • image_urls: Matriz de URL de imágenes de entrada (formato JPEG/PNG)
  • prompt: Descripción del efecto de animación (opcional)
  • aspect_ratio: Proporción del video (opcional, como "16:9", "4:3", etc., predeterminado "16:9")
  • num_frames: Número de fotogramas del video (opcional, predeterminado 16)
  • fps: Velocidad de fotogramas del video (opcional, predeterminado 8)

Ejemplo:

请使用generate-image-to-video工具生成视频，输入图片为https://example.com/image.jpg，效果为"波浪摇曳"，比例为"16:9"。

Uso como biblioteca de cliente

Uso básico

import { JimengClient } from 'jimeng-ai-mcp';

// 创建客户端实例
const client = new JimengClient({
  accessKey: 'YOUR_ACCESS_KEY',
  secretKey: 'YOUR_SECRET_KEY',
  region: 'cn-beijing', // 默认区域
  debug: false // 设置为true可以查看详细日志
});

// 文生图示例
async function generateImage() {
  const result = await client.generateImage({
    prompt: "一只可爱的猫咪在草地上玩耍",
    width: 512,
    height: 512
  });
  
  if (result.success && result.image_urls && result.image_urls.length > 0) {
    console.log('图像URL:', result.image_urls[0]);
  } else {
    console.error('生成失败:', result.error);
  }
}

// 文生视频示例
async function generateVideo() {
  const result = await client.generateVideo({
    prompt: "一只可爱的猫咪在草地上玩耍"
  });
  
  if (result.success && result.video_urls && result.video_urls.length > 0) {
    console.log('视频URL:', result.video_urls[0]);
  } else {
    console.error('生成失败:', result.error);
  }
}

// 图生视频示例
async function generateImageToVideo() {
  const result = await client.generateImageToVideo({
    image_urls: ["https://example.com/image.jpg"],
    prompt: "波浪效果",
    aspect_ratio: "16:9"
  });
  
  if (result.success && result.video_urls && result.video_urls.length > 0) {
    console.log('视频URL:', result.video_urls[0]);
  } else {
    console.error('生成失败:', result.error);
  }
}

Uso avanzado: procesamiento de tareas asíncronas

Para tareas de generación de video que requieren mucho tiempo, puede usar el modo asíncrono:

// 文生视频异步方式
async function generateVideoAsync() {
  // 提交任务
  const taskResult = await client.submitVideoTask({
    prompt: "一只可爱的猫咪在草地上玩耍",
    req_key: "jimeng_vgfm_t2v_l20"
  });
  
  console.log('任务ID:', taskResult.task_id);
  
  // 轮询任务结果
  let result;
  do {
    // 等待60秒再查询（符合API限制）
    await new Promise(resolve => setTimeout(resolve, 60000));
    
    // 查询任务结果
    result = await client.getVideoTaskResult(taskResult.task_id);
    console.log('任务状态:', result.status);
    
  } while (result.status === 'PENDING' || result.status === 'RUNNING');
  
  if (result.success && result.status === 'SUCCEEDED') {
    console.log('视频URL:', result.video_urls);
  } else {
    console.error('生成失败:', result.error);
  }
}

// 图生视频异步方式
async function generateImageToVideoAsync() {
  // 提交任务
  const taskResult = await client.submitI2VTask({
    image_urls: ["https://example.com/image.jpg"],
    prompt: "波浪效果",
    req_key: "jimeng_vgfm_i2v_l20"
  });
  
  console.log('任务ID:', taskResult.task_id);
  
  // 查询任务结果（简化示例，实际应用需要轮询）
  const result = await client.getVideoTaskResult(taskResult.task_id, "jimeng_vgfm_i2v_l20");
  
  if (result.success && result.status === 'SUCCEEDED') {
    console.log('视频URL:', result.video_urls);
  }
}

Implementación con Docker

Cree el siguiente Dockerfile:

FROM node:16-alpine

RUN npm install -g jimeng-ai-mcp

ENV JIMENG_ACCESS_KEY=你的火山引擎访问密钥
ENV JIMENG_SECRET_KEY=你的火山引擎密钥

CMD ["jimeng-ai-mcp"]

Compile y ejecute:

docker build -t jimeng-ai-mcp .
docker run -i --rm jimeng-ai-mcp

Guía de desarrollo

Desarrollo local

# 开发模式启动
npm run dev

# 构建
npm run build

# 测试
npm test

# 运行
npm start

Publicar paquete NPM

# 更新版本号
npm version patch|minor|major

# 构建项目
npm run build

# 发布
npm publish

Solución de problemas

Problemas comunes

  1. Error de autenticación: Verifique que JIMENG_ACCESS_KEY y JIMENG_SECRET_KEY sean correctos.

  2. Formato de imagen no compatible: Asegúrese de usar imágenes en formato JPEG/PNG y que la URL sea de acceso público.

  3. Límite de QPS: La API tiene un límite de QPS=1, debe esperar 60 segundos entre múltiples llamadas.

  4. Verificación de seguridad de contenido: Asegúrese de que el contenido generado cumpla con la política de contenido de la plataforma.

Lista de códigos de error

  • ERR_AUTH_FAILED: Error de autenticación, verifique la clave de acceso
  • ERR_TASK_FAILED: Error de tarea, consulte la información detallada del error
  • ERR_INVALID_PARAM: Parámetros no válidos, verifique los parámetros de entrada
  • ERR_NETWORK: Error de red, verifique la conexión de red
  • ERR_SERVER: Error del servidor, intente nuevamente más tarde

Contribución y soporte

¡Bienvenido a enviar problemas y solicitudes de extracción! Si tiene algún problema, comuníquese a través de GitHub Issues.

Licencia

MIT

Explicación detallada de funciones

Generación de imágenes (generate-image)

Use la herramienta generate-image para generar imágenes según descripciones de texto, elementos de ilustración y colores:

{
  "text": "创新未来",
  "illustration": "科技、星空、光线",
  "color": "蓝色",
  "ratio": "16:9"
}

Proporciones de imagen compatibles:

  • 4:3 - 512×384 píxeles
  • 3:4 - 384×512 píxeles
  • 16:9 - 512×288 píxeles
  • 9:16 - 288×512 píxeles

Generación de videos (generate-video)

La herramienta generate-video admite la generación de videos según descripciones de texto. A partir de la versión v1.0.5, esta herramienta usa el modo asíncrono por defecto, es decir, devuelve inmediatamente el ID de la tarea, y luego debe usar la herramienta get-video-task para consultar el resultado.

Descripción de parámetros

  • prompt - Descripción del contenido del video (obligatorio)
  • async - Si usar el modo asíncrono (opcional, predeterminado true)
  • intent_sync - Si se detecta intención de generación síncrona (opcional, predeterminado false)

Modos de comportamiento

  1. Modo asíncrono (predeterminado):

    • Devuelve inmediatamente el ID de la tarea, sin esperar a que se complete la generación del video
    • Debe usar la herramienta get-video-task posteriormente para consultar el resultado
    • Adecuado para entornos de producción y escenarios que evitan tiempos de espera
    {
  "prompt": "一只熊猫在竹林中玩耍"
}

  2. Modo síncrono:

    • Espera a que se complete la generación del video antes de devolver el resultado (puede tomar 1-2 minutos)
    • Es posible que la solicitud exceda el tiempo de espera debido al largo tiempo de generación
    • Adecuado para pruebas y experiencia rápida

    Formas de activar el modo síncrono:

    • Configurar explícitamente async=false
    • Configurar intent_sync=true
    • Incluir palabras clave en el mensaje que indiquen la expectativa de resultados inmediatos (como "salida única", "salida síncrona", "esperar resultado", etc.)
    {
  "prompt": "一只熊猫在竹林中玩耍",
  "async": false
}

    O mediante expresión de intención (el modelo grande identificará automáticamente y configurará intent_sync=true):

    请帮我生成一个熊猫在竹林中玩耍的视频，希望一次输出结果

Mejores prácticas

  • Para entornos de producción o integración con asistentes de IA, se recomienda usar el modo asíncrono predeterminado
  • La generación de videos generalmente toma 1-2 minutos; el modo asíncrono evita errores de tiempo de espera
  • Si necesita resultados síncronos, asegúrese de configurar un tiempo de espera de solicitud suficientemente largo

Generación de videos por pasos

Para escenarios que requieren un control más preciso, puede usar la generación de videos por pasos:

  1. Enviar la tarea de generación de video:
// submit-video-task
{
  "prompt": "一只白色的小猪在沙滩上跑动"
}
  1. Usar el ID de tarea devuelto para consultar el resultado:
// get-video-task
{
  "task_id": "12345678901234567890"
}