<div align="center">

🌿 HERMIT PURPLE

O Stand da IA

"O Stand que busca e adivinha informações." — Joseph Joestar

3 interfaces · 16 ferramentas · dados reais, nunca inventados

🚀 Instalação · 🖥️ Hermit CLI · 🤖 Hermit Bot · 🛠️ Ferramentas · ⚡ Modo econômico

</div>

---

✨ O que é

Hermit Purple dá mãos de verdade pra sua IA: busca mangás no MangaDex, escreve código, roda comandos, consulta o clima, salva anotações e conhece o universo de JoJo — tudo com dados reais, nunca alucinados.

Funciona em 3 modos, no PC, Termux (celular) ou servidor:

Modo	O que é	Pra quem é
🖥️ Hermit CLI	Interface estilo Claude Code nas cores roxas do Stand	Quem quer um terminal bonito pra conversar com a IA
🤖 Hermit Bot	Bot do Telegram que responde e executa	Quem quer usar do celular sem abrir terminal
🔌 Servidor MCP	Protocolo padrão da Anthropic	Quem usa Claude Code, Cursor, Codex, LunaCode

---

🚀 Instalação

Opção 1: Termux (Android) — recomendo 😎

# 1. Atualiza o Termux (na primeira vez demora uns 2 min)
pkg update -y && pkg upgrade -y

# 2. Instala Python e ferramentas
pkg install python git -y

# 3. Baixa o projeto
git clone https://github.com/jaivedpereira/hermit-purple
cd hermit-purple

# 4. Instala as dependências (SEM o SDK MCP — ele não funciona no Android!)
pip install requests textual httpx

# 5. (opcional) Se quiser o modo servidor MCP puro, rode num PC:
#    pip install "mcp[cli]" requests

Opção 2: Linux / Mac / WSL

# 1. Clona o projeto
git clone https://github.com/jaivedpereira/hermit-purple
cd hermit-purple

# 2. Cria um ambiente virtual (recomendado)
python3 -m venv .venv
source .venv/bin/activate

# 3. Instala as dependências
pip install "mcp[cli]" requests textual httpx

Opção 3: Windows (PowerShell)

# 1. Clona o projeto
git clone https://github.com/jaivedpereira/hermit-purple
cd hermit-purple

# 2. Cria um ambiente virtual
python -m venv .venv
.venv\Scripts\activate

# 3. Instala as dependências
pip install "mcp[cli]" requests textual httpx

---

🖥️ Hermit CLI — o Claude Code roxo

A interface estilo Claude Code com tema Hermit Purple (fundo preto-roxo, texto lavanda, logo do Stand):

┌─────────────────────────────────────────────────────────┐
│ /new nova conversa   /model modelo   /key chave   ...  │ ← cmdbar
│                                                         │
│              ███  ███  ███  ███                        │
│           HERMIT PURPLE — o Stand da IA                │
│                                                         │
│  🌿 Hermit Purple — o Claude Code do Stand!            │
│  ➤ Você: qual o stand do jotaro?                      │
│  🌿 Hermit Purple: Star Platinum! ORA ORA ORA! ⭐      │
│                                                         │
│  > digite sua mensagem…                                │ ← input
│  v1.0.0 · deepseek-v4-flash-free · 🔑                 │ ← statusbar
└─────────────────────────────────────────────────────────┘

Rodar

python hermit_cli.py

💡 No Termux: o teclado virtual pode não abrir sozinho. Toque no campo de input. Se não abrir: Termux Extra Keys (arraste da borda esquerda) → ícone de teclado, ou Ctrl+Shift+K.

Comandos

Comando	O que faz
/help	Mostra a ajuda
/tools	Lista as 16 ferramentas
/model NOME	Troca o modelo (ex: /model deepseek-v4-flash-free)
/key SK-...	Define a chave da API
/new	Limpa a conversa
/quit	Sai

Atalhos: Ctrl+Q sair · Ctrl+N nova conversa · Ctrl+T ferramentas

---

🤖 Hermit Bot — o agente no Telegram

Transforma o Hermit Purple num bot do Telegram: você manda mensagem, a IA pensa, chama as ferramentas e responde — mesmo com o celular no bolso. 🔋

Tu (Telegram) → Bot → LLM → chama ferramentas → responde

1. Crie o bot no Telegram (2 minutos)

1. Abra o @BotFather no Telegram
2. Envie /newbot
3. Escolha um nome (ex: Hermit Purple)
4. Escolha um username (ex: hermit_purple_bot)
5. Copie o token que ele te der (formato 123456:ABC-DEF...)

2. Configure o bot

# copia o modelo de config
cp .env.example .env

# edita o .env (use nano ou vim) e cola seu token:
nano .env

Dentro do .env:

TELEGRAM_TOKEN=123456:ABC-DEF...          # ← seu token do BotFather
LLM_API_URL=https://opencode.ai/zen/v1/chat/completions
LLM_API_KEY=                              # chave da API (se tiver)
LLM_MODEL=deepseek-v4-flash-free

3. Rode

# em primeiro plano (pra testar)
python hermit_bot.py

# ou em background — fecha o Termux e ele continua vivo!
./run_bot.sh

4. Use

Mande pro seu bot no Telegram:

🗨️ "Tem capítulo novo de Chainsaw Man em português?" 📬 "Cap. 232 — 'Obrigado, Chainsaw Man'! RENTARO SCAN, 02/04/2026. Quer que eu salve pra você lembrar?"

🗨️ "Cria um projeto python chamado app-testes com um main.py que imprime oi" 📬 "✅ Projeto criado em ~/hermit-workspace/app-testes" (e o arquivo já existe no seu celular!)

Comandos: /start boas-vindas · /tools lista ferramentas

---

🔌 Servidor MCP — pluga na sua IA favorita

Claude Code

claude mcp add hermit-purple -- python hermit_purple.py

OpenCode / LunaCode

Adicione no seu opencode.json:

{
  "mcp": {
    "hermit-purple": {
      "type": "stdio",
      "command": "python",
      "args": ["/caminho/para/hermit-purple/hermit_purple.py"],
      "enabled": true
    }
  }
}

Cursor

Settings → MCP → Add new MCP server:

Tipo:    stdio
Comando: python /caminho/para/hermit-purple/hermit_purple.py

Testar sem IA (MCP Inspector)

pip install "mcp[cli]"
npx @modelcontextprotocol/inspector python hermit_purple.py

---

🛠️ Ferramentas

📚 Mangá & Anime

Ferramenta	O que faz
buscar_manga	Busca mangás no MangaDex (foco pt-br): título, autor, status, gêneros
detalhes_manga	Ficha completa por ID: sinopse, nota, autores, estatísticas
capitulos_recentes	Últimos capítulos (pt-br) com scanlation e data
buscar_anilist	Anime/mangá no AniList: nota, popularidade, capítulos

💻 Código (sandbox seguro)

Ferramenta	O que faz
criar_projeto	Cria projeto novo (python / html / node)
listar_pasta	Lista arquivos do workspace
ler_arquivo / escrever_arquivo	Lê e edita código
rodar_comando	Executa comandos shell (timeout 60s)
git_status	Status do repositório git

🔒 As ferramentas de código só mexem dentro de ~/hermit-workspace — nunca fora.

🌍 Utilidades

Ferramenta	O que faz
buscar_musica	Músicas no iTunes com preview de 30s
clima	Previsão do tempo (Open-Meteo, sem chave)
salvar_nota / ler_notas	Anotações em ~/.hermit-purple/notas.md
jojo_stand	Base de 13 Stands de JoJo
hora_agora	Data e hora

---

⚡ Modo econômico

O bot foi feito pra quase não existir no seu celular:

• 📡 Long polling de 50s — ocioso = ~1 requisição/min (em vez de 60/min). ~98% menos dados
• 🔄 Backoff exponencial — se a rede cair, espera 1s → 2s → 4s → … até 60s
• 🔇 Modo silencioso — zero prints, zero IO de console
• ⚡ Só processa quando você fala — parado, CPU em repouso total
• 🪶 Dependência única (requests) — leve, roda no Termux com 2GB de RAM

💡 Resultado: você nem percebe que ele tá ligado — só acorda quando você chama.

---

⚙️ Variáveis de ambiente

Variável	Obrigatório	Default	Descrição
TELEGRAM_TOKEN	p/ bot	—	Token do @BotFather
LLM_API_URL	❌	https://opencode.ai/zen/v1/chat/completions	Endpoint OpenAI-compatível
LLM_API_KEY	❌	vazio	Chave da API
LLM_MODEL	❌	deepseek-v4-flash-free	Modelo padrão
ALLOWED_CHATS	❌	vazio = todos	Chat IDs permitidos (segurança)
HERMIT_WORKDIR	❌	~/hermit-workspace	Pasta de trabalho do código
HERMIT_NOTES	❌	~/.hermit-purple/notas.md	Arquivo de anotações
HERMIT_LONG_POLL	❌	50	Segundos do long polling
HERMIT_QUIET	❌	1	1 = silencioso

---

🧱 Stack

• Python 3.10+
• MCP SDK v2 (MCPServer)
• Textual 8.x — a TUI bonita
• requests — Telegram API, LLM e APIs públicas
• APIs sem chave: MangaDex, AniList, iTunes, Open-Meteo

🗂️ Estrutura

hermit-purple/
├── hermit_purple.py   # servidor MCP + 16 ferramentas
├── hermit_bot.py      # bot do Telegram (modo econômico)
├── hermit_cli.py      # TUI roxa estilo Claude Code
├── run_bot.sh         # sobe o bot em background
├── run_cli.sh         # sobe a CLI
├── .env.example       # modelo de configuração
└── requirements.txt   # dependências

---

🩹 Problemas comuns

❌ Failed to build 'rpds-py' no Termux

Target triple not supported by rustup: aarch64-unknown-linux-android
ERROR: Failed to build 'rpds-py' when installing build dependencies

Por que acontece: o pacote mcp[cli] puxa o rpds-py, que precisa compilar código Rust — e o compilador Rust não suporta o Android do Termux.

Solução: no Termux, não instale o mcp[cli]. O bot e a CLI funcionam só com:

pip install requests textual httpx

O modo servidor MCP puro (pip install "mcp[cli]") é só pra PC / servidor.

---

🧪 Testes

# testa o servidor MCP (handshake + ferramentas)
python test_mcp.py

# testa a CLI (comandos + agente, headless)
python test_cli.py

---

📜 Licença

MIT — feito com 🖤💛 e muito respeito a Araki.

<div align="center">

"Your next line is... 'código brabo demais'!" 😎

</div>