Como tirar o máximo do servidor MCP do Geneziz

Você rodou geneziz mcp register e seu assistente agora enxerga a sua base de conhecimento. A conexão é a parte fácil: o valor vem de como você a usa. Este é o guia que nós mesmos usamos, escrito para os dois lados da sessão: o humano que prompta e o agente que aciona as tools.

Regra 1: Oriente-se antes de buscar

Uma base de conhecimento não é um índice da web. Antes de buscar, um bom agente gasta uma round-trip entendendo o que existe lá, usando só tools:

get_recent(days=7, limit=10)   → o que foi salvo recentemente
list_categories()              → o formato do acervo (tools, artigos, tópicos)
list_tags(limit=20)            → como ele está organizado
list_domains()                 → de quais fontes você realmente salva

Isso evita o clássico modo de falha: buscar algo que a base simplesmente não tem e alucinar em volta do resultado vazio.

Nota: os números gerais vivem no resource knowledge://stats, não numa tool. Clientes que exibem resources do MCP conseguem lê-lo; assistentes que só listam tools devem se orientar com as quatro chamadas acima.

Regra 2: Duas tools de busca, dois trabalhos diferentes

O Geneziz traz duas tools de busca, e escolher a certa primeiro é, isoladamente, a maior economia de tempo:

Padrão prático para um agente: comece pelo search_fulltext; escale para search_knowledge só quando os resultados por palavra-chave parecerem próximos-mas-errados. A busca semântica lê mais, mas responde perguntas mais vagas. Não pague por ela quando a string exata "FastMCP import error" já está nas suas notas.

Dois comportamentos que vale conhecer:

• O search_knowledge degrada com elegância: se o índice vetorial não foi construído, ele devolve um marcador degraded: true junto com resultados best-effort por palavra-chave, em vez de falhar. Agentes devem tratar os dois formatos.
• O servidor tem rate-limit (~120 chamadas por minuto). Agrupe as leituras; não faça consultas em loop fechado.

Ambas devolvem snippets destacados. Quando um resultado importa, não pare no snippet:

Regra 3: Snippet é triagem, leia e expanda

search_* dá um preview. Quando o hit é o certo, puxe o arquivo inteiro com o slug que o resultado já traz:

get_article(name="local-first-vs-cloud-bookmarks")
get_tool(name="ripgrep")

E então faça o que a busca não faz: expanda para os lados.

find_related(filename="local-first-vs-cloud-bookmarks", limit=5)

O find_related devolve os vizinhos mais próximos de um arquivo em que você já confia: é o caminho mais rápido de um bom hit para os cinco artigos que pertencem a ele. E se a sua base é pesada em bookmarks, o get_bookmark(author="...") puxa entradas do X.com ricas (texto, engajamento, pastas) diretamente.

Regra 4: Liste com filtros, não com limits gigantes

list_tools e list_articles paginam (limit tem teto de 100, use offset). Empurre seu assistente para listagens filtradas em vez de "lista tudo":

list_tools(category="ai", limit=20)
list_articles(domain="github.com", tag="rust")

Paginar com offset significa "me dê os próximos 20 da mesma consulta", não "me dê 400 itens que eu vou rolar". Sua janela de contexto agradece.

Regra 5: Salve com intenção, e saiba quando vira pesquisável

Duas tools de captura, dois propósitos:

• add_note(title, body): escreva uma nota de verdade. Use para decisões, aprendizados, trechos que você quer achar depois. Tageie (tags=["rust", "perf"]): tags são o jeito do seu-eu-do-futuro buscar.
• save_url(url, note="..."): arquiva o link com uma anotação opcional. Ele não baixa a página. É um stub: URL + sua nota, ~450 bytes. Por design: a captura de página completa é trabalho da extensão do navegador (que guarda o snapshot inteiro), e hydrate/enrich podem preencher o corpo depois.

O erro a evitar: um agente "salvar um artigo" com save_url e nota vazia, e depois não entender por que a busca não acha o conteúdo do artigo. Se o conteúdo importa agora, ele vai na note, ou é capturado pela extensão.

Quando os saves aparecem na busca? Quando o indexador rodar da próxima vez (o pipeline do app desktop faz isso automaticamente; de um terminal é geneziz index). Um arquivo salvo há segundos ainda não é pesquisável, e isso é esperado. Diga isso ao seu agente, ou ele vai "verificar" o save com uma busca e reportar falha erradamente.

Tudo que é salvo via MCP carrega a proveniência real (via: MCP save / a tag mcp-note), então itens salvos por agentes são sempre distinguíveis dos salvos pela extensão nas suas estatísticas.

Regra 6: Limpe enquanto estiver aí

find_duplicates(threshold=0.92) aponta artigos quase duplicados por similaridade de embedding. Ele é só-relatório: nunca mescla nem apaga nada. Rodá-lo de vez em quando e mesclar à mão o que ele apontar mantém a busca semântica honesta: duplicatas não só ocupam espaço; dividem a "mesma" ideia entre vetores e diluem os resultados.

Uma sessão real, do início ao fim

Isto não é hipotético: é como o guia acima foi validado. Um agente terminou um setup de ferramentas e fechou o ciclo em três movimentos: save_url ×7 para os artigos de referência (cada um com uma linha de por quê), add_note ×1 para o registro da decisão (tags: best-practices, mcp, dogfooding), e uma rodada de indexação. Toda sessão futura (qualquer cliente MCP, não só a que salvou) agora consegue buscar o raciocínio, não só os links.

Um prompt compacto para o seu assistente

Se você usa Claude Code, Cursor, ZCode ou qualquer cliente MCP, cole isto nas instruções do seu projeto. Ele codifica tudo acima:

Ao trabalhar com a base de conhecimento do Geneziz:
1. Oriente-se antes: get_recent(7), list_categories, list_tags. Nunca busque às cegas.
2. search_fulltext para nomes/erros exatos; escale para search_knowledge só
   em conceitos vagos. Trate o formato de fallback "degraded".
3. Leia itens completos com get_article/get_tool usando o slug dos resultados,
   depois expanda com find_related. Rate limit ~120 chamadas/min: agrupe leituras.
4. Liste com filtros (category/domain/tag) + paginação offset; nunca peça
   listas sem limite.
5. save_url arquiva URL + nota APENAS (sem fetch; ponha o conteúdo-chave na
   note). add_note para aprendizados soltos, sempre com tags. Saves novos
   ficam pesquisáveis só depois o indexador rodar, não "verifique" um save
   buscando por ele imediatamente.
6. Rode find_duplicates de vez em quando; mescle os achados à mão.

O hábito que acumula

Todas as tools acima são, em sua maioria, de leitura por design: a superfície MCP é segura para deixar um agente explorar. O efeito acumulativo vem da Regra 5: cada sessão que termina com add_note("o que decidimos", ...) ou um save_url bem anotado deixa as Regras 1–4 da próxima sessão mais inteligentes. Esse é o ponto todo de um segundo cérebro: ele deve ficar melhor em te ajudar simplesmente porque você o usou.