Biblioteca Sophia

Sistema local de biblioteca RAG (ChromaDB) para uso com o Claude Desktop via MCP, com interface gráfica para gerenciar bibliotecas e processar PDFs escaneados via OCR.

• Guarde seus próprios livros/PDFs em bibliotecas separadas

• Pesquise o conteúdo deles diretamente dentro de conversas com o Claude, via MCP

• Interface gráfica para criar bibliotecas, adicionar documentos e acompanhar o progresso

• Detecção automática de PDFs escaneados (sem texto digital) + OCR em lote (Tesseract)

Requisitos

• Windows 10/11

• Python 3.10+ — python.org/downloads (marque "Add Python to PATH" durante a instalação)

• Claude Desktop instalado

• (Opcional, só para OCR de PDFs escaneados) Tesseract OCR — github.com/UBMannheim/tesseract/wiki

Related MCP server: MCP-RAG

Instalação

1. Baixe/clone este repositório para uma pasta, ex: D:\BibliotecaSophia

2. Dê dois cliques em instalar.bat. Ele:

   • Verifica se há um Python funcional instalado (e avisa se for só o atalho falso da Microsoft Store)

   • Cria um ambiente virtual isolado (.venv)

   • Instala todas as dependências automaticamente

   • Cria as pastas dados/ e chromadb_storage/

   • Verifica se o Tesseract OCR está presente (avisa se não estiver)

   • Registra automaticamente o servidor no Claude Desktop (edita o claude_desktop_config.json por você, sem apagar outros servidores MCP que você já tenha configurado — faz backup automático antes)

3. Feche e abra o Claude Desktop completamente

4. Pronto — a instalação não se repete depois da primeira vez

Interface web (busca via navegador, sem IA)

Rode python web_interface.py (dentro do .venv) e acesse http://localhost:5000. Página simples para escolher uma biblioteca e buscar, usando a mesma busca híbrida (BM25 + vetorial + re-ranking) do servidor MCP — sem depender de nenhuma IA.

Uso do dia a dia (interface gráfica)

Dê dois cliques em Abrir_Sophia.vbs — abre o painel direto, sem terminal.

O painel tem duas abas:

• Bibliotecas — criar biblioteca nova, adicionar documentos, deletar, ver progresso

• OCR em Lote — aponte uma pasta de PDFs, ele detecta sozinho quais precisam de OCR (PDFs escaneados/fotografados) e gera os .txt prontos para indexar

Nomes de biblioteca: o ChromaDB não aceita acento, espaço ou símbolo no nome interno da coleção. Se você digitar um nome como "Biblioteca Nórdica", a interface ajusta automaticamente para algo como biblioteca_nordica e mostra o resultado antes de confirmar.

Como o conteúdo é processado (chunking)

Cada PDF/TXT é dividido em blocos de aproximadamente 1800 caracteres, respeitando parágrafos, com 20% de sobreposição (overlap) entre blocos consecutivos — isso preserva contexto que ficaria cortado no meio se a divisão fosse rígida. Esse comportamento é o mesmo tanto na indexação via interface gráfica quanto via servidor MCP.

Conectar ao Claude Desktop (MCP)

O instalar.bat já faz esse passo automaticamente. Se precisar rodar de novo manualmente (ex: depois de mover a pasta do projeto):

.venv\Scripts\python.exe configurar_mcp.py

Para remover o registro (ex: antes de desinstalar):

.venv\Scripts\python.exe configurar_mcp.py --remover

Isso edita o arquivo claude_desktop_config.json (normalmente em %APPDATA%\Claude\claude_desktop_config.json), adicionando:

{
  "mcpServers": {
    "biblioteca-sophia": {
      "command": "D:\\BibliotecaSophia\\.venv\\Scripts\\python.exe",
      "args": ["D:\\BibliotecaSophia\\server_chromadb.py"]
    }
  }
}

Sempre mantendo qualquer outro servidor MCP que já esteja configurado, e criando um backup (claude_desktop_config.json.bak) antes de qualquer alteração.

Depois de rodar, feche o Claude Desktop completamente (não só minimizar) e abra de novo. No campo de mensagem, deve aparecer um ícone de ferramentas (martelo) — clique nele para confirmar que o servidor "Biblioteca Sophia" está conectado.

Avançado (opcional): servidor HTTP em segundo plano

Por padrão, o Claude Desktop já funciona via conexão direta (stdio), configurada automaticamente pelo instalar.bat — isso não precisa dessa seção.

Essa parte é útil se você quiser conectar a Biblioteca Sophia em outras ferramentas que falam MCP via HTTP (Qwen, GPT, Grok, AnythingLLM, Mistral, Manus, etc.), mantendo um servidor sempre ativo em segundo plano, sem precisar abrir nada manualmente.

Ativar

1. Clique com o botão direito em registrar_tarefa_sophia.bat → Executar como administrador

2. Isso registra uma tarefa agendada do Windows que sobe o servidor em modo HTTP automaticamente ~30 segundos após o login, sem nenhuma janela visível

3. O endpoint local fica disponível em: http://localhost:8765/mcp

4. Em cada ferramenta (Qwen, GPT, AnythingLLM, etc.), siga a documentação específica dela sobre como adicionar um servidor MCP/ferramenta customizado via HTTP, usando esse endereço local

Desativar

schtasks /delete /tn "BibliotecaSophia" /f

Expor o servidor HTTP pela internet (opcional, avançado)

Por padrão, o servidor HTTP (seção acima) só responde em localhost — funciona apenas na mesma máquina. Se você quiser acessá-lo de fora (por exemplo, de outro computador, ou para conectar ferramentas que não rodam localmente), uma forma comum é usar um túnel do Cloudflare (cloudflared).

Isso é opcional, avançado, e requer uma conta gratuita na Cloudflare e um domínio próprio. Passo básico, generalista:

1. Instale o cloudflared (developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads)

2. Autentique com sua conta Cloudflare: cloudflared tunnel login

3. Crie um túnel: cloudflared tunnel create biblioteca-sophia

4. Configure a rota do túnel para apontar para http://localhost:8765 (via arquivo config.yml do cloudflared, associando um subdomínio seu ao serviço local)

5. Rode o túnel: cloudflared tunnel run biblioteca-sophia

6. O endereço público (ex: https://sophia.seudominio.com/mcp) passa a responder o que está rodando localmente na porta 8765

Atenção: expor esse servidor publicamente significa que qualquer pessoa com o endereço pode consultar suas bibliotecas (não há autenticação embutida no servidor MCP). Se for expor publicamente, considere adicionar autenticação na camada do túnel (a Cloudflare oferece isso via Cloudflare Access) antes de divulgar o endereço. Este README cobre só o básico para você começar — os detalhes finos de configuração de DNS, Access, e segurança ficam por sua conta.

Estrutura de pastas

BibliotecaSophia/
├── instalar.bat                  <- rode uma vez, no início
├── Abrir_Sophia.vbs              <- atalho do dia a dia (sem terminal)
├── configurar_mcp.py             <- registra o servidor no Claude Desktop (roda sozinho no instalar.bat)
├── registrar_tarefa_sophia.bat   <- (opcional) ativa o servidor HTTP em segundo plano
├── iniciar_sophia.vbs            <- (opcional) launcher silencioso do modo HTTP
├── requirements.txt
├── server_chromadb.py            <- servidor MCP (usado pelo Claude Desktop)
├── sophia_unificado.py           <- interface gráfica (Bibliotecas + OCR)
├── gerenciar_bibliotecas.py
├── dados/                        <- seus PDFs/TXTs organizados por biblioteca
└── chromadb_storage/             <- banco de dados vetorial (gerado automaticamente)

Sobre o conteúdo das bibliotecas: este repositório distribui apenas a ferramenta. Os livros/PDFs de cada biblioteca não estão incluídos — cada pessoa monta sua própria coleção de acordo com seu próprio acervo e direitos de uso sobre esse material.

Licença

Este projeto é distribuído sob licença MIT (veja LICENSE) — uso livre, inclusive comercial, desde que o aviso de copyright/crédito original seja mantido nas cópias e distribuições.

Nota: não sou advogado, e isso não é aconselhamento jurídico. A licença MIT é um padrão amplamente usado no mundo open-source justamente porque é simples e permissiva, mas se você quiser uma condição de atribuição mais específica ou restrições adicionais (ex: proibir revenda), vale conversar com um profissional antes de publicar, para redigir os termos exatos que você deseja.

Créditos

Desenvolvido por Rafael — sinta-se livre para usar, adaptar e redistribuir, mantendo o crédito original conforme a licença.