# MCP‑сервер для управления памятью агента

## Описание проекта  
MCP‑сервер (Model Context Protocol) – это независимый сервис, который предоставляет API для хранения и извлечения данных памяти агентов через единый протокол. Сервис реализован на `fastmcp`, использует `pydantic` для валидации входных/выходных структур и `python-dotenv` для загрузки переменных окружения.

Основные возможности:
- **Namespaces** – изоляция данных по логическим группам (например, пользователь, проект, агент).
- CRUD‑операции над записями памяти.
- Простая REST‑подобная API через MCP‑протокол.
- Легкая интеграция с другими агентами и сервисами.

## Предварительные требования  
| Пакет | Версия |
|-------|--------|
| Python | 3.10+ |
| pip | Любой актуальный |

Установите зависимости из `requirements.txt`:

```bash
pip install -r requirements.txt
```

### Файлы проекта
- `memory_server.py` – основной серверный скрипт.
- `memory_client.py` – пример клиента, демонстрирующий работу с сервером.

## Установка

1. Клонируйте репозиторий:

   ```bash
   git clone https://github.com/your-org/memory-mcp-server.git
   cd memory-mcp-server
   ```

2. Создайте виртуальное окружение (необязательно, но рекомендуется):

   ```bash
   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   ```

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

   ```bash
   pip install -r requirements.txt
   ```

4. Создайте файл `.env` в корне проекта (если понадобится):

   ```dotenv
   MCP_HOST=0.0.0.0
   MCP_PORT=8000
   MEMORY_FILE=data/memory.json
   ```

## Запуск сервера

```bash
python memory_server.py
```

Сервер будет слушать на порту, указанном в переменной `MCP_PORT` (по умолчанию 8000). Вы увидите лог‑сообщения о подключениях и выполненных запросах.

## Пример использования клиента

```python
# memory_client_example.py
from memory_client import MemoryClient

client = MemoryClient(host="localhost", port=8000)

# Создать запись в namespace "project_alpha"
record_id = client.create(
    namespace="project_alpha",
    key="task_42",
    value={"status": "in_progress", "assigned_to": "agent_7"}
)
print(f"Создана запись с id: {record_id}")

# Получить запись
data = client.read(namespace="project_alpha", record_id=record_id)
print("Полученные данные:", data)

# Обновить запись
client.update(
    namespace="project_alpha",
    record_id=record_id,
    value={"status": "completed"}
)

# Удалить запись
client.delete(namespace="project_alpha", record_id=record_id)
```

Запустите пример:

```bash
python memory_client_example.py
```

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

```
memory-mcp-server/
├── .env
├── requirements.txt
├── memory_server.py
├── memory_client.py
└── README.md
```

- `memory_server.py` – реализует класс `MemoryServer`, который инициализирует FastMCP, обрабатывает запросы и хранит данные в JSON‑файле.
- `memory_client.py` – простая обёртка над MCP‑протоколом для удобного взаимодействия с сервером.

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

Для запуска тестов (если добавлены):

```bash
pytest tests/
```

---

**Автор:** *Ваше имя*  
**Дата:** 2026‑05‑28