即梦AI多模态MCP
Um serviço de geração multimodal que utiliza o Volcengine Jimeng AI para geração de imagens, geração de vídeos e conversão de imagem para vídeo.
Documentação
即梦AI多模态MCP
Este é um serviço de geração multimodal baseado no 即梦AI da Volcano Engine, que suporta geração de imagens, geração de vídeos e outras funcionalidades. Pode ser usado em clientes MCP como Cursor, Claude Desktop, entre outros, através do protocolo MCP, ou chamado como uma biblioteca independente. Suporta ambientes macOS, Linux, Windows e WSL.
Atualizações de Versão
v1.0.14
- Definições aprimoradas de ferramentas MCP, garantindo que todas as ferramentas estejam visíveis no cliente
- Processamento assíncrono de parâmetros otimizado, com modo assíncrono habilitado por padrão para evitar timeouts
- Informações de depuração mais detalhadas para geração de vídeo
v1.0.9-beta.1
- Versão beta: definições aprimoradas de ferramentas MCP, garantindo que todas as ferramentas estejam visíveis no cliente
- Processamento assíncrono de parâmetros otimizado, com modo assíncrono habilitado por padrão para evitar timeouts
- Informações de depuração mais detalhadas para geração de vídeo
- Correção de problemas na transmissão de parâmetros das ferramentas
v1.0.5
- Estrutura de documentação otimizada, com instruções de configuração claras para diferentes plataformas
- Exemplos de configuração do PowerShell adicionados
- Métodos de configuração de variáveis de ambiente permanentes para cada plataforma
- Notas de configuração multiplataforma adicionadas
v1.0.4
- Inicialização do serviço e retorno de respostas otimizados; agora todas as respostas usam formato JSON padrão
- Estrutura de dados unificada para tratamento de erros e respostas de sucesso
- Legibilidade e capacidade de análise de mensagens de erro aprimoradas
Funcionalidades Principais
- ✅ Texto para Imagem - Gera imagens de alta qualidade a partir de descrições textuais (modelo: jimeng_t2i_s20pro)
- ✅ Texto para Vídeo - Converte descrições textuais em vídeos fluidos (modelo: jimeng_vgfm_t2v_l20)
- ✅ Imagem para Vídeo - Converte imagens estáticas em vídeos dinâmicos (modelo: jimeng_vgfm_i2v_l20)
- ✅ Suporte Multiplataforma - Suporta ambientes macOS, Linux, Windows e WSL
- 🛠️ Definições completas de tipos TypeScript e tratamento de erros
- 🔄 Suporte a processamento assíncrono de tarefas e rastreamento de status
- 🎛️ Controle personalizado de parâmetros (dimensões, proporção, número de quadros, etc.)
Arquitetura do Sistema
O fluxograma a seguir ilustra o fluxo de trabalho e a arquitetura do sistema do 即梦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[用户展示]
Ferramentas MCP Disponíveis
| Nome da Ferramenta | Descrição | Parâmetros Principais |
|---|---|---|
generate-image | Gerar imagem | text, illustration, color, ratio |
generate-video | Gerar vídeo | prompt, async, intent_sync |
submit-video-task | Enviar tarefa de geração de vídeo | prompt |
get-video-task | Obter resultado da tarefa de vídeo | task_id |
Início Rápido
Instalação
Todas as 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
Configuração de Variáveis de Ambiente
Antes de usar, é necessário configurar as chaves de acesso do serviço 即梦AI da 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 (Windows Subsystem for 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
Prompt de Comando (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")
Publicação e Gerenciamento de Versões
O projeto inclui um script publish.sh para simplificar o processo de publicação e gerenciamento de versões.
Como Usar
Execute o script na raiz do projeto:
./publish.sh
O script exibirá um menu para guiá-lo pelas diferentes operações.
Opções de Funcionalidades
-
Publicar Nova Versão (Opções 1-5):
- patch: Para correções de bugs (ex.:
1.0.4->1.0.5). - minor: Para adicionar funcionalidades com compatibilidade reversa (ex.:
1.0.4->1.1.0). - major: Para mudanças significativas sem compatibilidade reversa (ex.:
1.0.4->2.0.0). - beta: Cria ou incrementa uma versão beta (ex.:
1.0.4->1.0.5-beta.0ou1.0.5-beta.0->1.0.5-beta.1). - Versão personalizada: Insira manualmente um novo número de versão.
Ao selecionar essas opções, o script automaticamente:
- Verifica se há alterações Git não commitadas.
- Atualiza os números de versão em
package.json,mcp.json,examples/mcp-server.tseREADME.md. - Compila o projeto.
- Publica no npm (versões beta usam a tag
beta). - Faz commit da atualização de versão e cria uma tag Git.
- patch: Para correções de bugs (ex.:
-
Cancelar Publicação de Versão (Opção 6):
- Esta é uma operação perigosa, use com cautela.
- O script solicitará o número da versão a ser cancelada; suporta múltiplos números de versão (separados por espaços).
- Antes de executar
npm unpublish, será solicitada uma segunda confirmação. - Nota: A política do npm geralmente permite cancelar a publicação apenas dentro de 72 horas após a publicação.
Configuração do Cliente MCP
Configuração do Cursor
macOS/Linux
Crie o arquivo mcp-config.json no diretório de configuração do Cursor:
{
"mcpServers": {
"jimeng": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"jimeng-ai-mcp"
],
"env": {
"JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
"JIMENG_SECRET_KEY": "你的火山引擎密钥"
}
}
}
}
Windows
Crie o arquivo mcp-config.json no diretório de configuração do Cursor:
{
"mcpServers": {
"jimeng": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"jimeng-ai-mcp"
],
"env": {
"JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
"JIMENG_SECRET_KEY": "你的火山引擎密钥"
}
}
}
}
WSL (Windows Subsystem for Linux)
Crie o arquivo mcp-config.json no diretório de configuração do Cursor:
{
"mcpServers": {
"jimeng": {
"type": "stdio",
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"jimeng-ai-mcp"
],
"env": {
"JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
"JIMENG_SECRET_KEY": "你的火山引擎密钥"
}
}
}
}
Nota: No ambiente WSL, é necessário usar o prefixo
cmd /cpara garantir a execução correta dos comandos.
Configuração do Claude Desktop
macOS/Linux
Adicione ao arquivo de configuração claude_desktop_config.json do Claude Desktop:
{
"mcpServers": {
"jimeng": {
"command": "npx",
"args": [
"-y",
"jimeng-ai-mcp"
],
"env": {
"JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
"JIMENG_SECRET_KEY": "你的火山引擎密钥"
}
}
}
}
Windows
Adicione ao arquivo de configuração claude_desktop_config.json do Claude Desktop:
{
"mcpServers": {
"jimeng": {
"command": "npx",
"args": [
"-y",
"jimeng-ai-mcp"
],
"env": {
"JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
"JIMENG_SECRET_KEY": "你的火山引擎密钥"
}
}
}
}
WSL (Windows Subsystem for Linux)
Adicione ao arquivo de configuração claude_desktop_config.json do Claude Desktop:
{
"mcpServers": {
"jimeng": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"jimeng-ai-mcp"
],
"env": {
"JIMENG_ACCESS_KEY": "你的火山引擎访问密钥",
"JIMENG_SECRET_KEY": "你的火山引擎密钥"
}
}
}
}
Notas de Configuração
- macOS/Linux: Certifique-se de usar as variáveis de ambiente e caminhos corretos.
- Windows:
- Se encontrar problemas de caminho, verifique se o caminho do comando está correto; se necessário, use o caminho completo.
- Se usar instalação global, você pode alterar
npx -y jimeng-ai-mcppara o comandojimeng-ai-mcp.
- WSL (Windows Subsystem for Linux):
- No ambiente WSL, é obrigatório usar o prefixo
cmd /cpara garantir a execução correta dos comandos. - Certifique-se de que o Node.js e o npm estejam instalados corretamente no lado do Windows.
- No ambiente WSL, é obrigatório usar o prefixo
Exemplos de Uso das Ferramentas
Em clientes que suportam MCP (como Cursor, Claude Desktop), você pode usar as ferramentas do 即梦AI das seguintes maneiras:
Exemplo de Geração de Imagem
请使用generate-image工具生成一张图片,图片上显示"创新未来"文字,配饰元素包括科技、星空、光线,背景色调为蓝色,比例为16:9。
Exemplo de Geração de Vídeo
请使用generate-video工具生成一段视频,视频内容为"熊猫在竹林中玩耍,阳光明媚,高清写实风格"。
Exemplo de Tarefa de Vídeo Assíncrona
请使用submit-video-task工具提交一个视频生成任务,视频内容为"一只白色的小猪在沙滩上跑动"。提交后使用get-video-task工具查询结果。
Perguntas Frequentes e Solução de Problemas
1. Não é possível instalar ou executar via npx
Se encontrar o erro de pacote não encontrado com npx jimeng-ai-mcp, tente:
- Verifique se a conexão de rede está funcionando e se o repositório npm está acessível
- Use
npm install -g jimeng-ai-mcppara instalar globalmente primeiro e depois use o comandojimeng-ai-mcp - Verifique se a versão do Node.js atende aos requisitos (necessário v14.0.0 ou superior)
2. Problemas com Variáveis de Ambiente
- Certifique-se de que as variáveis de ambiente
JIMENG_ACCESS_KEYeJIMENG_SECRET_KEYestejam configuradas corretamente - Essas variáveis de ambiente também precisam ser configuradas no arquivo de configuração do cliente MCP
- Você pode criar um arquivo .env para definir as variáveis de ambiente (o projeto fornece .env.example como referência; certifique-se de que o arquivo esteja no diretório de trabalho)
3. Compatibilidade Multiplataforma
- Usuários do Windows podem precisar ajustar os separadores de caminho (use
\\ou/) - Usuários do WSL precisam usar o prefixo
cmd /c - Certifique-se de que o pacote npm esteja instalado corretamente no ambiente do sistema atual
Contribuição e Desenvolvimento
Contribuições de código e sugestões de melhoria são bem-vindas! Aqui está o fluxo de desenvolvimento:
- Faça um fork do repositório do projeto
- Crie um branch de funcionalidade (
git checkout -b feature/amazing-feature) - Faça commit das alterações (
git commit -m 'Add some amazing feature') - Envie para o branch (
git push origin feature/amazing-feature) - Crie um Pull Request
Configuração do Ambiente de Desenvolvimento
# 克隆仓库
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 das Ferramentas MCP
generate-image
Ferramenta de geração de imagens, que gera imagens a partir de prompts de texto.
Parâmetros:
text: Texto a ser exibido na imagemillustration: Palavras-chave de elementos de ilustração usados como acessórios da imagemcolor: Cor de fundo principal da imagemratio: Proporção da imagem, suporta: 4:3 (512×384), 3:4 (384×512), 16:9 (512×288), 9:16 (288×512)
Exemplo:
请使用generate-image工具生成一张图片,图片上显示"创新未来"文字,配饰元素包括科技、星空、光线,背景色调为蓝色,比例为16:9。
generate-video
Ferramenta de geração de vídeos, que usa o modelo de texto para vídeo do 即梦AI.
Parâmetros:
prompt: Descrição do conteúdo do vídeonum_frames: Número de quadros do vídeo (opcional, padrão 16)fps: Taxa de quadros do vídeo (opcional, padrão 8)
Exemplo:
请使用generate-video工具生成一段视频,视频内容为"熊猫在竹林中玩耍",帧数为16。
generate-image-to-video
Ferramenta de imagem para vídeo, que converte imagens estáticas em vídeos dinâmicos.
Parâmetros:
image_urls: Array de URLs de imagens de entrada (formato JPEG/PNG)prompt: Descrição do efeito de animação (opcional)aspect_ratio: Proporção do vídeo (opcional, ex.: "16:9", "4:3", etc., padrão "16:9")num_frames: Número de quadros do vídeo (opcional, padrão 16)fps: Taxa de quadros do vídeo (opcional, padrão 8)
Exemplo:
请使用generate-image-to-video工具生成视频,输入图片为https://example.com/image.jpg,效果为"波浪摇曳",比例为"16:9"。
Uso como Biblioteca 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 Avançado: Processamento de Tarefas Assíncronas
Para tarefas de geração de vídeo que demoram mais, você pode usar o modo assí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);
}
}
Implantação com Docker
Crie o seguinte 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 e execute:
docker build -t jimeng-ai-mcp .
docker run -i --rm jimeng-ai-mcp
Guia de Desenvolvimento
Desenvolvimento Local
# 开发模式启动
npm run dev
# 构建
npm run build
# 测试
npm test
# 运行
npm start
Publicação do Pacote npm
# 更新版本号
npm version patch|minor|major
# 构建项目
npm run build
# 发布
npm publish
Solução de Problemas
Problemas Comuns
-
Falha de autenticação: Verifique se JIMENG_ACCESS_KEY e JIMENG_SECRET_KEY estão corretos.
-
Formato de imagem não suportado: Certifique-se de usar imagens nos formatos JPEG/PNG e que as URLs sejam publicamente acessíveis.
-
Limite de QPS: A API tem um limite de QPS=1; aguarde 60 segundos entre chamadas múltiplas.
-
Verificação de segurança de conteúdo: Certifique-se de que o conteúdo gerado esteja em conformidade com as políticas de conteúdo da plataforma.
Lista de Códigos de Erro
ERR_AUTH_FAILED: Falha de autenticação, verifique as chaves de acessoERR_TASK_FAILED: Falha na tarefa, consulte as informações detalhadas do erroERR_INVALID_PARAM: Parâmetros inválidos, verifique os parâmetros de entradaERR_NETWORK: Erro de rede, verifique a conexão de redeERR_SERVER: Erro do servidor, tente novamente mais tarde
Contribuição e Suporte
Issues e pull requests são bem-vindos! Em caso de problemas, relate através do GitHub Issues.
Licença
MIT
Detalhes das Funcionalidades
Geração de Imagem (generate-image)
Use a ferramenta generate-image para gerar imagens a partir de descrições textuais, elementos de ilustração e cores:
{
"text": "创新未来",
"illustration": "科技、星空、光线",
"color": "蓝色",
"ratio": "16:9"
}
Proporções de imagem suportadas:
4:3- 512×384 pixels3:4- 384×512 pixels16:9- 512×288 pixels9:16- 288×512 pixels
Geração de Vídeo (generate-video)
A ferramenta generate-video suporta a geração de vídeos a partir de descrições textuais. A partir da versão v1.0.5, esta ferramenta usa o modo assíncrono por padrão, ou seja, retorna imediatamente um ID de tarefa, que deve ser usado posteriormente com a ferramenta get-video-task para consultar o resultado.
Descrição dos Parâmetros
prompt- Descrição do conteúdo do vídeo (obrigatório)async- Se deve usar o modo assíncrono (opcional, padrãotrue)intent_sync- Se foi detectada intenção de geração síncrona (opcional, padrãofalse)
Modos de Comportamento
-
Modo assíncrono (padrão):
- Retorna imediatamente o ID da tarefa, sem aguardar a conclusão da geração do vídeo
- É necessário usar a ferramenta
get-video-taskposteriormente para consultar o resultado - Adequado para ambientes de produção e para evitar timeouts
{ "prompt": "一只熊猫在竹林中玩耍" } -
Modo síncrono:
- Aguarda a conclusão da geração do vídeo antes de retornar o resultado (pode levar de 1 a 2 minutos)
- Pode causar timeout da solicitação se a geração demorar muito
- Adequado para testes e experiências rápidas
Como acionar o modo síncrono:
- Definir explicitamente
async=false - Definir
intent_sync=true - Incluir palavras-chave no prompt que indiquem expectativa de resultado imediato (como "saída única", "saída síncrona", "aguardar resultado", etc.)
{ "prompt": "一只熊猫在竹林中玩耍", "async": false }Ou através de expressão de intenção (o modelo de IA reconhece automaticamente e define
intent_sync=true):请帮我生成一个熊猫在竹林中玩耍的视频,希望一次输出结果
Melhores Práticas
- Para ambientes de produção ou integração com assistentes de IA, recomenda-se usar o modo assíncrono padrão
- A geração de vídeos geralmente leva de 1 a 2 minutos; o modo assíncrono evita erros de timeout
- Se precisar de resultados síncronos, certifique-se de definir um tempo de timeout de solicitação suficientemente longo
Geração de Vídeo em Etapas
Para cenários que exigem controle mais preciso, você pode usar a geração de vídeo em etapas:
- Envie a tarefa de geração de vídeo:
// submit-video-task
{
"prompt": "一只白色的小猪在沙滩上跑动"
}
- Use o ID da tarefa retornado para consultar o resultado:
// get-video-task
{
"task_id": "12345678901234567890"
}