filamental-mcp

filamental-mcp

Um servidor local Model Context Protocol que conecta assistentes de IA (Claude Desktop, Claude Code, etc.) diretamente ao seu grafo de conhecimento Filamental.

O servidor lê e grava em seu vault — pesquisando nós, seguindo conexões, criando e atualizando conteúdo — enquanto o Filamental está em execução ou fechado. Ele fala com o mesmo índice SQLite que o aplicativo usa, então as alterações ficam imediatamente visíveis quando você abre o Filamental.

Requer Node.js 22+ e o aplicativo de desktop Filamental.

---

Pré-requisitos

• Filamental instalado e pelo menos um vault aberto (isso inicializa o índice SQLite)
• Node.js 22 ou posterior

---

Configuração via Filamental

A maneira mais fácil de conectar é pelo aplicativo:

1. Abra o Filamental e vá para Configurações > Integrações de IA
2. Clique em Conectar ao Claude Desktop
3. Reinicie o Claude Desktop

O Filamental resolve todos os caminhos automaticamente. O MCP segue o vault que estiver aberto — sem necessidade de reiniciar ao alternar entre mundos.

---

Configuração manual

Instale globalmente:

npm install -g filamental-mcp

Depois adicione ao seu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filamental": {
      "command": "node",
      "args": [
        "--no-warnings",
        "/absolute/path/to/node_modules/filamental-mcp/dist/index.js"
      ]
    }
  }
}

Nenhum argumento --vault é necessário. O servidor lê o vault ativo do Filamental automaticamente e reconecta quando você alterna de mundos. Para fixar um vault específico (por exemplo, para testes), passe --vault <absolute-path> explicitamente.

Claude Code

Adicione um .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "filamental": {
      "command": "npx",
      "args": [
        "filamental-mcp",
        "--vault",
        "/absolute/path/to/your/vault"
      ]
    }
  }
}

---

Ferramentas

Leitura

Ferramenta	Descrição
get_vault_info	Contagem de nós e arestas, além dos nomes de tipos de entidades e conectores
list_node_types	Configuração completa dos tipos de entidade deste vault
list_connector_types	Configuração completa dos tipos de conector deste vault
search_nodes	Pesquisa de texto completo em nomes de nós, corpos de notas e valores de propriedades
get_node	Registro completo do nó por UUID
get_connections	Todas as arestas conectadas a um nó, relatadas do ponto de vista desse nó (veja Direção da seta)
get_subgraph	Travessia BFS a partir de um nó raiz até N saltos (profundidade máxima 3)

Escrita

Ferramenta	Descrição
create_node	Criar um novo nó — grava um arquivo Markdown e atualiza o índice SQLite
update_node	Atualizar um nó existente; campos omitidos permanecem inalterados
delete_node	Excluir um nó e removê-lo do índice
create_edge	Adicionar um relacionamento entre dois nós
delete_edge	Remover um relacionamento entre dois nós

---

Direção da seta

O direction de um conector é um de none, outgoing, incoming ou bidirectional. Nada mais é aceito, e um valor não reconhecido é rejeitado em vez de armazenado.

Em gravações (create_edge, create_node, update_node), a direção é declarada em relação a source → target: outgoing desenha a ponta da seta no destino, incoming desenha de volta na origem, bidirectional desenha em ambos, none é uma linha simples.

Em leituras (get_connections), a direção é declarada em relação ao nó sobre o qual você perguntou, porque é isso que o usuário vê na tela:

Campo	Significado
node	O nó sobre o qual você perguntou
other	O nó na outra extremidade
direction	Onde a ponta da seta é desenhada, visto de node
stored_on	Qual arquivo do nó contém o relacionamento

Essa distinção importa. Qual extremidade de um conector é armazenada como source é decidido por qual extremidade o usuário arrastou ao desenhá-lo, e isso é invisível no grafo — um conector não direcionado parece idêntico em qualquer orientação. Portanto, a mesma seta é lida como outgoing de uma extremidade e incoming da outra, e get_connections inverte isso para você. Filtrar com direction: "outgoing" fornece arestas cuja seta aponta para longe de o nó sobre o qual você perguntou, nunca arestas que apenas por acaso estão armazenadas com ele como source. Uma aresta bidirectional corresponde aos filtros outgoing e incoming, já que ela genuinamente aponta em ambas as direções; undirected corresponde apenas a arestas sem seta alguma.

Use stored_on somente se você estiver editando o arquivo Markdown subjacente diretamente. Ele não diz nada sobre o que a seta faz.

---

Opções de CLI

filamental-mcp --vault <path>          Use vault at <path>
filamental-mcp --vault <path> --db <path>   Override the SQLite database path (for testing)

---

Como funciona

O Filamental armazena todos os dados de nós como arquivos Markdown com frontmatter YAML dentro da pasta do seu vault. Ele também mantém um índice SQLite (armazenado no diretório de configuração do aplicativo do seu sistema operacional, não dentro do vault) para pesquisa de texto completo e travessia de grafo rápidas.

Este servidor abre esse índice SQLite em modo leitura-escrita. As ferramentas de leitura consultam diretamente. As ferramentas de escrita atualizam tanto o arquivo Markdown no disco quanto o índice SQLite, para que o aplicativo Filamental veja as alterações imediatamente no próximo carregamento.

---

Compatibilidade

filamental-mcp	Aplicativo Filamental	Esquema do banco
0.2.6+	0.3.0 e posteriores (atual)	v6
0.2.0 – 0.2.5	0.2.x	v5

O servidor continua funcionando mesmo com incompatibilidade de esquema (o banco é um índice descartável, então a maioria das operações de leitura/escrita tolera divergências). Se uma chamada de ferramenta falhar por um motivo não relacionado enquanto as versões estiverem incompatíveis, a mensagem de erro é anotada com qual lado deve ser atualizado.

---

Limitações conhecidas

• O binário pré-compilado (better-sqlite3) é apenas para Windows x64. Outras plataformas exigem compilação a partir do código-fonte.
• A configuração automática via Configurações do Filamental foi testada no Windows. A resolução de caminhos no macOS está incluída, mas não testada.

---

Licença

MIT — Copyright Filamental