Hub Pessoal MCP

Fase 1 do projeto: um app desktop (Electron + React + TypeScript) que guarda notas do dia a dia organizadas por temas e subtemas — ao estilo pastas — com links soltos entre notas ao estilo Obsidian, e um servidor MCP que expõe tudo isso pra qualquer assistente de IA compatível (Claude Desktop, por exemplo), tudo rodando 100% local, sem nuvem.

Como rodar o app desktop

npm install
npm run dev

Isso abre a janela do Electron com hot-reload ligado. Na primeira vez já vem um punhado de notas de exemplo linkadas entre si, pra você ver o app funcionando sem precisar digitar nada.

• Barra lateral esquerda: a árvore de temas. + Novo tema cria um tema de nível raiz (ex: "Pagamentos"); passa o mouse num tema e clica + pra criar um subtema dentro dele (ex: "Projetos" → "Hub Pessoal"). Duplo clique no nome renomeia; o × remove (com confirmação) — as notas de um tema removido não são apagadas, só voltam a ficar "sem tema". Arrasta um tema ou subtema pra reordenar a lista do teu jeito — a ordem fica salva. Só dá pra arrastar dentro do mesmo grupo (temas de raiz entre si, subtemas de um mesmo pai entre si), não pra virar filho de outro tema.

• Clica num tema (ou subtema) pra ver, no meio, tudo que está relacionado a ele. Clicar num tema raiz agrega as notas dos subtemas também. Sem nada selecionado, o meio mostra a visão geral com um cartão por tema e a contagem de notas.

• Na barra de captura (embaixo, centro), escreve algo e aperta Enter — a nota nova entra automaticamente no tema selecionado. Use [[Nome de outra nota]] no meio do texto pra criar um link — se a nota ainda não existir, ela é criada automaticamente (igual ao Obsidian).

• No painel de detalhe (direita), dá pra trocar o tema de uma nota a qualquer momento pelo seletor abaixo do título. O conteúdo mostra os trechos que viraram link como texto clicável (clica em qualquer outro lugar do conteúdo pra editar); "Linka para" e "Linkado por" listam as notas conectadas, com um × pra desvincular sem apagar nada. [[Nome]] funciona tanto na barra de captura quanto editando o conteúdo de uma nota já existente — nos dois casos cria a nota referenciada se ela ainda não existir. O + ao lado de "Linka para" abre um dropdown com busca pra linkar uma nota já existente sem precisar digitar [[Nome]] no texto. URLs http(s):// soltas no conteúdo também viram link clicável, abrindo no navegador padrão do sistema (nunca dentro da janela do app).

• Botão Selecionar no topo da grade de notas liga um modo de seleção múltipla — marca várias notas e usa o seletor "Mover para…" que aparece pra trocar o tema de todas de uma vez.

• Atalhos: Ctrl+K foca a busca, Ctrl+N foca a barra de captura, Esc fecha o painel de detalhe.

Related MCP server: mor

Como rodar o servidor MCP

npm run mcp:server

Ele lê e escreve o mesmo arquivo que o app desktop usa (data/notas.json), então o que você adiciona por um lado aparece no outro. Pra conectar no Claude Desktop, adiciona isto no claude_desktop_config.json:

{
  "mcpServers": {
    "hub-pessoal": {
      "command": "npx",
      "args": ["tsx", "/caminho/completo/para/hub-pessoal-mcp/mcp-server/index.ts"]
    }
  }
}

Ferramentas expostas:

Temas

• listar_temas — devolve a árvore de temas/subtemas com a contagem de notas de cada um (tema raiz já vem com o total agregado dos subtemas). Chama essa primeiro: é como a IA descobre a organização do usuário e o caminho exato (ex: "Projetos/Hub Pessoal") pra usar nas outras ferramentas.

• criar_tema — cria um tema ou subtema sem precisar criar nota junto; idempotente (não duplica se já existir um com o mesmo nome no mesmo nível).

• renomear_tema — renomeia um tema/subtema existente, pelo caminho.

• remover_tema — remove um tema/subtema pelo caminho; as notas que estavam nele não são apagadas, só voltam a ficar sem tema. Chama sem confirmar primeiro pra ver o impacto (subtemas e quantas notas seriam afetadas); só remove de fato com confirmar: true.

Notas

• buscar_contexto — busca por texto livre no título/conteúdo, sem se importar com acento (título pesa mais no ranking); aceita tema opcional pra restringir a busca a um assunto e limite pra cortar o tamanho da resposta.

• listar_notas — lista notas, as mais recentes primeiro; sem tema lista tudo (use limite pra não estourar o contexto), com tema filtra só aquele assunto (um tema raiz traz também as notas dos subtemas).

• notas_relacionadas — dado o ID de uma nota, mostra pra quais notas ela linka e quais linkam pra ela (os dois lados do [[Nome]]), pra puxar o fio de um assunto.

• adicionar_nota — cria uma nota; o tema aceita o mesmo formato de caminho, mas aqui ele cria o tema/subtema automaticamente se ainda não existir.

• atualizar_nota — corrige/expande uma nota existente (título, conteúdo, tema ou links) sem precisar apagar e recriar; só os campos passados são alterados, e tema: "" tira a nota do tema atual.

• remover_nota — remove uma nota pelo ID. Chama sem confirmar primeiro pra ver uma prévia sem apagar nada; só remove de fato com confirmar: true.

• buscar_semantico — busca por similaridade de vocabulário (TF-IDF + cosseno, calculado localmente, sem IA/nuvem), pra achar notas do mesmo assunto mesmo sem a frase exata em comum. Complementa buscar_contexto.

• historico_nota — reconstrói como uma nota mudou ao longo do tempo, a partir dos backups automáticos em data/backups/ (até 5 versões).

• contexto_projeto — empacota as notas de um tema/projeto (+ as ligadas por [[Nome]] que ficam fora dele) num bloco de texto único, pronto pra colar como contexto em outra sessão/agente.

• listar_pendencias — varre o conteúdo procurando - [ ] algo ou TODO: algo e devolve os itens em aberto com a nota de origem; aceita tema pra restringir (ex: "agenda").

• sugerir_organizacao — aponta notas sem tema, temas quase vazios e pares de temas com nome parecido (possível duplicata por digitação).

Um caminho de tema que não existe (nas ferramentas que só leem, não criam) retorna um aviso pedindo pra chamar listar_temas primeiro, em vez de inventar resultado.

Estrutura do projeto

hub-pessoal-mcp/
  src/
    main/        → processo principal do Electron (janela + IPC)
    preload/      → ponte segura entre o main e a interface
    renderer/     → a interface (React): árvore de temas, grade de notas, etc.
    shared/       → tipos e a camada de armazenamento, usados por todo mundo
  mcp-server/      → servidor MCP standalone (roda separado do app)
  data/notas.json  → onde tudo fica salvo (JSON simples, fácil de inspecionar)
  data/backups/    → cópias automáticas antes de cada escrita (as 5 mais recentes)

Decisões da Fase 1 (e o que fica pra depois)

• Armazenamento em JSON, não SQLite ainda — dá pra ler com o olho e não exige compilar dependência nativa. Fase 2 troca por SQLite + sqlite-vec sem mudar a API de src/shared/armazenamento.ts.

• Sem OCR nem captura de recibos ainda — isso é a Fase 2.

• Sem app mobile ainda — isso é a Fase 3, com sync via rede local.

• UI: tema neumórfico escuro com roxo #7c6cf0, notas organizadas por temas/subtemas hierárquicos (2 níveis, reordenáveis por drag-and-drop) em vez de tags soltas.

• Backup automático: cada escrita em data/notas.json primeiro copia o estado atual pra data/backups/, mantendo as últimas 5 versões — recupera de uma migração com bug ou uma remoção em cascata que deu errado.

• Busca sem acento: tanto a busca da interface quanto buscar_contexto ignoram acentuação ("financas" acha "Finanças").

Scripts

Licença

MIT.