Добавлен README.md

2026-05-28 14:05:51 +00:00
parent 1364ad2f89
commit 750a79d383
1 changed files with 75 additions and 83 deletions
@@ -1,128 +1,120 @@
 # MCP‑сервер для управления памятью агента

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

-Основные возможности:
- **Namespaces** – изоляция данных по логическим группам (например, пользователь, проект, агент).
- CRUD‑операции над записями памяти.
- Простая REST‑подобная API через MCP‑протокол.
- Легкая интеграция с другими агентами и сервисами.
+- **FastMCP** – быстрый HTTP‑сервер для MCP.
+- **Pydantic** – валидатор данных (не используется напрямую в примере, но готов к расширению).
+- **python-dotenv** – загрузка переменных окружения из `.env`.

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

-Установите зависимости из `requirements.txt`:
+Установите зависимости через `pip`:

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

-### Файлы проекта
- `memory_server.py` – основной серверный скрипт.
- `memory_client.py` – пример клиента, демонстрирующий работу с сервером.
+Файл `requirements.txt` содержит:
+```
+fastmcp>=0.1.0
+pydantic>=2.0
+python-dotenv>=1.0
+```

-## Установка
+## Установка  
+Клонируйте репозиторий и установите зависимости:

-1. Клонируйте репозиторий:
+```bash
+git clone https://github.com/your-org/memory-mcp.git
+cd memory-mcp
+pip install -r requirements.txt
+```

-   ```bash
-   git clone https://github.com/your-org/memory-mcp-server.git
-   cd memory-mcp-server
-   ```
+Создайте файл `.env` в корне проекта (если понадобится):

-2. Создайте виртуальное окружение (необязательно, но рекомендуется):
+```dotenv
+MEMORY_FILE=memory_data.json
+PORT=8000
+```

-   ```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). Вы увидите лог‑сообщения о подключениях и выполненных запросах.
+Сервер будет слушать на порту, указанном в переменной `PORT` (по умолчанию 8000).  

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

 ```python
-# memory_client_example.py
-from memory_client import MemoryClient
+# memory_client.py
+from fastmcp import FastMCPClient
+import json

-client = MemoryClient(host="localhost", port=8000)
+client = FastMCPClient("Memory-Server", 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}")
+# Сохранить запись
+response = client.post("/memory/namespace1/item1", data={"value": 42})
+print(response.json())

 # Получить запись
-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)
+response = client.get("/memory/namespace1/item1")
+print(response.json())
 ```

-Запустите пример:
+Запустите клиент в отдельном терминале:

 ```bash
-python memory_client_example.py
+python memory_client.py
 ```

+## Пример работы
+
+1. **Сохранение данных**
+
+   ```bash
+   curl -X POST http://localhost:8000/memory/namespaces/agents/agent_123 \
+        -H "Content-Type: application/json" \
+        -d '{"name":"Alice","role":"researcher"}'
+   ```
+
+2. **Получение данных**
+
+   ```bash
+   curl http://localhost:8000/memory/namespaces/agents/agent_123
+   ```
+
+3. **Обновление записи**
+
+   ```bash
+   curl -X PUT http://localhost:8000/memory/namespaces/agents/agent_123 \
+        -H "Content-Type: application/json" \
+        -d '{"name":"Alice","role":"senior researcher"}'
+   ```
+
+4. **Удаление записи**
+
+   ```bash
+   curl -X DELETE http://localhost:8000/memory/namespaces/agents/agent_123
+   ```
+
 ## Структура проекта

 ```
-memory-mcp-server/
-├── .env
+memory-mcp/
+├── memory_server.py  # Сервер MCP
+├── memory_client.py  # Пример клиента
 ├── requirements.txt
-├── memory_server.py
-├── memory_client.py
-└── README.md
-```
-
- `memory_server.py` – реализует класс `MemoryServer`, который инициализирует FastMCP, обрабатывает запросы и хранит данные в JSON‑файле.
- `memory_client.py` – простая обёртка над MCP‑протоколом для удобного взаимодействия с сервером.
-
-## Тестирование
-
-Для запуска тестов (если добавлены):
-
-```bash
-pytest tests/
+└── .env (опционально)
 ```

 ---

-**Автор:** *Ваше имя*  
-**Дата:** 2026‑05‑28
+**Готово!** Теперь у вас есть работающий MCP‑сервер для управления памятью агентов. 🚀