MCP SharedMemory Server

Установка

1. Убедитесь, что у вас установлен Go 1.25 или выше
2. Клонируйте репозиторий:

git clone https://git.ymnuktech.ru/ymnuk/mcp-0memory.git
cd mcp-0memory

3. Переименуйте модуль в go.mod под ваш проект:

go mod edit -module your-project-name

4. Установите зависимости:

go mod download

5. Соберите проект:

go build .

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

Сервер поддерживает следующие параметры конфигурации:

Параметр	Флаг	Переменная окружения	По умолчанию	Описание
Port	-p, --port	WEB_PORT	3000	Порт для входящих соединений
OpenAI Base URL	-o, --openai-base-url	OPENAI_BASE_URL		Базовый URL для OpenAI API
OpenAI Embedding Base URL	-o, --openai-embed-base-url	OPENAI_EMBED_BASE_URL		Базовый URL для OpenAI API эмбеддингов
OpenAI API Key	-k, --openai-api-key	OPENAI_API_KEY		API ключ для OpenAI
OpenAI Embedding API Key	-k, --openai-embed-api-key	OPENAI_EMBED_API_KEY		API ключ для OpenAI эмбеддингов
Database Path	-d, --db-path	DB_PATH	./data.db	Путь к файлу базы данных
TLS Verify	-t, --ttl-verify	TLS_VERIFY	true	Проверка TLS
Model	-m, --model	MODEL	gpt-3.5-turbo	Модель для использования
Embedding Model	-m, --model-embed	MODEL_EMBED	text-embedding-ada-002	Модель для эмбеддингов
Token	-t, --token	TOKEN		Токен для аутентификации администратора

Конфигурационный параметр TOKEN используется для аутентификации администратора при управлении токенами пользователей.

Использование

Запустите MCP сервер:

./mcp-0memory

Или с настройкой параметров:

./mcp-0memory --port 3001 --db-path ./my_memory.db --token "admin_token"

Или с использованием переменных окружения:

WEB_PORT=3001 DB_PATH=./my_memory.db TOKEN="admin_token" ./mcp-0memory

Сервер будет доступен по адресу http://localhost:3000/mcp

Архитектура

Сервер включает следующие компоненты:

• LLM API Client: Интерфейс к llm-simple-api для генерации эмбеддингов и суммаризаций
• Memory Chunk Manager: Оркестратор записи контента, суммаризации и эмбеддингов
• Semantic Search Engine: Семантический поиск с использованием косинусного сходства
• In-Memory Cache: Кэш с TTL для эмбеддингов с автоматической очисткой
• Token-Based Router: Маршрутизатор с фильтрацией по токену владельца
• MCP Transport Layer: Обработка JSON-RPC 2.0 запросов для методов shared_memory/*

MCP Методы

Сервер реализует следующие MCP методы:

shared_memory/write

Сохранение контента в общую память.

Параметры:

• content: string (обязательный) - Контент для сохранения в памяти
• scope: string (опциональный) - Область доступа (public/private, по умолчанию private)
• type: string (опциональный) - Тип фрагмента памяти (message/snippet/doc/other, по умолчанию message)

shared_memory/search

Выполнение семантического поиска в общей памяти.

Параметры:

• query: string (обязательный) - Поисковый запрос
• top_k: int (опциональный) - Количество возвращаемых результатов (по умолчанию 5)

shared_memory/list

Вывод всех фрагментов памяти для конкретного владельца.

HTTP Административные Эндпоинты

Сервер предоставляет HTTP-эндпоинты для управления токенами пользователей. Все эндпоинты защищены с помощью токена администратора, заданного в конфигурации.

/generate_token (POST)

Создание нового токена для пользователя.

Заголовок: Authorization: Bearer <admin_token>

Параметры запроса:

• name: string (опциональный) - Имя пользователя, по умолчанию "User"
• nick: string (опциональный) - Никнейм пользователя, по умолчанию "user"

Пример запроса:

curl -X POST -H "Authorization: Bearer admin_token" -H "Content-Type: application/json" \
-d '{"name": "John Doe", "nick": "johndoe"}' \
http://localhost:3000/generate_token

Пример ответа:

{
  "token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
}

/modify_token (POST)

Изменение информации о токене (имя и никнейм).

Заголовок: Authorization: Bearer <admin_token>

Параметры запроса:

• token: string (обязательный) - Токен пользователя для изменения
• name: string (обязательный) - Новое имя пользователя
• nick: string (обязательный) - Новый никнейм пользователя

Пример запроса:

curl -X POST -H "Authorization: Bearer admin_token" -H "Content-Type: application/json" \
-d '{"token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456", "name": "Jane Smith", "nick": "janesmith"}' \
http://localhost:3000/modify_token

Пример ответа:

{
  "status": "Token updated successfully"
}

/remove_token (POST)

Удаление токена пользователя (отзыв доступа).

Заголовок: Authorization: Bearer <admin_token>

Параметры запроса:

• token: string (обязательный) - Токен пользователя для удаления

Пример запроса:

curl -X POST -H "Authorization: Bearer admin_token" -H "Content-Type: application/json" \
-d '{"token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"}' \
http://localhost:3000/remove_token

Пример ответа:

{
  "status": "Token removed successfully"
}

/activate_token (POST)

Активация токена пользователя (восстановление доступа).

Заголовок: Authorization: Bearer <admin_token>

Параметры запроса:

• token: string (обязательный) - Токен пользователя для активации

Пример запроса:

curl -X POST -H "Authorization: Bearer admin_token" -H "Content-Type: application/json" \
-d '{"token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"}' \
http://localhost:3000/activate_token

Пример ответа:

{
  "status": "Token activated successfully"
}

/deactivate_token (POST)

Деактивация токена пользователя (приостановка доступа).

Заголовок: Authorization: Bearer <admin_token>

Параметры запроса:

• token: string (обязательный) - Токен пользователя для деактивации

Пример запроса:

curl -X POST -H "Authorization: Bearer admin_token" -H "Content-Type: application/json" \
-d '{"token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"}' \
http://localhost:3000/deactivate_token

Пример ответа:

{
  "status": "Token deactivated successfully"
}

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

Пример MCP запроса для сохранения фрагмента памяти:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "toolName": "shared_memory/write",
    "arguments": {
      "content": "Заметки из встречи: планирование на квартал прошло продуктивно. Мы решили сосредоточиться на улучшении пользовательского опыта в Q1.",
      "scope": "private",
      "type": "message"
    }
  }
}

Пример MCP запроса для поиска в памяти:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "toolName": "shared_memory/search",
    "arguments": {
      "query": "планирование на квартал",
      "top_k": 3
    }
  }
}

Пример MCP запроса для вывода фрагментов памяти:

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "toolName": "shared_memory/list",
  }
}

Структура проекта

mcp-0memory/
├── main.go                 # Основной файл приложения
├── go.mod                  # Модуль Go
├── config/                 # Конфигурация приложения
│   └── config.go
├── handler/                # Обработчики HTTP-запросов и MCP-инструментов
│   ├── example.go          # Пример MCP-инструмента
│   ├── health.go           # Эндпоинт проверки состояния
│   └── shared_memory.go    # Обработчики shared_memory инструментов
├── middleware/             # Middleware для логирования и метрик
│   ├── mddleware.go        # Middleware для логирования
│   └── metrics.go          # Middleware для сбора метрик
├── db/                     # Код для работы с БД
│   ├── db.go               # Инициализация DB
│   ├── model/              # Модели данных
│   │   ├── memory_chunk.go # Модель фрагмента памяти
│   │   └── token.go        # Модель токена пользователя
│   ├── repository.go       # Интерфейс репозитория
│   ├── repository_impl.go  # Реализация репозитория для фрагментов
│   └── token_repository_impl.go # Реализация репозитория для токенов
├── memory/                 # Менеджер фрагментов памяти
│   └── chunk_manager.go    # Управление фрагментами памяти
├── search/                 # Поисковый движок
│   ├── similarity.go       # Функция косинусного сходства
│   └── search_engine.go    # Реализация поиска
├── cache/                  # Кэш эмбеддингов
│   └── embedding_cache.go  # Кэш с TTL
├── router/                 # Маршрутизатор по токенам
│   └── context_router.go   # Маршрутизатор с проверкой токенов
├── users/                  # Управление пользователями
│   └── user_manager.go     # Управление токенами пользователей
└── llm/                    # Клиент для работы с LLM
    └── client.go           # Клиент для эмбеддингов и суммаризации

Мониторинг

Сервер предоставляет метрики в формате Prometheus по адресу /metrics. Доступны следующие метрики:

HTTP-метрики

• http_requests_total - Общее количество HTTP-запросов с разбивкой по методу, пути и статусу
• http_request_duration_seconds - Гистограмма времени выполнения HTTP-запросов

Метрики MCP инструментов

• mcp_tool_calls_total - Общее количество вызовов MCP инструментов с разбивкой по имени инструмента и статусу (успешно/ошибка)
• mcp_tool_call_duration_seconds - Гистограмма времени выполнения вызовов MCP инструментов

Процессные метрики

• process_cpu_seconds_total - Общее время CPU, затраченное процессом (включает пользовательское и системное время) - стандартная метрика Go-рантайма
• process_resident_memory_bytes_custom - Объем резидентной памяти процесса в байтах (кастомная метрика)

Эндпоинты

Сервер предоставляет следующие HTTP-эндпоинты:

• /mcp - основной endpoint для MCP-инструментов
• /metrics - endpoint для сбора Prometheus-метрик
• /health - endpoint для проверки состояния сервиса (возвращает HTTP 200 OK)
• /generate_token - endpoint для генерации новых токенов пользователей (требует аутентификации администратора)
• /modify_token - endpoint для изменения информации токена (требует аутентификации администратора)
• /remove_token - endpoint для удаления токена (требует аутентификации администратора)
• /activate_token - endpoint для активации токена (требует аутентификации администратора)
• /deactivate_token - endpoint для деактивации токена (требует аутентификации администратора)

Архитектурная схема

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Клиент    │───▶│  MCP Транспорт   │───▶│  Контекстный    │
└─────────────────┘    │    Слой          │    │   Маршрутизатор │
                       └──────────────────┘    └─────────────────┘
                                                      │
                    ┌────────────────-──┐             │
                    │ Менеджер Фрагмента│◀────────────┘
                    │      Памяти       │
                    └──────────────────-┘
                             │
                    ┌──────────────────┐
                    │   Поисковый      │
                    │   Движок         │
                    └──────────────────┘
                             │
                    ┌──────────────────┐
                    │   LLM Клиент     │
                    └──────────────────┘
                             │
                    ┌──────────────────┐
                    │  SQLite Хранилище│
                    └──────────────────┘
                             │
                    ┌──────────────────┐
                    │   User Manager   │
                    └──────────────────┘
                             │
                    ┌──────────────────┐
                    │  Токен Хранилище │
                    └──────────────────┘

Плавное завершение работы

Сервер обрабатывает сигналы SIGINT и SIGTERM для плавного завершения работы, гарантируя корректное закрытие всех соединений и очистку ресурсов.

Лицензия

Этот проект распространяется под лицензией MIT, подробности см. в файле LICENSE.