vault-go

Servidor MCP em Bun para pesquisar, contextualizar e registrar memória na plataforma Vault. A persistência fica no PostgreSQL do serviço Rust executado no EasyPanel; este pacote não cria banco local.

Pré-requisito

Instale o Bun e confirme:

bun --version

Instalação MCP

Opção remota somente leitura

Para pesquisa e contexto, é possível usar diretamente o endpoint Streamable HTTP da plataforma, sem instalar runtime ou banco local. Crie em Segurança > Chaves de API uma chave apenas com memory:read e configure:

export VAULT_GO_TOKEN='<chave-memory-read>'
codex mcp add vault-go \
  --url https://vault.resolveup.com.br/api/mcp \
  --bearer-token-env-var VAULT_GO_TOKEN

Configuração genérica para clientes com transporte HTTP:

{
  "mcpServers": {
    "vault-go": {
      "type": "http",
      "url": "https://vault.resolveup.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VAULT_GO_TOKEN}"
      }
    }
  }
}

O endpoint remoto expõe somente projetos, busca, contexto, recentes, feed, linha do tempo, contexto de arquivos, estatísticas, estado vetorial e consultas às bases de conhecimento. Para captura automática, criação/reconstrução de bases, escrita, importação ou exclusão, use o cliente Bun completo abaixo.

Opção Bun completa

Execute em um terminal:

bunx --bun vault-go@latest

O assistente:

1. valida uma sessão existente em ~/.memvault;
2. se necessário, solicita login por e-mail, senha e MFA ou uma chave de API vg_live_...;
3. detecta os clientes instalados;
4. permite escolher onde registrar o MCP;
5. preserva as outras configurações dos clientes.

Clientes suportados:

• Codex e ChatGPT Desktop local;
• Claude Code e Claude Desktop;
• Cursor e Windsurf;
• VS Code com GitHub Copilot;
• GitHub Copilot CLI;
• Roo Code;
• OpenCode.

Comandos explícitos:

bunx --bun vault-go@latest setup
bunx --bun vault-go@latest setup --clients codex,claude,copilot
bunx --bun vault-go@latest login --force
bunx --bun vault-go@latest serve

As credenciais são gravadas em ~/.memvault/auth.json com permissão 0600; o diretório usa 0700. Senhas e códigos MFA não são persistidos. Reinicie os clientes que estavam abertos depois da primeira instalação.

Configuração MCP genérica:

{
  "mcpServers": {
    "vault-go": {
      "command": "bunx",
      "args": ["--bun", "vault-go@latest", "serve"]
    }
  }
}

Por padrão, todos os clientes reutilizam ~/.memvault/config.json e ~/.memvault/auth.json, criados pelo assistente. Também é possível apontar outro diretório:

{
  "mcpServers": {
    "vault-go": {
      "command": "bunx",
      "args": ["--bun", "vault-go@latest", "serve"],
      "env": {
        "VAULT_GO_HOME": "/caminho/privado/.memvault"
      }
    }
  }
}

Para ambientes efêmeros, VAULT_GO_TOKEN aceita um access token de sessão ou uma chave vg_live_... criada na tela Segurança > Chaves de API. Use somente os escopos necessários: memory:read para pesquisa/contexto, memory:write para eventos e lembranças e memory:delete para exclusão. VAULT_GO_API_URL troca o endpoint. O login normal permite renovação automática; a chave de API é indicada para automações com prazo e escopo limitados.

Ferramentas MCP

• vault_go_status: conexão e autenticação sem expor credenciais.
• vault_go_cloud_health: disponibilidade da plataforma.
• vault_go_projects e vault_go_project_create: projetos da conta.
• vault_go_session_start e vault_go_session_end: ciclo de sessão.
• vault_go_event: eventos de prompt, ferramenta e resultado.
• vault_go_remember: observações, decisões, descobertas e resumos.
• vault_go_search: busca textual com ranking e trechos.
• vault_go_search_index: índice compacto com filtros, trechos e custo estimado.
• vault_go_observations: carrega em lote somente os IDs selecionados.
• vault_go_timeline: contexto anterior e posterior a uma memória.
• vault_go_context: contexto progressivo com limite de caracteres.
• vault_go_file_context: histórico ligado aos arquivos lidos ou modificados.
• vault_go_stats: contagens isoladas da conta.
• vault_go_jobs: fila PostgreSQL da conta, sem payload sensível.
• vault_go_job_retry e vault_go_job_cancel: controle idempotente do processamento.
• vault_go_export e vault_go_import: transporte JSON tenant-scoped, atômico e idempotente.
• vault_go_embedding_status e vault_go_embedding_backfill: busca híbrida e fila vetorial, sem expor chaves.
• vault_go_feed: pagina memórias recentes por projeto, tipo e origem.
• vault_go_knowledge_bases e vault_go_knowledge_base: lista e abre bases focadas.
• vault_go_knowledge_build e vault_go_knowledge_rebuild: cria ou atualiza uma base a partir de filtros.
• vault_go_knowledge_query: recupera contexto fundamentado e citações dentro da base.
• vault_go_knowledge_delete: remove a base e preserva as memórias originais.
• vault_go_forget: exclusão explícita de uma memória.

O recurso vault-go://status fornece o resumo sanitizado em JSON.

Para reduzir o uso de contexto, prefira a recuperação em três camadas:

1. Pesquise com vault_go_search_index, usando projeto, origem, conceitos, arquivos e intervalo de datas quando conhecidos.
2. Abra vault_go_timeline somente para os resultados que precisam de contexto cronológico.
3. Envie os IDs escolhidos a vault_go_observations para carregar o conteúdo completo em um único lote tenant-scoped.

As bases, filtros, vínculos e feed ficam exclusivamente no PostgreSQL da plataforma. A consulta retorna evidências e synthesisAvailable: false; o cliente MCP faz a síntese, evitando respostas inventadas e chaves ocultas no servidor. A síntese do servidor só será habilitada quando um provedor semântico for configurado explicitamente.

Fluxo integrado

Cliente MCP -> vault-go (Bun) -> API autenticada (Bun)
                              -> engine interno (Rust)
                              -> PostgreSQL no EasyPanel

O engine não possui rota pública. A API valida o JWT do usuário, substitui-o por uma credencial interna e informa ao engine a conta autenticada. Todas as consultas aplicam esse identificador, impedindo leitura entre contas.

Segurança

• Não retorna access token nem refresh token em ferramentas ou recursos.
• Aceita HTTPS; HTTP somente em localhost.
• Renova o access token usando o refresh token local com permissão privada.
• Limita tamanhos, listas e janelas nos schemas das ferramentas.
• Reserva stdout exclusivamente para o protocolo MCP.
• Não persiste memória nem cria banco no dispositivo.

Instale o MCP apenas em clientes confiáveis: o cliente conectado pode pedir busca, gravação e exclusão de memórias dentro da conta autenticada.

Desenvolvimento

npm install
bun run typecheck
bun test src
bun run build
npm run pack:check

Publicação automática

Pushes em main passam por CI. Commits convencionais acionam release semântica, publicação no npm, tag e GitHub Release:

• fix: gera patch;
• feat: gera minor;
• feat!: ou BREAKING CHANGE: gera major.

O segredo NPM_TOKEN existe apenas no GitHub Actions e nunca deve ser salvo no repositório ou em logs.