Verifica a saúde do servidor MCP e do banco default.

Use quando: Diagnosticar falhas ou confirmar que o servidor está operacional. Retorna: {status: ok|error, database: connected | motivo, version, schema_version, toolset}. Exemplo: health_check() Notas: Valida a conexão e a presença de todas as tabelas (inclusive a de busca textual).

Pacote de contexto do projeto: regras, contexto, decisões, padrões, procedimentos.

Use quando: Começar num projeto (se o hook não injetou) ou ao passar a mexer em outra área: paths traz as regras com escopo daqueles arquivos; query, itens relacionados. Retorna: {linked, project_key, workspace, domain, markdown, included, omitted, sensitive}. Exemplo: context_get(project=".", paths=["src/payments/Charge.java"], query="estorno") Notas: Dentro de budget_tokens. Itens que casam com paths ou query vêm em foco, com o começo do content (dispensa item_get); o resto, só título, resumo e key. sensitive é true se paths toca uma área marcada com a keyword "sensivel". Inclui o domain do projeto, Geral do workspace e Global/Geral. Sem substituídos, obsoletos nem ephemeral.

Busca por texto. Devolve resumos, nunca o conteúdo completo.

Use quando: Procurar algo que pode já estar guardado (decisão, gotcha, procedimento). Retorna: [{id, key, type, memory_class, domain, title, summary, score, uses}]. Exemplo: item_search(query="migração flyway", limit=5) Notas: Sem project/workspace, busca no projeto da pasta atual (se ligado) — não vaza para outros projetos; everywhere=True busca em todos. Relevância primeiro; acentos e plurais não atrapalham. include_inactive traz substituídos, obsoletos e ephemeral vencidos.

Lê itens completos (content, tags, relações, anexos) por id e/ou key, vários de uma vez.

Use quando: O resumo da busca ou do contexto não bastou. Retorna: Lista de itens completos, na ordem pedida; o que não existe vem como {key|id, missing: true}, sem derrubar os outros. Exemplo: item_get(keys=["regra/money", "proc/deploy"], project=".") Notas: keys exigem project (o domain ligado) ou workspace e domain. Até 20 por chamada.

Grava itens (criar, atualizar, upsert, renovar, relacionar) numa transação.

Use quando: Guardar o que vale para depois — uma regra que o usuário enunciou, as decisões e aprendizados ao fechar uma mudança, uma correção de um item. Retorna: [{index, id, key, action: created|updated|unchanged, similar?, relations?}]. Modo, por entrada: com key → upsert no domain (não duplica; o preferido); com id → atualiza o item; sem os dois → cria e devolve similar (títulos parecidos já guardados). Exemplo (upsert): item_save(project=".", items=[{"key": "regra/money", "type": "rule", "title": "Money em pagamentos", "summary": "Valores em Money, nunca double", "content": "...", "scope_paths": ["src/payments/**"], "source": "PAY-142"}]) Exemplo (aposentar): item_save(project=".", items=[{"key": "regra/x", "status": "deprecated"}]) Exemplo (substituir): item_save(project=".", items=[{"key": "proc/deploy-v2", ..., "relations": [{"type": "supersedes", "target": "proc/deploy"}]}]) Campos: type (rule, insight, procedure, pattern, knowledge, context, artifact, task), title, summary, content, keywords, source, scope_paths, status (active, done, superseded, deprecated), memory_class "ephemeral" + ttl_days só para nota temporária (sem aprovação: o resto já vale), tags, labels, relations [{type: related_to|depends_on|implements|references|supersedes|derived_from, target: id ou key}], workspace/domain (sem eles vale o domain ligado a project). Segredo: {"key": "segredo/npm-token", "type": "secret", "title": "Token do npm", "summary": "publicar no npm"} — sem valor (é recusado); a resposta traz fill_url: passe ao usuário para ele preencher na UI local. Usar: knowledge-mcp run --env NPM_TOKEN=segredo/npm-token -- <comando>. Notas: Um erro desfaz o lote e aponta a entrada. Conteúdo com cara de segredo é recusado.

Liga um repositório a um workspace/domain do segundo cérebro.

Use quando: Configurar um projeto pela primeira vez (o /plumb-setup faz isso). Retorna: {project_key, workspace, domain}. Exemplo: project_link(project=".") → domain = repo; workspace = o de outro repo do mesmo dono já ligado (no primeiro, o nome do dono; sem remote, Pessoal). Organização: workspace = contexto (empresa, cliente, Pessoal); Geral do workspace = o que vale para os repos dele; Global = o que vale em qualquer lugar. Notas: project aceita caminho (qualquer pasta do repo), URL do remote ou chave; a chave é o remote do git normalizado (ou o caminho, sem remote). Workspace e domain são criados se não existirem. Religar move o projeto.

Árvore workspaces → domains com a contagem de itens.

Use quando: Ver o que existe antes de organizar, ligar um projeto ou fazer backup. Retorna: [{workspace, description, items, domains: [{name, items}]}]. Exemplo: structure_list() · structure_list(workspace="agenda-api") Notas: Criar workspace/domain é implícito em item_save e project_link.

Remove um domain (ou o workspace inteiro) com todos os itens. Destrutivo.

Use quando: O usuário pediu explicitamente para apagar. Retorna: Sem confirm: {status: preview, would_delete}. Com confirm: {status: deleted}. Exemplo: structure_delete(workspace="Teste", confirm=True) Notas: Chame primeiro sem confirm e mostre o preview ao usuário. Prefira backup_export antes, e status=deprecated (item_save) quando o histórico importar.

Remove um item de vez (com tags, relações e anexos). Destrutivo.

Use quando: O item está errado e não há histórico a preservar. Retorna: {status: deleted, id}. Exemplo: item_delete(item_id="...") Notas: Para aposentar mantendo o histórico, prefira item_save com status=deprecated ou uma relação supersedes.

Remove uma relação entre itens (o id vem em item_get → relations).

Use quando: Uma relação foi criada por engano. Retorna: {status: deleted, id}. Exemplo: relation_delete(relation_id="...") Notas: Remover um supersedes não reativa o alvo: ajuste o status com item_save.

Vocabulário da base: tags (livres) e labels (lista controlada).

Use quando: Reaproveitar tags existentes antes de criar variações, ou gerir labels. Retorna: list → [{id, name}]; create → {id, name}; delete → {status: deleted}. Exemplo: vocabulary(kind="tags") · vocabulary(kind="labels", action="create", name="lgpd") Notas: kind: tags | labels. action: list | create (name) | delete (id). Tags também são criadas direto no item_save.

Exporta um workspace (ou só um domain) para um ZIP em /exports.

Use quando: Antes de mudanças grandes ou para levar conhecimento a outra máquina. Retorna: {status: ok, file_path, size_mb}. Exemplo: backup_export(workspace="agenda-api") · backup_export(workspace="agenda-api", domain="projpro") Notas: backup_import restaura (o workspace importado ganha ids novos).

Importa um ZIP de backup_export: workspace inteiro, ou um domain dentro de workspace.

Use quando: Restaurar um backup ou trazer conhecimento de outra máquina. Retorna: {status: ok, ...workspace ou domain criado}. Exemplo: backup_import(file_path="C:/x/workspace_....zip") Notas: Use só caminhos que o usuário indicou. Nome de workspace já existente é recusado.

Anexa um arquivo local a um item (copiado para /artifacts, até 100 MB).

Use quando: O valor do item é um arquivo (diagrama, template, script). Retorna: Metadados do anexo (id, filename, file_size, mime_type). Exemplo: artifact_attach(item_id="...", file_path="C:/docs/arquitetura.png") Notas: Use só caminhos que o usuário indicou. A lista vem em item_get → artifacts.

Conteúdo de um anexo em base64.

Use quando: Precisar do arquivo em si (confira file_size em item_get antes). Retorna: {artifact, content_base64}. Exemplo: artifact_get(artifact_id="...")