🧠 Servidor MCP Project Synapse

Motor de síntesis de conocimiento autónomo 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 una wiki de Obsidian Markdown para crear una base de conocimiento persistente y acumulativa. El texto sin procesar se transforma a través de un pipeline semántico en nodos de grafo interconectados con incrustaciones vectoriales (embeddings), mientras que una capa de wiki legible por humanos proporciona páginas Markdown interconectadas y navegables.

📚 Documentación

Para obtener información detallada sobre cómo configurar y utilizar 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 de la suite de pruebas.

• Contribución: Directrices de contribución al proyecto.

Related MCP server: KG Memory

Qué es (y qué no es) esto

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, justificació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:

• Investigaciones profundas que se acumulan durante semanas/meses

• Bases de conocimiento de proyectos (por qué se tomaron las decisiones, no solo cuáles fueron)

• Gestión de conocimiento personal (artículos, libros, notas de podcasts)

• Lluvia de ideas colaborativa con la IA como mantenedora de la wiki

Configuración por proyecto: Cree un vault de Obsidian + repositorio de GitHub independiente para cada proyecto. Apunte la variable de entorno WIKI_VAULT_PATH hacia él. Una instancia de Neo4j puede servir a múltiples 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 clave

Grafo de conocimiento (Neo4j 2026.x)

• Tipo VECTOR nativo con búsqueda semántica ANN

• Índices BM25 de texto completo para búsqueda por palabras clave

• Búsqueda híbrida (fusión de puntuación vectorial + BM25)

• Recorrido de grafos para descubrir relaciones ocultas

• Analizador de gramática de Montague para análisis semántico formal

• Motor Zettelkasten para la generación autónoma de ideas

Integración LLM-WIKI

• Conecta el vault de Obsidian Markdown con el grafo de Neo4j

• CRUD completo de páginas con frontmatter YAML

• Generación automática de índices y registro de solo adición (append-only)

• Comprobaciones de salud: detección de huérfanos, enlaces wiki rotos, frontmatter faltante

• Manifiesto de sincronización delta (hashing de contenido) para una sincronización eficiente del grafo

• Basado en el patrón LLM Wiki de Andrej Karpathy

Ingesta de contenido web (defuddle)

• wiki_fetch_url obtiene cualquier URL, elimina la navegación/anuncios/desorden mediante defuddle, lo ingesta en Neo4j y lo 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

Incrustaciones (embeddings) solo locales (sin APIs de pago)

• sentence-transformers (predeterminado): se ejecuta en GPU

• Ollama (opcional): cualquier modelo de incrustación 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 comunitario Git

• Un repositorio de GitHub para el vault de la 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 la navegación, anuncios y texto repetitivo antes de la ingesta. 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 no se encuentra defuddle, asegúrese de que esté instalado en una versión de Node gestionada por nvm.

Configuración del vault de Obsidian

1. Cree un nuevo vault en Obsidian (o clone su repositorio de wiki)

2. Instale el plugin comunitario Git (Configuración → Plugins comunitarios → Explorar → "Git")

3. Configure el plugin Git con sus credenciales de GitHub

4. La estructura del vault (raw/, wiki/, Clippings/, AGENTS.md) es creada automáticamente por Synapse en la primera ejecución

Instalación

cd /home/ty/Repositories/ai_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

# 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"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "WIKI_VAULT_PATH": "/path/to/obsidian-vault",
        "WIKI_GITHUB_REPO": "https://github.com/user/wiki-repo"
      }
    }
  }
}

Herramientas MCP

Grafo de conocimiento

Wiki (LLM-WIKI)

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

Flujo de trabajo

1. Investigación web: wiki_fetch_url(url) → obtiene, limpia, ingesta y archiva en una sola llamada

2. Recorte manual: Coloque en raw/, llame a wiki_ingest_raw(filename) → auto-archiva después de la ingesta

3. Consulta: query_knowledge (grafo) o wiki_search (archivos) → sintetizar respuesta

4. Lint: wiki_lint → corregir huérfanos, enlaces rotos, afirmaciones obsoletas

5. Reversión: Git maneja el control de versiones a través del plugin Obsidian Git

Fundamentos teóricos

• Gramática de Montague: Semántica composicional formal para la extracción de significado

• Método Zettelkasten: Notas vinculadas atómicas con estructura emergente

• Teoría de grafos: Detección de comunidades, centralidad, análisis de rutas

• LLM-WIKI de Karpathy: Compilación de conocimiento persistente frente a RAG sin estado

• Memex de Vannevar Bush: Conocimiento asociativo privado con rutas mantenidas

Licencia

MIT — ver LICENSE.

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