🧠 MCP Memory Server

MCP сервер для управления долговременной памятью (Knowledge Graph) и поиска в интернете. Поддерживает SQLite (встроенное хранилище) и PostgreSQL (удалённая БД).

⚡ Используйте MCP инструменты прямо из VS Code: сохраняйте заметки, стройте граф знаний, ищите в интернете — всё без выхода из редактора.

✨ Возможности

🧠 Knowledge Graph (Граф знаний)

• Сохранение сущностей — люди, концепции, заметки, проекты, статьи

• Связи между сущностями — граф отношений (A --[related_to]--> B)

• Полнотекстовый поиск — по имени, свойствам, тегам (FTS5 / PostgreSQL tsvector)

• Семантический поиск — векторные эмбеддинги через sentence-transformers

• Пространства имён — изолированные области знаний (проекты, темы)

• Теги и категории — гибкая классификация

• Экспорт графа — JSON/Markdown дамп всей базы знаний

• TTL для сущностей — автоматическое "забывание" устаревших данных

🌐 Web Browser (Поиск в интернете)

• Поиск через DuckDuckGo — без API-ключа, бесплатно

• Скрейпинг страниц — извлечение основного контента по URL

• Сохранение страниц как знаний — с эмбеддингами для поиска

• Кэширование в Redis — повторные запросы без задержек

💬 Dialogue Memory (Память диалогов)

• Хранение истории — каждая сессия диалога сохраняется

• Извлечение контекста — восстановление предыдущих разговоров

• Очистка сессии — управление памятью

⚙️ Системное

• Health Check — мониторинг БД, Redis, эмбеддингов

• Статистика — количество сущностей, связей, размер БД

• Резервное копирование — SQLite backup / PostgreSQL dump

🖥️ Web UI

• Dashboard — статистика, графики, граф знаний (D3.js)

• Entity Browser — поиск и просмотр сущностей

• Timeline — временная шкала изменений

• Graph Visualization — force-directed граф с зумом

🏗️ Архитектура

┌─────────────────────────────────────────────────────────┐
│                   MCP Client (Claude)                    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP Protocol (stdio / SSE)
┌──────────────────────▼──────────────────────────────────┐
│                    server.py (FastMCP)                    │
│  ┌────────────┐  ┌────────────┐  ┌───────────────────┐  │
│  │ Knowledge   │  │  Browser    │  │  Dialogue Memory │  │
│  │ Graph Tools │  │  Tools      │  │  Tools           │  │
│  └──────┬──────┘  └──────┬─────┘  └───────┬───────────┘  │
│         │                │                 │              │
│  ┌──────▼────────────────▼─────────────────▼──────────┐  │
│  │              KnowledgeGraph (core logic)            │  │
│  └──────┬──────────────────────┬──────────────────────┘  │
│         │                      │                         │
│  ┌──────▼──────┐       ┌──────▼──────┐                  │
│  │  SQLite3 /  │       │    Redis    │                  │
│  │ PostgreSQL  │       │   (cache)   │                  │
│  └─────────────┘       └─────────────┘                  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │         EmbeddingsEngine (sentence-transformers)  │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Технологии

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

Установка

# Клонировать репозиторий
cd mcp-server

# Установить зависимости (рекомендуется использовать uv)
uv sync

# Или через pip
pip install -e .

Настройка

cp .env.example .env
# Отредактировать .env при необходимости

Запуск сервера (локальная сеть)

Сервер работает по SSE (Server-Sent Events) и доступен в локальной сети.

Через Python (SQLite)

# Установить зависимости
pip install -e .

# Запустить MCP сервер (SSE транспорт, порт 8000)
python -m server

Сервер будет доступен по адресу: http://127.0.0.1:8000/sse

Через Python (PostgreSQL)

# Настроить .env
DB_TYPE=postgres
PG_HOST=your-postgres-host
PG_USER=postgres
PG_PASSWORD=your-password
PG_DATABASE=mcp_memory

# Запустить
python -m server

Через Docker Compose (SQLite + Redis)

docker compose up -d

# Сервер: http://SERVER_IP:8000/sse
# Redis: порт 6379

Через Docker Compose (PostgreSQL + Redis — production)

cp .env.example .env
# Отредактировать PG_PASSWORD и EMBEDDINGS_MODE

docker compose -f docker-compose.remote.yml up -d

# PostgreSQL: порт 5432 (только localhost)
# Redis: порт 6379 (только localhost)
# Сервер: http://SERVER_IP:8000/sse

Вариант 1: Автоматически (конфигурация в проекте)

В файле .vscode/mcp.json уже прописано подключение по URL:

{
    "servers": {
        "memory-server": {
            "type": "url",
            "url": "http://localhost:8000/sse"
        }
    }
}

Замените localhost на IP-адрес сервера в локальной сети, если VS Code запущен на другом компьютере.

Вариант 2: Через settings.json пользователя

Добавьте в глобальный settings.json VS Code (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):

{
    "mcp": {
        "servers": {
            "memory-server": {
                "type": "url",
                "url": "http://192.168.1.100:8000/sse"
            }
        }
    }
}

Замените IP на фактический адрес сервера.

Вариант 3: Локальный запуск сервера на том же компьютере

Если VS Code запущен на том же компьютере, что и сервер:

{
    "mcp": {
        "servers": {
            "memory-server": {
                "type": "url",
                "url": "http://localhost:8000/sse"
            }
        }
    }
}

Проверка подключения

1. Убедитесь, что сервер запущен (команда python -m server или docker-compose up -d)

2. Откройте VS Code

3. Если настроено через .vscode/mcp.json — откройте папку проекта

4. Используйте Ctrl+Shift+P → "MCP: List Tools" чтобы увидеть все доступные инструменты

5. При успешном подключении вы увидите список из 18 инструментов

Подключение из Kilo Code

Kilo Code поддерживает MCP серверы по протоколу SSE. Добавьте в kilo.json (глобальный ~/.config/kilo/kilo.json или проектный ./kilo.json):

Без авторизации

{
  "mcp": {
    "memory-server": {
      "type": "remote",
      "url": "http://192.168.1.100:8000/sse",
      "enabled": true
    }
  }
}

С авторизацией (SSE_API_KEY)

{
  "mcp": {
    "memory-server": {
      "type": "remote",
      "url": "http://192.168.1.100:8000/sse",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      },
      "enabled": true
    }
  }
}

Замените IP и ключ на фактические значения сервера.

Подключение из Roo Code

Roo Code также поддерживает SSE MCP серверы. Добавьте в mcp_settings.json (или в настройках расширения → MCP → Edit Settings):

{
  "mcpServers": {
    "memory-server": {
      "type": "sse",
      "url": "http://192.168.1.100:8000/sse",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      }
    }
  }
}

Если авторизация не включена — поле headers можно опустить.

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

Knowledge Graph

Browser

Dialogue Memory

System

📝 Примеры использования

Сохранение знаний

🔧 store_entity(
    name="Python asyncio",
    entity_type="concept",
    properties='{"category": "programming", "difficulty": "intermediate"}',
    tags="python,async,programming"
)

Поиск с семантикой

🔍 search_knowledge(
    query="асинхронное программирование",
    use_semantic=true,
    limit=5
)

Связывание сущностей

🔗 add_relation(
    source_id="<entity_id_1>",
    target_id="<entity_id_2>",
    relation_type="depends_on"
)

Поиск в интернете и сохранение

🌐 web_search(query="последние новости AI", max_results=5)

📄 scrape_page(url="https://example.com/article")

💾 save_webpage_to_knowledge(
    url="https://example.com/article",
    tags="AI,research"
)

🐳 Docker

Локальная разработка (SQLite + Redis)

docker compose up -d

Production (PostgreSQL + Redis)

# Полный стек (PostgreSQL, Redis, MCP Server)
docker compose -f docker-compose.remote.yml up -d

# Или с внешней PostgreSQL (без локального контейнера PG)
docker compose -f docker-compose.remote.yml --profile external-db up -d

Сборка образа вручную

docker build -t mcp-memory-server .

# Запуск с пробросом .env
docker run -it --rm --env-file .env -v mcp-data:/app/data mcp-memory-server

🧪 Тестирование

# Установить dev-зависимости
pip install -e ".[dev]"

# Запустить тесты
pytest -v

# С覆盖率
pytest --cov=. --cov-report=term-missing

📦 Переменные окружения

🤝 Предлагаемые улучшения

• Авторизация — Bearer token аутентификация для SSE-эндпоинтов (SSE_AUTH_ENABLED + SSE_API_KEY)

• Мониторинг URL — периодическая проверка страниц на изменения

• OpenTelemetry — метрики и трейсинг

• Партиционирование — шардирование PostgreSQL по namespace

• Бэкап PostgreSQL — автоматический pg_dump по расписанию

📋 Changelog

v0.2.0 — PostgreSQL, async, Web UI

• PostgreSQL: новый async-клиент (storage/postgres_client.py) на asyncpg:

  • Пул соединений, JSONB, GIN-индексы, FTS через tsvector

  • 16 индексов: GIN на JSONB/TEXT[]/tsvector, композитные, покрывающие

  • Каскадные внешние ключи (ON DELETE CASCADE)

  • Переключение между SQLite/PostgreSQL через DB_TYPE в .env

• Async dispatch: KnowledgeGraph автоматически определяет sync/async хранилище

• Web UI: Dashboard с D3.js графом, Entity Browser, Timeline, Stats

• Favicon: иконка сервера (mcp.png) на всех страницах Web UI

• Docker Compose: docker-compose.remote.yml для production-развёртывания

• Тесты: 176/176, 0 warnings

v0.1.1 (предыдущий релиз)

• Исправлен критический баг: __version__ теперь определён в server.py, сервер не падает при запуске

• Исправлены импорты: относительные импорты (from ..storage) заменены на абсолютные (from storage)

• Починены тесты: 73% тестов (143 из 197) теперь выполняются (раньше падали с ImportError)

• Оптимизация производительности:

  • N+1 запросы в GraphVisualizer заменены на batch-запрос get_relations_for_entities

  • list_namespaces() теперь использует SELECT DISTINCT вместо загрузки всех сущностей

  • export_graph() использует batch-запрос вместо цикла

• Безопасность:

  • Добавлен html.escape() для всех пользовательских данных в Web UI (XSS)

  • Добавлена защита path traversal в MarkdownImporter

  • MCP_HOST по умолчанию изменён на 127.0.0.1

• Улучшения кода:

  • Убран мёртвый вызов search_knowledge() в url_monitor.py

  • _parse_json() теперь принимает str | None

  • cosine_similarity() — @staticmethod

  • Суждены блоки except Exception до конкретных исключений

  • Убраны поздние импорты в server.py

  • Добавлен fastembed в optional-dependencies

  • Устранён дубликат тестового класса TestSearchEngineWithMockRedis

  • Модельные тесты вынесены в test_models.py

📄 Лицензия

MIT