AI工具助手

Assistente de IA com Ferramentas (LangChain + MCP)

Um pequeno assistente conversacional que roda no seu próprio computador. Você conversa com ele pelo terminal — em português — e ele consegue buscar informações reais (CEP, clima, cotação de moedas, ações, criptomoedas, hora atual e mais) usando ferramentas conectadas a serviços públicos da internet.

Pense nele como uma versão simplificada do ChatGPT que não envia seus dados para nenhuma empresa (o modelo de IA roda localmente) e que sabe executar tarefas concretas, não só responder texto.

O que ele sabe fazer hoje

Quando você pergunta algo no chat, o assistente decide sozinho se precisa usar uma ferramenta para te responder. As ferramentas disponíveis hoje são:

Tudo isso é feito de graça, usando APIs públicas (sem precisar de cadastro ou cartão de crédito).

Exemplos do que você pode perguntar

• "Qual o endereço do CEP 01310-100?"
• "Quanto está o dólar hoje?"
• "Qual o preço da PETR4?"
• "Quanto custa 1 Bitcoin em reais?"
• "Como está o tempo em Lisboa?"
• "Que horas são em Tóquio agora?"
• "Sorteia um número entre 1 e 100"

Como ele funciona (em linguagem simples)

O projeto tem três peças que conversam entre si:

   Você ──► Chat (terminal) ──► Cérebro (modelo de IA local) ──► Caixa de ferramentas (MCP Server) ──► Internet

1. O Chat é a janela do terminal onde você digita suas perguntas.
2. O Cérebro é um modelo de IA chamado Qwen 2.5, que roda localmente no seu computador através do Ollama. Ele lê sua pergunta, entende o que você quer, e decide se precisa usar alguma ferramenta.
3. A Caixa de Ferramentas é o MCP Server — um pequeno serviço que expõe todas as ferramentas listadas acima. Quando o Cérebro precisa de uma cotação ou de um CEP, ele "abre a caixa", escolhe a ferramenta certa, e executa.

MCP (Model Context Protocol) é um padrão criado pela Anthropic para que modelos de IA possam usar ferramentas externas de forma segura e organizada. LangChain e LangGraph são as bibliotecas que orquestram tudo isso.

Como rodar

Estas instruções assumem Linux (ou WSL no Windows). Você precisa ter o Docker e o Python 3.12+ instalados. Cada passo abre um terminal diferente — deixe todos abertos.

Pré-requisitos

# verifique se você tem Docker e Python instalados
docker --version
python3 --version    # precisa ser 3.12 ou superior

Passo 1 — Subir o modelo de IA local (Ollama + Qwen 2.5)

No terminal 1:

docker build -f Containerfile.ollama -t ollama-mistral .
docker run -p 11434:11434 --name ollama-mistral ollama-mistral

Na primeira execução, o Docker vai baixar o modelo (alguns gigabytes — pode demorar). Deixe esse terminal aberto.

Da próxima vez, basta rodar docker start -a ollama-mistral.

Passo 2 — Subir a caixa de ferramentas (MCP Server)

No terminal 2:

docker build -f Containerfile.mcp_server -t mcp-server .
docker run -p 8000:8000 --name mcp-server mcp-server

Da próxima vez, basta rodar docker start -a mcp-server.

Passo 3 — Iniciar o chat

No terminal 3, instale as dependências e rode o cliente:

# instala o gerenciador de pacotes uv (se ainda não tiver)
pip install uv

# cria ambiente virtual e instala dependências
uv venv .venv
uv sync

# inicia o chat
.venv/bin/python -m modules.agent_chat.main

Pronto! Você verá:

================== USER ==================
Para sair digite q ou exit:

Digite sua pergunta e divirta-se. Para encerrar, digite q ou exit.

Memória da conversa (SQLite)

O chat lembra do que você conversou antes, mesmo depois de fechar e abrir o programa. As mensagens ficam salvas em um arquivo SQLite local: agent_memory.db (criado automaticamente na primeira execução).

Você pode personalizar via variáveis de ambiente (opcional):

Use o arquivo .env.example como ponto de partida — copie para .env e ajuste o que precisar:

cp .env.example .env

Exemplo — duas conversas separadas no mesmo banco:

THREAD_ID=trabalho   .venv/bin/python -m modules.agent_chat.main
THREAD_ID=pessoal    .venv/bin/python -m modules.agent_chat.main

Para apagar a memória, basta deletar o arquivo:

rm agent_memory.db

Estrutura do projeto

langchain-with-mcp/
├── modules/
│   ├── agent_chat/         # o chat (cliente que conversa com você)
│   │   ├── main.py         # ponto de entrada do chat
│   │   └── config/         # configura o modelo e a conexão com o MCP
│   ├── mcp_server/         # a caixa de ferramentas
│   │   ├── server.py       # ponto de entrada do servidor
│   │   ├── config/         # registro automático de ferramentas
│   │   └── domain/         # uma pasta por categoria de ferramenta
│   │       ├── location/   # CEP
│   │       ├── finance/    # moedas, ações, cripto
│   │       ├── weather/    # clima
│   │       └── generic/    # utilidades (hora, aleatório, curiosidade)
│   └── base_common/        # logger e variáveis de ambiente compartilhados
├── Containerfile.ollama    # imagem do modelo de IA
├── Containerfile.mcp_server# imagem da caixa de ferramentas
└── pyproject.toml          # dependências do projeto

Como adicionar uma ferramenta nova

Cada ferramenta é uma função Python simples decorada com @register_tool. Por exemplo:

@register_tool(
    name="minha_ferramenta",
    description="Explica o que ela faz, em português.",
)
def minha_ferramenta(parametro: str) -> dict:
    return {"resultado": parametro.upper()}

Coloque o arquivo dentro de modules/mcp_server/domain/<categoria>/, importe-o no server.py, reinicie o servidor — e o assistente já saberá usá-la automaticamente.

Tecnologias usadas

• Ollama + Qwen 2.5 7B — modelo de IA rodando localmente
• LangChain / LangGraph — orquestra a conversa e as decisões do agente
• AsyncSqliteSaver (LangGraph) — persiste o histórico da conversa em SQLite local
• FastMCP — servidor MCP em Python
• langchain-mcp-adapters — conecta o LangChain ao MCP
• APIs públicas gratuitas: OpenCEP, AwesomeAPI, brapi.dev, CoinGecko, wttr.in, uselessfacts

Privacidade

• O modelo de IA roda 100% no seu computador (via Docker + Ollama). Suas perguntas não são enviadas para a OpenAI, Anthropic, Google etc.
• As ferramentas consultam serviços públicos da internet (ex.: para saber a cotação do dólar, é preciso conectar à AwesomeAPI). Os dados que trafegam são apenas os parâmetros da consulta (ex.: o CEP, o nome da cidade, o ticker da ação) — nunca o histórico do seu chat.