Ensinando Kiro a Pintar: Uma Habilidade de Edição de Imagem Stateful Baseada na API de Interações do Gemini e MCP

TL;DR: nb2lite-skill-kiro envolve o modelo gemini-3.1-flash-lite-image do Google (NB2Lite) em um pequeno servidor FastMCP e o empacota como uma habilidade Kiro. Você digita "gerar uma imagem de uma cozinha cyberpunk" no Kiro, e ele simplesmente... faz isso. Então você diz "adicione uma placa de RAMEN neon" e ele edita a mesma imagem sem precisar re-descrever toda a cena. Ah, e a imagem de capa deste artigo? Gerada pela coisa sobre a qual o artigo fala — dogfooding até o fim. Mais sobre isso no final.

Contexto: por que mais uma ferramenta de imagem?

A maioria dos fluxos de trabalho de geração de imagens são sem estado. Você envia um prompt, recebe pixels de volta, e o modelo imediatamente esquece tudo. Quer ajustar o resultado? Você re-descreve a cena inteira e reza para que o personagem, a iluminação e a composição sobrevivam à viagem de ida e volta. (Narrador: eles não sobrevivem.)

O NB2Lite do Google — o apelido amigável para gemini-3.1-flash-lite-image — adota uma abordagem diferente. É um modelo de imagem de alta eficiência com gerações em menos de 2 segundos, renderização de texto sólida em mais de 25 idiomas, e — a principal característica — suporte para a API de Interações com estado, que permite iterar sobre uma imagem em várias etapas enquanto o modelo mantém o contexto visual no servidor.

Este repositório conecta essa capacidade ao Kiro, para que seu agente de codificação possa gerar e refinar iterativamente imagens como parte natural de uma sessão. Ele é enviado como duas coisas em um único repositório:

1. Um servidor de Protocolo de Contexto de Modelo (MCP) (nb2lite-agent, um aplicativo FastMCP de arquivo único em server.py) expondo exatamente quatro ferramentas.
2. Uma habilidade Kiro (nb2lite-image) que ensina o Kiro quando e como usar essas ferramentas corretamente.

A API de Interações: imagens com memória

A API de Interações é o endpoint com estado do Gemini. O loop central funciona assim:

1. Você chama client.interactions.create(...) com um prompt e store=True.
2. A resposta inclui um interaction_id — um identificador para o contexto visual da rodada, persistido nos servidores do Google.
3. Na próxima chamada, você passa previous_interaction_id, e o modelo edita a tela existente — preservando personagem, estilo, iluminação e continuidade de pixels.

Então, em vez disso (sofrimento sem estado):

"Uma raposa em aquarela em uma floresta ao amanhecer, neblina, luz suave, usando um cachecol vermelho, três bétulas à esquerda, e agora também segurando uma lanterna"

...você escreve isso:

"Adicione uma lanterna em sua pata."

É isso. O contexto armazenado mantém o resto.

Alguns detalhes práticos que o servidor cuida para você:

• Cada rodada retorna um novo ID de interação. Cadastre o mais recente; editar a partir de um ID desatualizado silenciosamente separa sua sessão de um estado anterior (um bug sutil e muito irritante se você fizer isso manualmente).
• Proporção de aspecto é escolhida no momento da geração (1:1, 16:9, 9:16, 4:3, 3:4) e herdada em edições com estado — mudá-la no meio da sessão degrada a continuidade dos pixels, então a ferramenta de edição deliberadamente não aceita uma.
• Níveis de pensamento: baixo (padrão, rascunhos rápidos) ou alto (renderização complexa, layout de texto preciso, composição de personagens). A especificação genérica da API também lista mínimo e médio, mas a API ao vivo os rejeita para este modelo com um HTTP 400 — o servidor o salva de descobrir isso da maneira difícil.

O que é MCP, em um minuto

O Protocolo de Contexto de Modelo é um padrão aberto para conectar assistentes de IA a ferramentas e dados. Antes dele, dar a um modelo acesso a algum serviço significava escrever uma integração sob medida para cada assistente — N assistentes × M serviços, todos reinventando a mesma tubulação. O MCP colapsa isso: um autor de ferramenta escreve um servidor MCP que expõe ferramentas tipadas, e qualquer cliente compatível com MCP (Kiro, Claude Code, Claude Desktop, e uma lista crescente de outros) pode descobri-las e chamá-las sem código de cola por cliente.

Um servidor MCP é geralmente um pequeno processo local que fala JSON-RPC via stdio. O cliente o inicia, pergunta "quais ferramentas você tem?", e a partir de então o modelo pode chamá-las como funções.

O servidor nb2lite-agent expõe exatamente quatro:

As imagens são salvas no disco como gen_<timestamp>_<uuid8>.jpg (ou prefixadas com edit_/edit_local_) — o sufixo UUID evita que gerações concorrentes se sobreponham. Erros retornam como strings de texto 🔴 ... em vez de erros de protocolo, para que o agente possa lê-los e reagir a eles.

E o que é uma habilidade Kiro?

Se o MCP é as mãos (as ferramentas que o Kiro pode chamar fisicamente), uma habilidade é a memória muscular — um arquivo markdown (SKILL.md) mais recursos agrupados que carregam no contexto do Kiro e ensinam o fluxo de trabalho: qual ferramenta usar, em que ordem, com quais restrições.

As habilidades Kiro vivem em .kiro/skills/<nome-da-habilidade>/ dentro de um projeto. Quando o Kiro detecta uma frase de gatilho que corresponde à descrição da habilidade, ele ativa a habilidade automaticamente e começa a usar a orientação codificada lá.

Para nb2lite-image, a habilidade codifica coisas como:

• Chame get_help primeiro ao diagnosticar problemas de configuração — se a chave da API estiver faltando, nada mais funcionará.
• Mantenha os prompts de edição incrementais: descreva a mudança, não a cena.
• Sempre encadeie o último ID de interação.
• Gerações são cobradas — agrupe edições relacionadas e prefira thinking_level: low para rascunhos.

A habilidade também agrupa o próprio servidor MCP (mcp/server.py), seus requisitos, um script de instalação e uma cópia vendida do guia do desenvolvedor da API de Interações — então é autossuficiente: instale a habilidade, e você terá tudo o que precisa para também configurar o servidor.

Instalando: a edição "eu só quero que funcione"

Você precisa de três coisas: Python 3.10+, Kiro, e uma chave da API do Gemini (grátis do Google AI Studio). Escolha um dos caminhos abaixo.

Caminho A: Clonar e inicializar (este repositório)

# 1. Obtenha o código
git clone https://github.com/xbill9/nb2lite-skill-kiro.git
cd nb2lite-skill-kiro

# 2. Configuração com um comando: instala dependências, registra o servidor MCP
#    em .mcp.json, e pr