🧠 MCP-сервер Project Synapse

Автономный движок синтеза знаний с интеграцией LLM-WIKI

Project Synapse — это сервер MCP (Model Context Protocol), который объединяет графовую базу данных Neo4j 2026.x с вики-системой Obsidian Markdown для создания постоянной, накапливаемой базы знаний. Необработанный текст проходит через семантический конвейер, превращаясь в взаимосвязанные узлы графа с векторными эмбеддингами, в то время как слой вики, читаемый человеком, предоставляет удобные для просмотра, перелинкованные страницы Markdown.

📚 Документация

Для получения подробной информации о настройке и использовании Project Synapse, пожалуйста, обратитесь к следующим руководствам:

• Начало работы: Установка и первый запуск.

• Архитектура: Как работают семантический конвейер и граф.

• Конфигурация: Полный список переменных окружения.

• Разработка: Руководство по добавлению инструментов и внесению вклада.

• Тестирование: Запуск набора тестов.

• Вклад в проект: Руководство по участию в проекте.

Related MCP server: KG Memory

Что это такое (и чем не является)

Это система знаний, а не редактор кода. Она предназначена для мышления, исследований и написания текстов, сопровождающих проекты — архитектурных решений, исследований предметной области, обоснования дизайна, справочных материалов, заметок со встреч.

Код живет в своем репозитории. Знания о коде живут здесь.

Варианты использования:

• Глубокие исследования, накапливаемые неделями/месяцами

• Базы знаний проектов (почему были приняты решения, а не только что именно)

• Управление личными знаниями (статьи, книги, заметки из подкастов)

• Совместный мозговой штурм с ИИ в качестве администратора вики

Настройка для каждого проекта: Создайте отдельное хранилище (vault) Obsidian + репозиторий GitHub для каждого проекта. Укажите на него переменную окружения WIKI_VAULT_PATH. Один экземпляр Neo4j может обслуживать несколько проектов (графы сосуществуют).

Архитектура

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

Ключевые особенности

Граф знаний (Neo4j 2026.x)

• Нативный тип VECTOR с семантическим поиском ANN

• Полнотекстовые индексы BM25 для поиска по ключевым словам

• Гибридный поиск (объединение оценок вектора + BM25)

• Обход графа для обнаружения скрытых связей

• Парсер грамматики Монтегю для формального семантического анализа

• Движок Zettelkasten для автономной генерации инсайтов

Интеграция LLM-WIKI

• Связывает хранилище Obsidian Markdown с графом Neo4j

• Полный CRUD страниц с YAML frontmatter

• Автоматическая генерация индекса и лог только для добавления

• Проверки работоспособности: обнаружение «сирот», битых вики-ссылок, отсутствующего frontmatter

• Манифест дельта-синхронизации (хеширование контента) для эффективной синхронизации графа

• Основано на шаблоне LLM Wiki Андрея Карпатого

Сбор веб-контента (defuddle)

• wiki_fetch_url извлекает любой URL, удаляет навигацию/рекламу/мусор через defuddle, загружает в Neo4j и архивирует в Clippings/ — один вызов, полная автоматизация

• wiki_ingest_raw автоматически перемещает обработанные файлы из raw/ в Clippings/ — папка «входящие» остается чистой

• raw/ — это настоящая папка «входящие»: пуста после каждого сеанса

Локальные эмбеддинги (без платных API)

• sentence-transformers (по умолчанию) — работает на GPU

• Ollama (опционально) — любая локальная модель эмбеддингов

• Все векторы хранятся нативно в Neo4j через db.create.setNodeVectorProperty()

Быстрый старт

Предварительные требования

• Python 3.12+

• Neo4j 2026.x (Community или Enterprise)

• Менеджер пакетов uv (pip install uv)

• Obsidian с сообщественным плагином Git

• Репозиторий GitHub для хранилища вики (может быть приватным)

• Node.js + defuddle (для получения веб-контента — см. ниже)

Настройка 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

Настройка defuddle

defuddle извлекает чистый markdown из веб-страниц, удаляя навигацию, рекламу и шаблонный код перед загрузкой. Требуется для 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

Примечание: Synapse находит defuddle автоматически через пути nvm, даже если он не находится в PATH вашей оболочки. Если wiki_fetch_url сообщает, что defuddle не найден, убедитесь, что он установлен в версии Node, управляемой nvm.

Настройка хранилища Obsidian

1. Создайте новое хранилище в Obsidian (или клонируйте свой репозиторий вики)

2. Установите общественный плагин Git (Настройки → Общественные плагины → Обзор → "Git")

3. Настройте плагин Git с вашими учетными данными GitHub

4. Структура хранилища (raw/, wiki/, Clippings/, AGENTS.md) создается автоматически Synapse при первом запуске

Установка

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

Конфигурация

Отредактируйте .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

Интеграция с Claude Desktop / MCP

Добавьте в свою конфигурацию 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"
      }
    }
  }
}

Инструменты MCP

Граф знаний

Вики (LLM-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

Жизненный цикл контента

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/ всегда пуст после сеанса. Clippings/ — это постоянная запись всего, что было обработано. Исходные страницы в wiki/sources/ ссылаются на исходный URL, а не на путь к файлу.

Рабочий процесс

1. Веб-исследование: wiki_fetch_url(url) → получает, очищает, загружает, архивирует за один вызов

2. Ручная вырезка: Поместите в raw/, вызовите wiki_ingest_raw(filename) → автоархивация после загрузки

3. Запрос: query_knowledge (граф) или wiki_search (файлы) → синтез ответа

4. Линтинг: wiki_lint → исправление сирот, битых ссылок, устаревших утверждений

5. Откат: Git обрабатывает контроль версий через плагин Obsidian Git

Теоретическая основа

• Грамматика Монтегю: Формальная композиционная семантика для извлечения смысла

• Метод Zettelkasten: Атомарные связанные заметки с эмерджентной структурой

• Теория графов: Обнаружение сообществ, центральность, анализ путей

• Karpathy LLM-WIKI: Постоянная компиляция знаний против RAG без сохранения состояния

• Memex Ванневара Буша: Личные ассоциативные знания с поддерживаемыми путями

Лицензия

MIT — см. LICENSE.

Project Synapse: От реактивного RAG к постоянным, накапливаемым знаниям.