Baidu iRAG MCP Server

Gere imagens usando a API iRAG da Baidu por meio de uma interface MCP padronizada.

Documentação

Servidor MCP Baidu iRAG

Um servidor MCP (Model Context Protocol) baseado na API de geração de imagens Baidu iRAG, permitindo que clientes MCP (como Claude Desktop) chamem o serviço de geração de imagens da Baidu por meio de uma interface padronizada.

🚨 Aviso importante

Antes de usar, faça um teste real com a API!

O teste básico apenas verifica se o servidor inicia. Para garantir total funcionalidade, você precisa:

Obter uma chave de API Baidu real
Executar npm run test:api para testar a API real
Verificar a geração de imagens e a conversão para Base64

Para um guia de configuração detalhado, consulte: FINAL_SETUP.md

Recursos

🎨 Suporte à API de geração de imagens Baidu iRAG
🔧 Implementação completa do protocolo MCP
📝 Suporte a vários modelos (irag-1.0, flux.1-schnell)
🖼️ Configuração flexível de tamanho de imagem
🔄 Mecanismo de nova tentativa automática
📊 Registro de logs completo
✅ Validação abrangente de parâmetros
🧪 Cobertura completa de testes

Modelos suportados

irag-1.0: Modelo de geração de imagens desenvolvido pela Baidu
flux.1-schnell: Modelo de geração rápida com suporte a mais parâmetros avançados

Instalação

Pré-requisitos

Node.js >= 18.0.0
npm ou yarn

Clonar o projeto

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

Instalar dependências

npm install

Compilar o projeto

npm run build

Configuração

1. Obter a chave de API Baidu

Acesse o Console da Baidu AI Cloud
Crie uma chave de API e selecione o Qianfan ModelBuilder
Configure os recursos do aplicativo correspondente
Copie a chave de API (formato: bce-v3/ALTAK-****/****)

2. Configuração das variáveis de ambiente

Copie o modelo de variáveis de ambiente:

cp .env.example .env

Edite o arquivo .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

Explicação das configurações de salvamento de imagens

RESOURCE_MODE=local: As imagens serão salvas no sistema de arquivos local, retornando também os dados base64 e o caminho do arquivo
RESOURCE_MODE=url: Retorna apenas a URL da imagem e os dados base64, sem salvar arquivos locais
BASE_PATH: Caminho personalizado para salvar imagens; se vazio, usa o caminho padrão (pasta irag-images na área de trabalho do usuário)
MODEL: Define o modelo de geração de imagens padrão
- irag-1.0: Modelo desenvolvido pela Baidu, boa versatilidade e velocidade
- flux.1-schnell: Suporta mais parâmetros avançados, maior qualidade

Como usar

Iniciar o servidor

# 开发模式
npm run dev

# 生产模式
npm start

Configuração do cliente MCP

Configuração do Claude Desktop

Adicione ao arquivo de configuração do 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"
      }
    }
  }
}

Referência da API

Ferramenta generate_image

Ferramenta MCP para geração de imagens.

Parâmetros

Nome do parâmetro	Tipo	Obrigatório	Padrão	Descrição
`prompt`	string	✅	-	Prompt de geração de imagem
`refer_image`	string	❌	-	URL da imagem de referência
`n`	integer	❌	1	Quantidade de imagens a gerar (1-4)
`size`	string	❌	1024x1024	Tamanho da imagem
`steps`	integer	❌	-	Número de etapas de amostragem (1-50, apenas flux.1-schnell)
`seed`	integer	❌	-	Semente aleatória (apenas flux.1-schnell)
`guidance`	number	❌	3.5	Valor de densidade de orientação (0-30, apenas flux.1-schnell)

Observação: O modelo é definido pelo parâmetro MODEL no arquivo de configuração, não na solicitação.

Tamanhos de imagem suportados

512x512, 768x768, 1024x768, 1024x1024

Exemplo de uso

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

Desenvolvimento

Estrutura do projeto

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

Comandos de desenvolvimento

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 监听测试
npm run test:watch

# 代码检查
npm run lint

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

# 清理构建文件
npm run clean

Testes

Executar todos os testes:

npm test

Ver a cobertura de testes:

npm test -- --coverage

Solução de problemas

Problemas comuns

Chave de API inválida
- Verifique se o formato da chave de API está correto: bce-v3/ALTAK-****/****
- Verifique se o recurso Qianfan ModelBuilder está configurado na chave de API
Tempo limite de conexão
- Verifique a conexão de rede
- Aumente o valor de configuração API_TIMEOUT
Falha na geração de imagens
- Verifique se o prompt atende aos requisitos
- Confirme se os parâmetros do modelo estão configurados corretamente
Erro de validação Base64
- O servidor baixa automaticamente a imagem e a converte para o formato base64
- Se o download falhar, uma mensagem de erro e a URL original serão retornadas
- Verifique a conexão de rede e a acessibilidade da URL da imagem
Problemas de conexão com o cliente MCP
- Verifique se o caminho do arquivo de configuração do Claude Desktop está correto
- Verifique a versão do Node.js (necessário >= 18.0.0)
- Confirme se o projeto foi compilado corretamente (execute npm run build)

Depuração de logs

Defina o nível de log como debug:

LOG_LEVEL=debug

Veja os logs detalhados de chamadas da API e o processo de download de imagens.

Licença

Licença MIT

Contribuições

Contribuições são bem-vindas! Envie Issues e Pull Requests!

Histórico de versões

v1.0.0

Versão inicial
Suporte à API de geração de imagens Baidu iRAG
Implementação completa do protocolo MCP
Suporte a vários modelos e configurações de parâmetros