26 lines
12 KiB
Markdown
26 lines
12 KiB
Markdown
{
|
||
"task": {
|
||
"_id": "69f8e929da860fb4533faa2a",
|
||
"title": "MCP-сервер для управления памятью агента",
|
||
"description": "# Практическое задание: MCP-сервер для управления памятью агента\n\n## Цель\n\nСоздать **MCP-сервер (Model Context Protocol)** — самостоятельный сервис, который предоставляет другим агентам инструменты для работы с памятью через стандартизированный протокол. Это первый шаг к построению распределённых многоагентных систем, где агенты могут обмениваться данными и координировать работу через единое хранилище.\n\nВ отличие от локальной памяти внутри одного скрипта, MCP-сервер — это независимый процесс с API, доступный для любого клиента (другого агента, CLI-утилиты или другого сервиса).\n\n---\n\n## Стек и установка\n\n- Python 3.10+\n- Пакеты: `fastmcp` (фреймворк MCP), `pydantic` (валидация данных)\n\nУстановка:\n\n```bash\npip install fastmcp pydantic python-dotenv\n```\n\n> **Важно:** `fastmcp` — это библиотека для создания серверов и клиентов MCP. Она позволяет регистрировать инструменты, которые становятся доступны агентам через протокол stdio или SSE.\n\n---\n\n## Что нужно сделать\n\n### 1. Создать MCP-сервер с базовыми инструментами памяти\n\nСоздай файл `memory_server.py`, в котором определишь класс сервера на основе `FastMCP`:\n\n```python\nfrom fastmcp import FastMCP\nimport json\nfrom datetime import datetime\nfrom pathlib import Path\nfrom typing import Any, Optional\n\nclass MemoryServer:\n def __init__(self):\n self.mcp = FastMCP(\"Memory-Server\")\n self.storage_path = Path(\"./memory_data.json\")\n \n def _load_memory(self) -> dict:\n \"\"\"Загружает память из JSON-файла.\"\"\"\n if not self.storage_path.exists():\n return {}\n with open(self.storage_path, 'r', encoding='utf-8') as f:\n return json.load(f)\n \n def _save_memory(self, data: dict):\n \"\"\"Сохраняет память в JSON-файл.\"\"\"\n self.storage_path.parent.mkdir(parents=True, exist_ok=True)\n with open(self.storage_path, 'w', encoding='utf-8') as f:\n json.dump(data, f, indent=2, ensure_ascii=False)\n \n @self.mcp.tool()\n def save(key: str, value: Any) -> bool:\n \"\"\"Сохраняет значение по ключу в память сервера.\n \n Args:\n key: Идентификатор для сохранения (уникальный ключ).\n value: Любое сериализуемое значение.\n \n Returns:\n True при успешном сохранении, False иначе.\n \"\"\"\n # Реализуй здесь...\n \n @self.mcp.tool()\n def get(key: str) -> Optional[dict]:\n \"\"\"Возвращает значение по ключу с метаданными.\n \n Args:\n key: Идентификатор для поиска.\n \n Returns:\n Словарь с полями {\"key\": ..., \"value\": ..., \"timestamp\": ...} \n или None если ключ не найден.\n \"\"\"\n # Реализуй здесь...\n \n @self.mcp.tool()\n def delete(key: str) -> bool:\n \"\"\"Удаляет ключ из памяти сервера.\n \n Args:\n key: Идентификатор для удаления.\n \n Returns:\n True при успешном удалении, False если ключ не найден.\n \"\"\"\n # Реализуй здесь...\n \n @self.mcp.tool()\n def list_keys(pattern: str = \"*\") -> list[str]:\n \"\"\"Возвращает список всех ключей с поддержкой wildcard-паттерна.\n \n Args:\n pattern: Паттерн для фильтрации (поддерживает * и ?).\n \n Returns:\n Список совпадающих ключей.\n \"\"\"\n # Реализуй здесь...\n```\n\n### 2. Добавить инструменты с поддержкой namespaces\n\n**Namespace** — это пространство имён для изоляции данных. Например, один агент может работать в namespace `agent_1`, другой — в `agent_2`. Данные не пересекаются.\n\nДобавь следующие инструменты:\n\n```python\n @self.mcp.tool()\n def save_with_namespace(key: str, value: Any, namespace: str = \"default\") -> bool:\n \"\"\"Сохраняет значение с указанием пространства имён.\n \n Args:\n key: Идентификатор.\n value: Значение для сохранения.\n namespace: Пространство имён (по умолчанию 'default').\n \n Returns:\n True при успехе, False иначе.\n \"\"\"\n # Ключ в хранилище должен формироваться как: f\"{namespace}:{key}\"\n \n @self.mcp.tool()\n def get_by_namespace(namespace: str = \"default\") -> list[dict]:\n \"\"\"Возвращает все ключи из указанного namespace.\n \n Args:\n namespace: Пространство имён для чтения.\n \n Returns:\n Список словарей с метаданными всех ключей namespace.\n \"\"\"\n # Ищи ключи, начинающиеся на f\"{namespace}:\"\n```\n\n### 3. Реализовать сохранение данных\n\nСоздай файловое хранилище в формате JSON. Структура файла:\n\n```json\n{\n \"default:user_name\": {\n \"value\": \"Алексей\",\n \"timestamp\": \"2026-05-15T10:30:00\"\n },\n \"agent_1:session_token\": {\n \"value\": \"abc123xyz\", \n \"timestamp\": \"2026-05-15T10:31:00\"\n }\n}\n```\n\nКаждое значение должно храниться с метаданными (timestamp). Ключи формируются как `namespace:key` для namespace-based инструментов.\n\n### 4. Написать клиент для тестирования\n\nСоздай файл `memory_client.py`, который демонстрирует работу с сервером через MCP-клиент:\n\n```python\nfrom fastmcp import Client\nimport asyncio\n\nasync def main():\n # Подключение к MCP-серверу через stdio\n client = Client(\"python memory_server.py\")\n \n await client.connect()\n \n try:\n # Сохранение данных в namespace \"default\"\n result = await client.call_tool(\n \"save_with_namespace\", \n {\"key\": \"username\", \"value\": \"Алексей\", \"namespace\": \"default\"}\n )\n print(f\"Сохранено: {result}\")\n \n # Чтение данных\n result = await client.call_tool(\n \"get_by_namespace\", \n {\"namespace\": \"default\"}\n )\n print(f\"Данные namespace 'default':\")\n for item in result:\n print(f\" {item['key']}: {item['value']}\")\n \n # Поиск по паттерну\n keys = await client.call_tool(\"list_keys\", {\"pattern\": \"*name\"})\n print(f\"Ключи с 'name': {keys}\")\n \n finally:\n await client.close()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### 5. Добавить запуск сервера\n\nВ конце файла `memory_server.py` добавь блок запуска:\n\n```python\nif __name__ == \"__main__\":\n server = MemoryServer()\n server.mcp.run(\n transport=\"stdio\",\n show_banner=False,\n log_level='ERROR'\n )\n```\n\n---\n\n## Подсказки\n\n- **Импорты:** понадобятся `FastMCP`, `Client` из `fastmcp`; `json`, `datetime` стандартные библиотеки; `Path` из `pathlib`.\n- **Wildcard паттерн:** используй `fnmatch.fnmatch(key, pattern)` для фильтрации ключей.\n- **Структура данных:** каждый ключ в JSON должен хранить значение + timestamp. Namespace добавляется к ключу как префикс: `namespace:key`.\n- **Асинхронность:** клиент работает асинхронно (`async def`, `await`). Сервер запускается синхронно через `mcp.run()`.\n- **Безопасность:** валидируй ввод — ключи не должны содержать опасных символов (например, пути `/../`).\n\n---\n\n## Ожидаемый результат\n\nПри запуске клиента в консоли должен появиться вывод:\n\n```text\nСохранено: True\nДанные namespace 'default':\n username: Алексей\nКлючи с 'name': ['default:user_name']\n```\n\nСервер работает как отдельный процесс, клиент подключается к нему через stdio и вызывает инструменты удалённо.\n\n---\n\n## Критерии оценки\n\n| Критерий | Баллы |\n|----------|-------|\n| Сервер корректно зарегистрирован с FastMCP и минимум 6 инструментов (save, get, delete, list_keys, save_with_namespace, get_by_namespace) | 2 |\n| Инструменты правильно оформлены через декоратор @mcp.tool() с docstring и типизацией аргументов | 2 |\n| Используется транспорт stdio в mcp.run(), сервер запускается корректно | 1 |\n| Данные сохраняются в JSON-файл с метаданными (timestamp) | 2 |\n| Поддержка namespace для изоляции данных (ключи формируются как namespace:key) | 2 |\n| Реализован клиент для тестирования с примером вызова инструментов | 1 |\n| **Итого** | **10** |\n\n---\n\n## Ссылки\n\n- [FastMCP documentation](https://github.com/jlowin/fastmcp) — создание MCP-серверов и клиентов\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — спецификация протокола\n- [LangChain AI - MCP Integration](https://docs.langchain.com/oss/python/langchain/mcp) — интеграция MCP с LangChain",
|
||
"course": "698b49da77cb6d4d2e43ce78",
|
||
"lesson": {
|
||
"_id": "69b035ab2a32e307dd6e1fee",
|
||
"name": "Implementing Model Context Protocol in LangChain",
|
||
"date": "2026-03-10T15:30:00.000Z",
|
||
"id": "69b035ab2a32e307dd6e1fee"
|
||
},
|
||
"gradeType": "passfail",
|
||
"maxScore": 100,
|
||
"assignmentType": "individual",
|
||
"allowSubmissions": true,
|
||
"allowRevisions": false,
|
||
"creator": {
|
||
"sub": "8ae348ab-f32e-46c7-9960-8b7fdf0e4c0e",
|
||
"name": "Александр Примаков"
|
||
},
|
||
"teamGrades": [],
|
||
"created": "2026-05-04T18:44:57.314Z",
|
||
"id": "69f8e929da860fb4533faa2a"
|
||
}
|
||
} |