Português · English
Motor de busca em documentação técnica para agentes de IA. O Castalia indexa a documentação do seu sistema e a entrega via MCP a agentes como GitHub Copilot, Cursor, Claude Code, Codex e Kiro, para que cenários de teste sejam escritos a partir das regras documentadas, com a fonte de cada uma.
Ele não gera texto nem tem agente próprio: encontra os trechos certos e deixa a escrita para o agente que você já usa.
Diferenciais
- Cenário com fonte. Cada trecho vem com o caminho de títulos (
Transferências > Limites) e o link de origem, então cada cenário aponta a regra que o justifica. - Lacuna em vez de suposição. Quando nenhuma regra documentada corresponde à busca, o resultado vem vazio, e o agente registra a falta de documentação em vez de inventar comportamento.
- Documentação como ela está. Markdown, MDX, reStructuredText, HTML e PDF na mesma pasta, incluindo exports de portais fechados.
- Embeddings na nuvem ou locais. OpenAI, Ollama ou qualquer API de embeddings compatível com OpenAI.
- Qualquer cliente MCP. Exemplos prontos para seis clientes, todos usando o mesmo servidor.
Como funciona
flowchart LR
DOCS["Documentação<br/>MD, HTML, PDF, reST"] --> ING["Ingestão"]
ING --> DB[("PostgreSQL<br/>+ pgvector")]
DB --> MCP["Servidor MCP"]
MCP --> AG["Seu agente<br/>escreve os cenários"]
- Ingestão: cada arquivo é convertido para texto, dividido em trechos pelos títulos e indexado com embeddings.
- Consulta: o agente chama as ferramentas do servidor MCP e recebe os trechos relevantes com a fonte.
- Geração: o agente escreve os cenários citando as regras e sinaliza o que não está documentado.
Começando
Pré-requisitos: JDK 21, Docker e uma chave da OpenAI ou o Ollama instalado.
1. Suba o banco e compile
docker compose up -d
./mvnw -q package -DskipTests
2. Configure os embeddings
# OpenAI
export OPENAI_API_KEY=sk-...
# ou Ollama local, sem chave
ollama pull nomic-embed-text
export CASTALIA_EMBEDDING=ollama
export CASTALIA_EMBEDDING_DIMENSIONS=768
3. Indexe a documentação
java -jar castalia-ingestion/target/castalia-ingestion.jar ingest ./corpus
Para experimentar sem documentação própria, use o corpus fictício já versionado:
java -jar castalia-ingestion/target/castalia-ingestion.jar ingest docs/demo-corpus.
O script opcional ./scripts/prepare-corpus.sh baixa a documentação do Kubernetes.
4. Conecte o agente
Copie a configuração do seu cliente de examples/ para o seu projeto e ajuste o caminho do jar:
| Cliente | Configuração |
|---|---|
| VS Code com GitHub Copilot | .vscode/mcp.json |
| Cursor | .cursor/mcp.json |
| Claude Code | .mcp.json |
| Codex | .codex/config.toml |
| Kiro | .kiro/settings/mcp.json |
| Claude Desktop | claude_desktop_config.json |
Os exemplos incluem as instruções do agente: buscar antes de escrever, citar a fonte em cada cenário e sinalizar lacunas.
Demonstração mínima / minimal demo (Bash e PowerShell)
Ferramentas MCP
| Ferramenta | O que faz |
|---|---|
search_docs |
Busca as regras relacionadas a um tema ou critério de aceite. |
get_document |
Devolve o documento completo quando um trecho não basta. |
list_sources |
Lista o que está indexado. |
Contribuindo
Arquitetura, pipeline de ingestão, perfis de documentação, configuração completa e como rodar os testes estão em CONTRIBUTING.md.
Licença
GNU AGPL-3.0. Você pode usar, estudar, modificar e redistribuir o Castalia. Versões modificadas, inclusive as oferecidas a outras pessoas pela rede, precisam ser distribuídas sob a mesma licença e com o código-fonte disponível.
O corpus de exemplo baixado por scripts/prepare-corpus.sh é a documentação do Kubernetes, © The Kubernetes Authors, sob CC BY 4.0, usada apenas localmente.
