🔍 GBR: MCP Semantic (Memória Semântica Agnóstica & GraphRAG)

Bem-vindo ao **gbr_mcp_semantic*! Este é o servidor MCP (Model Context Protocol) dedicado a fornecer habilidades de *Memória Semântica e GraphRAG** (Retrieval-Augmented Generation baseada em grafos) para os agentes de IA do monorepo.

🎯 Motivo de Existir

Os agentes de IA precisam lembrar de informações, regras de negócios e estruturas de código encontradas no repositório. Fazer buscas textuais simples (como grep) falha quando a intenção do desenvolvedor ou do LLM é conceitual.

O gbr_mcp_semantic foi criado como um *banco vetorial e de grafos local e agnóstico. Ele utiliza modelos Candle BERT locais e tabelas estruturadas no *DuckDB** para indexar fragmentos de conhecimento (documentos, códigos, ASTs) e realizar buscas por proximidade semântica de alta performance, sem depender de serviços externos na nuvem para vetorização e indexação.

🛠️ Ferramentas Expostas (MCP Catalog)

Este servidor expõe ferramentas "peças de Lego" (agnósticas) para manipulação semântica:

**semantic_search*: - *Descrição: Busca vetorial por similaridade conceitual e similaridade de cosseno em um namespace específico do banco. - Parâmetros: - namespace (String indicando a tabela/contexto). - query (String contendo a busca textual). - limit (Int definindo o limite de resultados retornados).
**semantic_upsert_batch*: - *Descrição: Vetoriza (gerando embeddings via BERT local) e armazena múltiplos documentos de uma só vez em um namespace no DuckDB. - Parâmetros: - namespace (String do contexto de destino). - documents (Lista de strings JSON decodificadas em SemanticDocument contendo id, content e metadata).

🧠 Arquitetura de Memória Semântica

*Separação de Responsabilidades*: A extração de código, parsing de arquivos AST e lógica de chunking de textos são responsabilidade do cliente orquestrador (ex: gbr_ai_gleam). O gbr_mcp_semantic foca estritamente na computação de embeddings e na persistência vetorial/grafos no DuckDB.
*BERT local*: Utiliza a biblioteca nativa gbr_vector para carregar o modelo de embedding BERT em tempo de execução, garantindo privacidade e velocidade local.
*DuckDB*: Banco de dados analítico embarcado de alto desempenho para armazenar vetores e estruturar relações de grafos com suporte SQL avançado.

💻 Como Utilizar

Este projeto é executado automaticamente pelo proxy unificado gbr_ai_gleam, mas você pode iniciá-lo individualmente como um servidor MCP stdio independente:

gleam run

Nota: Na primeira inicialização, pode demorar alguns segundos para carregar o modelo BERT local e estruturar as tabelas DuckDB.

🧪 Rodando Testes e Validações

Para testar a lógica do motor de indexação e buscas semânticas: