MCP-сервер для управления памятью агента: README.md

2026-05-27 11:21:24 +00:00
parent 63523592ff
commit e3c7df487a
1 changed files with 119 additions and 0 deletions
@@ -0,0 +1,119 @@
+# MCP Memory Server
+
+## 📌 Описание проекта
+Этот проект реализует **MCP‑сервер (Model Context Protocol)**, который предоставляет API для управления памятью агента в распределённой системе.  
+Сервер хранит данные в JSON‑файле и поддерживает:
+- *namespaces* – логическое разделение данных;
+- *wildcard‑поиск* ключей (`fnmatch`);
+- простую модель CRUD через протокол MCP.
+
+Клиентский скрипт `memory_client.py` демонстрирует, как обращаться к серверу из другого агента или CLI‑утилиты.
+
+---
+
+## ⚙️ Предварительные требования
+| Компонент | Версия | Как установить |
+|-----------|--------|----------------|
+| Python    | 3.10+  | `python -m venv .venv && source .venv/bin/activate` (Linux/macOS) / `.venv\Scripts\activate` (Windows) |
+| pip       | —      | Встроен в Python |
+| **Библиотеки** | — | Установить из `requirements.txt` |
+
+> **Важно:** Сервер не требует внешних сервисов, но при желании можно подключить к базе данных или использовать Docker‑контейнеры.
+
+---
+
+## 📦 Установка
+```bash
+# Клонируйте репозиторий (или скачайте архив)
+git clone https://github.com/your-org/mcp-memory-server.git
+cd mcp-memory-server
+
+# Создайте виртуальное окружение и активируйте его
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# Установите зависимости
+pip install -r requirements.txt
+```
+
+`requirements.txt`
+```text
+fastmcp>=0.1.0
+pydantic>=2.0
+python-dotenv>=1.0
+```
+
+---
+
+## 🚀 Запуск сервера и клиента
+
+### 1️⃣ Запустить сервер
+```bash
+# В корне проекта
+python memory_server.py
+```
+Сервер будет слушать по адресу `http://127.0.0.1:8000` (по умолчанию).  
+При первом запуске создастся файл `memory_data.json`.
+
+### 2️⃣ Запустить клиент
+```bash
+# В другом терминале, в той же виртуальной среде
+python memory_client.py
+```
+Клиент демонстрирует пример CRUD‑операций:
+- Добавление записи;
+- Чтение всех записей;
+- Поиск по шаблону;
+- Удаление.
+
+---
+
+## 📚 Пример использования
+
+```bash
+# 1. Запускаем сервер
+python memory_server.py
+
+# 2. В другом терминале запускаем клиент (или пишем свой скрипт)
+python memory_client.py
+```
+
+### Вывод клиента
+```
+Added record: {'namespace': 'chat', 'key': 'msg_001', 'value': 'Hello, world!'}
+All records:
+[{'namespace': 'chat', 'key': 'msg_001', 'value': 'Hello, world!'}]
+Search results for pattern '*msg*':
+[{'namespace': 'chat', 'key': 'msg_001', 'value': 'Hello, world!'}]
+Deleted record: {'namespace': 'chat', 'key': 'msg_001'}
+```
+
+---
+
+## 📁 Структура проекта
+```text
+mcp-memory-server/
+├── memory_server.py   # Сервер MCP
+├── memory_client.py   # Демонстрационный клиент
+├── requirements.txt   # Зависимости
+└── README.md          # Это файл
+```
+
+---
+
+## 🔧 Настройка
+
+Если нужно изменить порт или путь к файлу хранения, отредактируйте конструктор `MemoryServer` в `memory_server.py`:
+
+```python
+self.mcp = FastMCP("Memory-Server", host="0.0.0.0", port=8080)
+self.storage_path = Path("./data/memory.json")
+```
+
+---
+
+## 📜 Лицензия
+
+MIT License – см. файл `LICENSE`.
+
+---