Hermit Purple MCP Server
README.md
<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](#-instalação) · [🖥️ Hermit CLI](#-hermit-cli-o-claude-code-roxo) · [🤖 Hermit Bot](#-hermit-bot-o-agente-no-telegram) · [🛠️ Ferramentas](#-ferramentas) · [⚡ Modo econômico](#-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 😎
```bash
# 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
```bash
# 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)
```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
```bash
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
```bash
# 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`:
```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
```bash
# 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
```bash
claude mcp add hermit-purple -- python hermit_purple.py
```
### OpenCode / LunaCode
Adicione no seu `opencode.json`:
```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)
```bash
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](https://github.com/modelcontextprotocol/python-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
```text
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:
```bash
pip install requests textual httpx
```
O modo servidor MCP puro (`pip install "mcp[cli]"`) é só pra **PC / servidor**.
---
## 🧪 Testes
```bash
# 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>
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues