Project Synapse MCP Server

Transforma texto bruto em grafos de conhecimento interconectados e gera insights usando um banco de dados Neo4j.

Documentação

🧠 Project Synapse MCP Server

Mecanismo Autônomo de Síntese de Conhecimento com Integração LLM-WIKI

O Project Synapse é um servidor MCP (Model Context Protocol) que combina um banco de dados de grafo Neo4j 2026.x com um wiki Markdown do Obsidian para criar uma base de conhecimento persistente e em constante crescimento. Texto bruto é processado por meio de um pipeline semântico em nós de grafo interconectados com embeddings vetoriais, enquanto uma camada de wiki legível por humanos fornece páginas Markdown navegáveis e interligadas.

📚 Documentação

Para informações detalhadas sobre como configurar e usar o Project Synapse, consulte os seguintes guias:

Começando: Instalação e primeira execução.
Arquitetura: Como o pipeline semântico e o grafo funcionam.
Configuração: Lista completa de variáveis de ambiente.
Desenvolvimento: Guia para adicionar ferramentas e contribuir.
Testes: Executando a suíte de testes.
Contribuindo: Diretrizes de contribuição do projeto.

O Que Isto É (e Não É)

Isto é um sistema de conhecimento, não um editor de código. É para o pensamento, pesquisa e escrita que cercam projetos — decisões de arquitetura, pesquisa de domínio, justificativa de design, material de referência, notas de reunião.

O código vive no repositório. O conhecimento sobre o código vive aqui.

Casos de uso:

Mergulhos profundos em pesquisa que se acumulam ao longo de semanas/meses
Bases de conhecimento de projetos (por que decisões foram tomadas, não apenas o quê)
Gestão de conhecimento pessoal (artigos, livros, notas de podcasts)
Brainstorming colaborativo com IA como mantenedora do wiki

Configuração por projeto: Crie um cofre Obsidian separado + repositório GitHub para cada projeto. Aponte a variável de ambiente WIKI_VAULT_PATH para ele. Uma única instância do Neo4j pode atender vários projetos (os grafos coexistem).

Arquitetura

Web / Raw Sources
         │
    [defuddle]          ← cleans web content before ingestion
         │
         ▼
┌──────────────────────┐     ┌─────────────────────┐
│  Semantic Pipeline   │────▶│  Neo4j Knowledge    │
│  (Montague Grammar,  │     │  Graph (entities,   │
│   NLP, embeddings)   │     │  facts, vectors)    │
└──────────────────────┘     └────────┬────────────┘
                                      │
                              ┌───────┴───────┐
                              │ Wiki Adapter  │
                              └───────┬───────┘
                                      │
                              ┌───────▼───────┐
                              │ Obsidian Vault│
                              │ (Markdown,    │
                              │  Git-synced)  │
                              └───────────────┘

Principais Recursos

Grafo de Conhecimento (Neo4j 2026.x)

Tipo nativo VECTOR com busca semântica ANN
Índices fulltext BM25 para busca por palavras-chave
Busca híbrida (fusão de pontuação vetorial + BM25)
Travessia de grafo para descobrir relacionamentos ocultos
Parser de Gramática de Montague para análise semântica formal
Pipeline de Extração Híbrida: Mescla extração baseada em LLM (Gemma 2 9b via Ollama) com NER do spaCy para descoberta de entidades e relacionamentos de alta precisão
Mecanismo Zettelkasten para geração autônoma de insights

Integração LLM-WIKI

Conecta o cofre Markdown do Obsidian ao grafo Neo4j
CRUD completo de páginas com frontmatter YAML
Geração automática de índice e log somente de acréscimo
Verificações de saúde: detecção de órfãos, wikilinks quebrados, frontmatter ausente
Manifesto de sincronização delta (hash de conteúdo) para sincronização eficiente do grafo
Baseado no padrão LLM Wiki de Andrej Karpathy

Ingestão de Conteúdo Web (defuddle)

wiki_fetch_url busca qualquer URL, remove navegação/anúncios/poluição via defuddle, ingere no Neo4j e arquiva em Clippings/ — uma chamada, totalmente automatizada
wiki_ingest_raw move automaticamente arquivos processados de raw/ para Clippings/ — a caixa de entrada permanece limpa
raw/ é uma verdadeira caixa de entrada: vazia após cada sessão

Embeddings Somente Locais (Sem APIs Pagas)

sentence-transformers (padrão) — executa na GPU
Ollama (opcional) — qualquer modelo de embedding local
Todos os vetores armazenados nativamente no Neo4j via db.create.setNodeVectorProperty()

Início Rápido

Pré-requisitos

Python 3.12+
Neo4j 2026.x (Community ou Enterprise)
Gerenciador de pacotes uv (pip install uv)
Obsidian com o plugin comunitário Git
Um repositório GitHub para o cofre do wiki (pode ser privado)
Node.js + defuddle (para busca de conteúdo web — veja abaixo)

Configuração do Neo4j

# Ubuntu/Debian — see neo4j.com for other platforms
sudo apt install neo4j
sudo systemctl start neo4j
sudo systemctl enable neo4j
# Set password (default user: neo4j)
sudo neo4j-admin set-initial-password your_password

Configuração do defuddle

O defuddle extrai Markdown limpo de páginas web, removendo navegação, anúncios e conteúdo repetitivo antes da ingestão. Necessário para wiki_fetch_url.

# Install Node.js if not present (via nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

# Install defuddle globally
npm install -g defuddle

# Verify
defuddle --version

Nota: O Synapse encontra o defuddle automaticamente via caminhos nvm, mesmo que ele não esteja no PATH do seu shell. Se wiki_fetch_url relatar que o defuddle não foi encontrado, garanta que ele esteja instalado em uma versão Node gerenciada pelo nvm.

Configuração do Cofre Obsidian

Crie um novo cofre no Obsidian (ou clone seu repositório do wiki)
Instale o plugin comunitário Git (Configurações → Plugins Comunitários → Navegar → "Git")
Configure o plugin Git com suas credenciais do GitHub
A estrutura do cofre (raw/, wiki/, Clippings/, AGENTS.md) é criada automaticamente pelo Synapse na primeira execução

Instalação

cd /path/to/your/workspace
git clone <repository-url> project-synapse-mcp
cd project-synapse-mcp
uv venv --python 3.12 --seed
source .venv/bin/activate
uv add -e .
uv run python -m spacy download en_core_web_sm
cp .env.example .env  # edit with your Neo4j password and vault path

Configuração

Edite .env:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j

# Embedding — local only, no paid APIs
EMBEDDING_PROVIDER=sentence-transformers  # or "ollama"
EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2
EMBEDDING_DIMENSION=768

# Extraction — Montague (default) or "llm" (hybrid)
EXTRACTION_PROVIDER=montague
OLLAMA_EXTRACTION_MODEL=gemma2:9b
OLLAMA_TIMEOUT=120

# Wiki vault
WIKI_VAULT_PATH=/path/to/your/obsidian-vault
WIKI_GITHUB_REPO=https://github.com/user/wiki-repo

Integração com Claude Desktop / MCP

Adicione à sua configuração MCP:

{
  "mcpServers": {
    "project-synapse": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/project-synapse-mcp",
        "run",
        "python",
        "-m",
        "synapse_mcp.server"
      ]
    }
  }
}

Ferramentas MCP

Grafo de Conhecimento

Ferramenta	Descrição
`ingest_text`	Processa texto pelo pipeline semântico → Neo4j
`query_knowledge`	Busca semântica vetorial com resultados priorizando insights
`explore_connections`	Travessia de grafo para relacionamentos ocultos
`generate_insights`	Detecção autônoma de padrões Zettelkasten
`analyze_semantic_structure`	Análise semântica com Gramática de Montague

Wiki (LLM-WIKI)

Ferramenta	Descrição
`wiki_fetch_url`	Busca URL → limpeza via defuddle → ingestão → arquivamento em Clippings/
`wiki_ingest_raw`	Ingestão de arquivo de raw/ → Neo4j + movimentação automática para Clippings/
`wiki_write_page`	Cria/atualiza página do wiki com frontmatter (atualiza índice write-through)
`wiki_read_page`	Lê uma página do wiki por caminho, suportando `mode` (meta, trecho, completo)
`wiki_search`	Busca por palavras-chave nas páginas do wiki retornando trechos e excertos
`wiki_list_pages`	Lista páginas em um subdiretório com filtros paginados `limit`, `offset` e `tag`
`wiki_update_index`	Reconstrói o índice do wiki (`index.md`)
`wiki_sync_index`	Sincroniza/atualiza manualmente o banco de índice de páginas DuckDB a partir do disco
`wiki_lint`	Verificação de saúde: órfãos, links quebrados, frontmatter ausente/inválido (executa via SQL)

Estrutura do Cofre do Wiki

LLM-WIKI/
├── AGENTS.md           # Agent schema doc — conventions and workflows
├── raw/                # INBOX ONLY — unprocessed files; empty after each session
├── raw-inbox.base      # Obsidian Base view of pending raw/ queue
├── Clippings/          # Permanent archive — all processed sources land here
├── wiki/
│   ├── index.md        # Auto-generated page catalogue
│   ├── log.md          # Append-only activity log
│   ├── entities/       # People, tools, projects
│   ├── concepts/       # Ideas, theories, patterns
│   └── sources/        # Summaries of ingested sources

Ciclo de Vida do Conteúdo

You clip/save → raw/          # your inbox
     or
Agent fetches → wiki_fetch_url # web research
                    │
              [defuddle clean]
                    │
              [semantic pipeline] → Neo4j
                    │
              wiki_write_page → wiki/sources/
                    │
              auto-move → Clippings/   # permanent archive

raw/ está sempre vazia após uma sessão. Clippings/ é o registro permanente de tudo que foi processado. Páginas de origem em wiki/sources/ referenciam a URL original, não o caminho do arquivo.

Fluxo de Trabalho

Pesquisa web: wiki_fetch_url(url) → busca, limpa, ingere, arquiva em uma chamada
Recorte manual: Solte em raw/, chame wiki_ingest_raw(filename) → arquiva automaticamente após a ingestão
Consulta: query_knowledge (grafo) ou wiki_search (arquivos) → sintetize a resposta
Lint: wiki_lint → corrija órfãos, links quebrados, afirmações desatualizadas
Rollback: O Git cuida do controle de versão via plugin Obsidian Git

Fundamentação Teórica

Gramática de Montague: Semântica composicional formal para extração de significado
Método Zettelkasten: Notas atômicas interligadas com estrutura emergente
Teoria dos Grafos: Detecção de comunidades, centralidade, análise de caminhos
Karpathy LLM-WIKI: Compilação persistente de conhecimento vs. RAG sem estado
Memex de Vannevar Bush: Conhecimento associativo privado com trilhas mantidas

Licença

MIT — veja LICENSE.

Project Synapse: De RAG reativo a conhecimento persistente e em constante crescimento.