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

Технологии

Компонент	Технология	Назначение
MCP Server	mcp[cli] (FastMCP)	Протокол взаимодействия
Хранилище	SQLite3 / PostgreSQL (asyncpg)	Персистентность данных
Кэш	Redis (async)	Кэш запросов, сессии, TTL
Эмбеддинги	sentence-transformers / fastembed	Семантический поиск
Поиск	duckduckgo-search	Бесплатный веб-поиск
Скрейпинг	httpx + beautifulsoup4	Извлечение контента
Web UI	Starlette + D3.js	Визуализация графа

---

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

Установка

# Клонировать репозиторий
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

Инструмент	Описание	Параметры
store_entity	Сохранить сущность	name, entity_type, properties(JSON), namespace, tags, ttl_seconds
get_entity	Получить сущность	entity_id или name + namespace
search_knowledge	Поиск по базе знаний	query, namespace, entity_type, tags, use_semantic, limit
list_entities	Список сущностей	namespace, entity_type, limit, offset
delete_entity	Удалить сущность	entity_id
add_relation	Создать связь	source_id, target_id, relation_type, properties
get_relations	Связи сущности	entity_id, relation_type
export_graph	Экспорт графа	namespace

Browser

Инструмент	Описание	Параметры
web_search	Поиск в интернете	query, max_results
scrape_page	Извлечь текст страницы	url
save_webpage_to_knowledge	Сохранить страницу как знание	url, namespace, tags

Dialogue Memory

Инструмент	Описание	Параметры
store_dialogue	Сохранить реплику	session_id, role, content, namespace
get_dialogue_history	История сессии	session_id, limit
clear_dialogue_history	Очистить историю	session_id

System

Инструмент	Описание	Параметры
health_check	Проверка сервисов	—
get_stats	Статистика	namespace
list_namespaces	Список пространств	—

---

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

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

🔧 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

---

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

Переменная	По умолчанию	Описание
DB_TYPE	sqlite	Тип БД: sqlite или postgres
SQLITE_DB_PATH	data/memory.db	Путь к SQLite (при DB_TYPE=sqlite)
PG_HOST	localhost	Хост PostgreSQL (при DB_TYPE=postgres)
PG_PORT	5432	Порт PostgreSQL
PG_USER	postgres	Пользователь PostgreSQL
PG_PASSWORD	—	Пароль PostgreSQL
PG_DATABASE	mcp_memory	Имя БД PostgreSQL
PG_POOL_SIZE	10	Размер пула соединений asyncpg
REDIS_HOST	localhost	Хост Redis
REDIS_PORT	6379	Порт Redis
REDIS_DB	0	Номер БД Redis
REDIS_PASSWORD	—	Пароль Redis
MCP_HOST	127.0.0.1	Интерфейс для SSE сервера
MCP_PORT	8010	Порт для SSE сервера
MCP_TRANSPORT	sse	Транспорт: sse (сеть) или stdio (локально)
EMBEDDINGS_MODE	local	Режим эмбеддингов: none, local или fastembed
EMBEDDINGS_MODEL_NAME	all-MiniLM-L6-v2	Модель эмбеддингов
DEFAULT_NAMESPACE	default	Пространство имён по умолчанию
ENTITY_TTL_SECONDS	0	TTL для сущностей (0 = без TTL)
SSE_AUTH_ENABLED	false	Включить Bearer token аутентификацию для SSE
SSE_API_KEY	—	API-ключ для SSE эндпоинтов

---

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

• [x] Авторизация — 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