Bem-vindos ao BrainAPI!

Aprenda como criar sistemas de IA que conversam com APIs usando linguagem natural

Olá! Eu sou o BrainAPI 🧠

Sou um assistente inteligente que vai te ensinar como criar sistemas de IA que conseguem "conversar" com APIs usando linguagem natural. Imagine poder dizer "Consulte meu saldo" e eu entender exatamente qual API chamar e como fazer isso!

Nesta jornada, você vai aprender conceitos fundamentais de forma técnica e prática.

Interface Natural

Converse com suas APIs usando linguagem humana, sem necessidade de conhecimento técnico sobre a implementação.

Conversão Automática

Transforma especificações OpenAPI em ferramentas de IA (MCP) de forma automática, economizando horas de trabalho.

IA Avançada

Utiliza o poder do Google Gemini via ADK, com flexibilidade para integrar outros LLMs, inclusive modelos locais.

Ecossistema Tecnológico

OpenAPI

OpenAPI Specifications

Java 17+

Linguagem principal

Spring Boot

Framework Web

Google ADK

Framework de Agentes

MCP Protocol

Comunicação com Tools

MCP Toolbox

Server MCP

Docker

Containerização

Node.js

Para MCP Inspector

O que é um Agent?

Sistemas de IA que podem entender, raciocinar e agir

Agent = Sistema Inteligente Autônomo

Um Agent é um sistema de IA que:

👂

Entende comandos em linguagem natural

🧠

Raciocina sobre qual ação tomar

🔧

Executa tarefas usando ferramentas disponíveis

💬

Responde de forma contextual e inteligente

🎯 Experimente um Agent em ação:

Aguardando comando...

MCP - Model Context Protocol

O protocolo padrão para conectar LLMs a fontes de dados e ferramentas. Saiba mais

MCP = Protocolo Universal

O Model Context Protocol é um padrão aberto que:

🔌

Padroniza como LLMs se conectam a dados externos

🌐

Define arquitetura cliente-servidor

🔄

Especifica como expor recursos, prompts e ferramentas

🔒

Garante conexões seguras e bidirecionais

🏗️ Arquitetura MCP:

MCP Server

Expõe capacidades

Resources: Dados e conteúdo
Tools: Funções executáveis
Prompts: Templates interativos

MCP Client

Consome capacidades

LLM Applications: Claude, ChatGPT
AI Agents: Sistemas autônomos
Development Tools: IDEs, assistentes

🔗 Analogia: MCP como USB-C

Pense no USB-C: aquele conector universal que, num piscar de olhos, liga seu celular, notebook e periféricos sem frescura. O MCP faz o mesmo pelo mundo da IA — é o padrão que conecta qualquer modelo a toda fonte de dados e ferramenta que você imaginar, sem gambiarra nem dor de cabeça.

Consulte: Docker MCP HUB

# Antes do MCP: Cada IA tinha sua própria forma de conectar

Claude → Formato A → API

ChatGPT → Formato B → API

Gemini → Formato C → API

# Com MCP: Padrão universal

Qualquer LLM → MCP Protocol → Qualquer Ferramenta

MCP toolbox

A implementação prática do servidor MCP. Saiba mais

MCP toolbox = Implementação Prática

O MCP toolbox é a implementação do protocolo MCP no ADK:

🛠️

MCPToolset Class: Classe principal para integração

🔄

Auto-discovery: Descobre ferramentas automaticamente

🔌

Connection Management: Gerencia conexões stdio/SSE

🎯

Tool Filtering: Filtra ferramentas específicas

MCP (Protocolo)

O padrão universal

Define como a comunicação deve acontecer
Especifica formatos de mensagens
Estabelece arquitetura cliente-servidor
Criado pela Anthropic
Analogia: Como o protocolo HTTP

MCP toolbox (Implementação)

A ferramenta prática

Implementa o protocolo MCP dentro do ADK
Fornece classes e métodos prontos
Facilita integração com agentes ADK
Desenvolvido pelo Google
Analogia: Como um navegador web que usa HTTP

ADK - Agent Development Kit

Framework do Google para desenvolvimento de agentes de IA. Saiba mais

ADK = Framework Completo

O Agent Development Kit oferece:

🏗️

Framework: Estrutura completa para agentes

🌐

WebServer: Interface web integrada

🔗

Integração: Suporte nativo ao MCP

☕

Multi-linguagem: Python e Java

🏛️ Arquitetura ADK:

🎯

Agent Core

Lógica principal de IA e processamento

🌐

WebServer

Interface web para interação

🔌

MCP Client

Conexão com ferramentas externas

OpenAPI → tools.json

Conversão automática de especificações OpenAPI em ferramentas MCP

O Tradutor Automático

O openapi-mcp-java automatiza a conversão:

📖

Lê arquivos OpenAPI/Swagger

🔄

Converte cada endpoint em ferramenta

📝

Gera tools.json compatível com MCP

⚡

Automatiza todo o processo de integração

⚙️ Processo de geração:

# Compilar o gerador

cd openapi-mcp-java
mvn clean package

# Gerar ferramentas a partir do OpenAPI

java -jar target/openapi-mcp-1.0-jar-with-dependencies.jar > tools.json

🔄 Pipeline de transformação:

📄

openapi.yaml

Especificação da API REST

🔧

openapi-mcp-java

Gerador de ferramentas

📦

tools.json

Ferramentas MCP prontas

💡 Exemplo de conversão:

# OpenAPI Specification

paths:
  /cards/{uuid}

    get:

        summary: "Get card by UUID"

        parameters:

              - name: uuid

                  in: path

                  required: true

↓ Vira ferramenta MCP ↓

{

    "name": "get-card-by-uuid",

    "description": "Get card by UUID",

    "inputSchema": {

        "type": "object",

        "properties": {

           "uuid": { 
      "type": "string" 
     }

        }

    }

}

Agent entende: "Consulte o cartão abc123" → get-card-by-uuid(uuid: "abc123")

BrainAPI em Ação

Integrando todos os componentes em um sistema completo

🎯 Simulação do BrainAPI:

Pronto para responder suas perguntas!

🎯 Visão Geral

Transforme especificações de API em respostas inteligentes com IA conversacional.

O BrainAPI é um sistema que combina Inteligência Artificial conversacional com APIs REST, permitindo que usuários interajam com APIs utilizando linguagem natural.

Ao invés de fazer chamadas HTTP manuais (curl, Postman, etc), você pode simplesmente perguntar:

"Qual o status do cartão com UUID b4ff0172-3a01-4aca-96f0-72247c5ba34c?"

E o sistema automaticamente:

🧠 Entende sua intenção usando IA
🔍 Identifica qual API chamar
⚙️ Executa a chamada HTTP apropriada
💬 Retorna a resposta em linguagem natural

🌟 Principais Características

🗣️ Interface Natural: Converse com APIs usando linguagem humana
🔄 Conversão Automática: OpenAPI → Ferramentas MCP automaticamente
🤖 IA Avançada: Powered by Google Gemini via ADK (ou outra LLM, até local!)
🐳 Containerizado: Deploy fácil com Docker
🌐 Interface Web: WebServer integrado para interação
🔧 Extensível: Adicione novas APIs facilmente

Java 17+ Spring Boot Google ADK MCP Toolbox Node.js Docker Ready OpenAPI 3.1

🏗️ Arquitetura

Entenda como os componentes do BrainAPI se conectam.

🧩 Componentes do BrainAPI

O BrainAPI é composto por três componentes principais que trabalham juntos:

🛠️ Geração de Tool
🤖 Agente
🧰 MCP Toolbox

🔄 Fluxo de Funcionamento

Especificação: APIs são documentadas em formato OpenAPI
Geração: openapi2mcp-toolbox converte endpoints em ferramentas MCP
Hospedagem: MCP Toolbox serve as ferramentas via protocolo MCP
Processamento: ADK Agent processa linguagem natural e chama ferramentas
Resposta: Resultado é formatado em linguagem natural para o usuário

🧩 Componentes Detalhados

1. OpenAPI → MCP Generator openapi2mcp-toolbox

Função: Converte especificações OpenAPI em ferramentas MCP

Input: openapi.yaml com definições de APIs

Output: tools.json com ferramentas prontas para uso

Tecnologia: Java + Maven

2. MCP Toolbox Docker

Função: Hospeda ferramentas via Model Context Protocol

Protocolo: MCP (da Anthropic)

Interface: HTTP + Server-Sent Events (SSE)

Tecnologia: Docker container

3. ADK Agent Java + WebServer

Função: Interface de IA conversacional

Framework: Google Agent Development Kit (ADK)

LLM: Google Gemini 2.0 Flash (ou outro, inclusive local)

Interface: Web UI integrada

📋 Pré-requisitos

Software e chaves necessárias para rodar o projeto.

🔧 Software Necessário

Componente	Versão Mínima	Download
Java JDK	17+	OpenJDK
Maven	3.6+	Apache Maven
Docker	20.0+	Docker
Node.js	16+	Node.js
Git	2.0+	Git

🔑 Chaves de API

É necessária uma Google AI Studio API Key para o ADK Agent. Você pode obtê-la em Google AI Studio e configurá-la como uma variável de ambiente chamada `GOOGLE_API_KEY`.

🔍 Verificação do Ambiente

Execute os comandos abaixo para verificar se tudo está instalado:

                    # Verificar Java

                    java -version

                    # Verificar Maven

                    mvn -version

                    # Verificar Docker

                    docker --version

                    # Verificar Node.js

                    node --version

                    # Verificar Git

                    git --version

🚀 Instalação e Configuração

Passo a passo para colocar o BrainAPI para funcionar.

1️⃣ Clone o Repositório e Configure a API Key

                    git clone https://github.com/cesarschutz/BrainAPI.git

                    cd BrainAPI

                    export GOOGLE_API_KEY="sua-chave-aqui"

2️⃣ Configure a API Key

                    # Linux/macOS

                    export GOOGLE_API_KEY="sua-chave-do-google-ai-studio"

                    # Windows (PowerShell)

                    $env:GOOGLE_API_KEY="sua-chave-do-google-ai-studio"

                    # Windows (CMD)

                    set GOOGLE_API_KEY=sua-chave-do-google-ai-studio

3️⃣ Gere as Ferramentas MCP

                    # Navegue para o gerador e compile

                    cd openapi2mcp-toolbox

                    mvn clean package

                    # Gere o arquivo tools.json na raiz do projeto

                    java -jar target/openapi-mcp-1.0-jar-with-dependencies.jar > ../tools.json

                    cd ..

4️⃣ Inicie o MCP Toolbox com Docker

                    export VERSION=0.6.0

                    docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

                    docker docker run -d -p 5001:5000 --platform linux/amd64 -v "$(pwd)/tools.yaml:/tools.yaml" us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.6.0 toolbox --tools-file /tools.yaml --address 0.0.0.0

5️⃣ Verificação do MCP Toolbox

                    # Instalar e executar MCP Inspector

                    npx @modelcontextprotocol/inspector

Abra: http://127.0.0.1:6274
Configure:
Transport type: SSE
URL: http://127.0.0.1:8080/mcp/sse
Clique em "Connect" e depois "List Tools"

6️⃣ Execute o ADK Agent

                    # Navegue para o agente

                    cd BrainAPI-agent

                    # Execute com o WebServer na porta 8081

                    mvn compile exec:java "-Dexec.args=--server.port=8081"

Após esses passos, a interface web estará acessível em http://localhost:8081.

💡 Como Usar

Exemplos práticos de interação com o BrainAPI.

🎯 Interface Web

Acesse: http://localhost:8081

Digite: Sua pergunta em linguagem natural

Aguarde: O processamento da IA

Receba: Resposta formatada

📝 Exemplos de Comandos

👤 Usuário: "Consulte o cartão com UUID b4ff0172-3a01-4aca-96f0-72247c5ba34c"

🤖 BrainAPI: Consultando cartão...

📊 Resultado: Cartão ativo, limite R$ 5.000, disponível R$ 3.750

👤 Usuário: "Qual o status do meu cartão?"

🤖 BrainAPI: Para consultar seu cartão, preciso do UUID. Você pode fornecer?

🔧 Comandos Avançados

O BrainAPI entende diversos tipos de solicitações:

Consultas: "Mostre informações do cartão com uuid b4ff0172-3a01-4aca-96f0-72247c5ba34c"
Filtros: "Liste cartões do customer uuid eb58556d-e468-49fe-b3b8-02220e878897"
Operações: "Bloqueie o cartão b4ff0172-3a01-4aca-96f0-72247c5ba34c"
Relatórios: "Gere relatório de transações do mês do cartão b4ff0172-3a01-4aca-96f0-72247c5ba34c"

🛠️ Tecnologias

Frameworks, protocolos e ferramentas que movem o BrainAPI.

🛠️ Principais Tecnologias

Tecnologia	Uso	Link
Google ADK	Framework para desenvolvimento de agentes	Documentação
GenAI Toolbox (MCP)	Servidor de ferramentas MCP	Repositório
Spring Boot	Framework para o WebServer	Site Oficial
OpenAPI 3.x	Especificação de APIs	Site Oficial
Docker	Containerização do MCP Toolbox	Site Oficial