Project Synapse MCP Server

Transforma texto sin procesar en grafos de conocimiento interconectados y genera información utilizando una base de datos Neo4j.

GitHub

Documentación

🧠 Project Synapse MCP Server

Motor autónomo de síntesis de conocimiento con integración LLM-WIKI

Project Synapse es un servidor MCP (Model Context Protocol) que combina una base de datos de grafos Neo4j 2026.x con un wiki de Markdown de Obsidian para crear una base de conocimiento persistente y acumulativa. El texto bruto se procesa a través de un pipeline semántico hasta convertirse en nodos de grafo interconectados con embeddings vectoriales, mientras que una capa de wiki legible por humanos proporciona páginas Markdown interconectadas y navegables.

📚 Documentación

Para obtener información detallada sobre la configuración y el uso de Project Synapse, consulte las siguientes guías:

Primeros pasos: Instalación y primera ejecución.
Arquitectura: Cómo funcionan el pipeline semántico y el grafo.
Configuración: Lista completa de variables de entorno.
Desarrollo: Guía para añadir herramientas y contribuir.
Pruebas: Ejecución del conjunto de pruebas.
Contribución: Directrices para contribuir al proyecto.

Qué es esto (y qué no es)

Esto es un sistema de conocimiento, no un editor de código. Está pensado para el pensamiento, la investigación y la escritura que rodean a los proyectos: decisiones de arquitectura, investigación de dominio, fundamentación de diseño, material de referencia, notas de reuniones.

El código vive en su repositorio. El conocimiento sobre el código vive aquí.

Casos de uso:

Inmersiones profundas de investigación que se acumulan durante semanas/meses
Bases de conocimiento de proyectos (por qué se tomaron las decisiones, no solo qué)
Gestión personal del conocimiento (artículos, libros, notas de podcasts)
Lluvia de ideas colaborativa con la IA como mantenedora del wiki

Configuración por proyecto: Cree una bóveda de Obsidian separada + repositorio de GitHub para cada proyecto. Apunte la variable de entorno WIKI_VAULT_PATH a ella. Una única instancia de Neo4j puede servir a varios proyectos (los grafos coexisten).

Arquitectura

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)  │
                              └───────────────┘

Características principales

Grafo de conocimiento (Neo4j 2026.x)

Tipo VECTOR nativo con búsqueda semántica ANN
Índices fulltext BM25 para búsqueda por palabras clave
Búsqueda híbrida (fusión de puntuaciones vectorial + BM25)
Recorrido de grafo para descubrir relaciones ocultas
Analizador de gramática de Montague para análisis semántico formal
Pipeline de extracción híbrido: Combina la extracción basada en LLM (Gemma 2 9b vía Ollama) con NER de spaCy para el descubrimiento de entidades y relaciones de alta precisión
Motor Zettelkasten para la generación autónoma de ideas

Integración LLM-WIKI

Conecta la bóveda Markdown de Obsidian con el grafo de Neo4j
CRUD completo de páginas con frontmatter YAML
Generación automática de índices y registro de solo anexión
Comprobaciones de salud: detección de huérfanos, wikilinks rotos, frontmatter faltante
Manifiesto de sincronización delta (hash de contenido) para una sincronización eficiente del grafo
Basado en el patrón LLM Wiki de Andrej Karpathy

Ingestión de contenido web (defuddle)

wiki_fetch_url obtiene cualquier URL, elimina navegación/anuncios/ruido mediante defuddle, ingiere en Neo4j y archiva en Clippings/ — una sola llamada, totalmente automatizada
wiki_ingest_raw mueve automáticamente los archivos procesados de raw/ a Clippings/ — la bandeja de entrada se mantiene limpia
raw/ es una verdadera bandeja de entrada: vacía después de cada sesión

Embeddings solo locales (sin APIs de pago)

sentence-transformers (predeterminado) — se ejecuta en GPU
Ollama (opcional) — cualquier modelo de embeddings local
Todos los vectores se almacenan de forma nativa en Neo4j mediante db.create.setNodeVectorProperty()

Inicio rápido

Requisitos previos

Python 3.12+
Neo4j 2026.x (Community o Enterprise)
Gestor de paquetes uv (pip install uv)
Obsidian con el plugin de comunidad Git
Un repositorio de GitHub para la bóveda del wiki (puede ser privado)
Node.js + defuddle (para la obtención de contenido web — ver más abajo)

Configuración de 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

Configuración de defuddle

defuddle extrae markdown limpio de páginas web, eliminando navegación, anuncios y texto repetitivo antes de la ingestión. Requerido 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: Synapse encuentra defuddle automáticamente a través de las rutas de nvm incluso si no está en el PATH de su shell. Si wiki_fetch_url informa que defuddle no se encuentra, asegúrese de que esté instalado en una versión de Node gestionada por nvm.

Configuración de la bóveda de Obsidian

Cree una nueva bóveda en Obsidian (o clone su repositorio del wiki)
Instale el plugin de comunidad Git (Configuración → Plugins de comunidad → Explorar → "Git")
Configure el plugin Git con sus credenciales de GitHub
La estructura de la bóveda (raw/, wiki/, Clippings/, AGENTS.md) se crea automáticamente por Synapse en la primera ejecución

Instalación

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

Configuración

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

Integración con Claude Desktop / MCP

Añada a su configuración de MCP:

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

Herramientas MCP

Grafo de conocimiento

Herramienta	Descripción
`ingest_text`	Procesa texto a través del pipeline semántico → Neo4j
`query_knowledge`	Búsqueda semántica vectorial con resultados priorizando ideas
`explore_connections`	Recorrido de grafo para relaciones ocultas
`generate_insights`	Detección autónoma de patrones Zettelkasten
`analyze_semantic_structure`	Análisis semántico con gramática de Montague

Wiki (LLM-WIKI)

Herramienta	Descripción
`wiki_fetch_url`	Obtener URL → limpiar con defuddle → ingerir → archivar en Clippings/
`wiki_ingest_raw`	Ingerir archivo de raw/ → Neo4j + mover automáticamente a Clippings/
`wiki_write_page`	Crear/actualizar página del wiki con frontmatter (actualiza el índice en escritura)
`wiki_read_page`	Leer una página del wiki por ruta con soporte para `mode` (meta, extracto, completo)
`wiki_search`	Búsqueda por palabras clave en las páginas del wiki que devuelve extractos y fragmentos
`wiki_list_pages`	Listar páginas en un subdirectorio con filtros paginados `limit`, `offset` y `tag`
`wiki_update_index`	Reconstruir el índice del wiki (`index.md`)
`wiki_sync_index`	Sincronizar/actualizar manualmente la base de datos de índice de páginas DuckDB desde el disco
`wiki_lint`	Comprobación de salud: huérfanos, enlaces rotos, frontmatter faltante/no válido (se ejecuta vía SQL)

Estructura de la bóveda del 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 del contenido

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/ siempre está vacía después de una sesión. Clippings/ es el registro permanente de todo lo que se ha procesado. Las páginas de origen en wiki/sources/ referencian la URL original, no la ruta del archivo.

Flujo de trabajo

Investigación web: wiki_fetch_url(url) → obtiene, limpia, ingiere y archiva en una sola llamada
Recorte manual: Coloque en raw/, llame a wiki_ingest_raw(filename) → se archiva automáticamente tras la ingestión
Consulta: query_knowledge (grafo) o wiki_search (archivos) → sintetizar respuesta
Lint: wiki_lint → corregir huérfanos, enlaces rotos, afirmaciones obsoletas
Reversión: Git gestiona el control de versiones mediante el plugin Obsidian Git

Fundamento teórico

Gramática de Montague: Semántica composicional formal para la extracción de significado
Método Zettelkasten: Notas atómicas enlazadas con estructura emergente
Teoría de grafos: Detección de comunidades, centralidad, análisis de caminos
Karpathy LLM-WIKI: Compilación persistente de conocimiento frente a RAG sin estado
Memex de Vannevar Bush: Conocimiento asociativo privado con senderos mantenidos

Licencia

MIT — ver LICENCIA.

Project Synapse: De RAG reactivo a conocimiento persistente y acumulativo.