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

README.md

@@ -1,3 +1,214 @@
-# task-69f8e929-mcp-server-dlya-upravleni
+# MCP‑Server for Agent Memory Management
 
-Решения домашних заданий
+A lightweight FastAPI server that stores and retrieves memory snippets for an AI agent using **Qdrant** as a vector database and **OpenAI embeddings** to encode text.
+
+> **TL;DR** – Run the server, add memory items via `/memory`, query them with `/query`, and let your agent fetch relevant context automatically.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Running the Server](#running-the-server)
+- [API Endpoints](#api-endpoints)
+  - `POST /memory`
+  - `GET /query`
+- [Example Usage](#example-usage)
+- [Testing with cURL](#testing-with-curl)
+- [License](#license)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Vector Search** | Stores embeddings in Qdrant and performs similarity search. |
+| **OpenAI Embeddings** | Uses `text-embedding-ada-002` (or any OpenAI model) to encode text. |
+| **FastAPI** | Simple, async API with automatic docs (`/docs`). |
+| **Conversation Buffer Memory** | Optional integration with LangChain for conversational context. |
+
+---
+
+## Prerequisites
+
+| Component | Minimum Version | How to Install |
+|-----------|-----------------|----------------|
+| Python | 3.10+ | `python -m venv .venv && source .venv/bin/activate` |
+| Qdrant | 1.x (Docker) | `docker run -p 6333:6333 qdrant/qdrant` |
+| OpenAI API Key | – | Sign up at https://platform.openai.com and copy your key. |
+
+> **Tip:** The server uses the default Qdrant port `6333`. If you change it, update `QDRANT_PORT` in `solution.py`.
+
+---
+
+## Installation
+
+```bash
+# 1️⃣ Clone the repo (or download solution.py)
+git clone https://github.com/your-username/mcp-agent-memory.git
+cd mcp-agent-memory
+
+# 2️⃣ Create a virtual environment and activate it
+python -m venv .venv
+source .venv/bin/activate   # On Windows: .venv\Scripts\activate
+
+# 3️⃣ Install dependencies
+pip install --upgrade pip
+pip install fastapi uvicorn httpx qdrant-client langchain openai pydantic
+```
+
+> **Optional** – If you want to use the built‑in LangChain memory, also install:
+> ```bash
+> pip install langchain[all]
+> ```
+
+---
+
+## Configuration
+
+Edit `solution.py` and set:
+
+```python
+OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"   # <-- Replace with your key
+QDRANT_HOST = "localhost"
+QDRANT_PORT = 6333
+COLLECTION_NAME = "agent_memory"
+```
+
+If you run Qdrant on a different host/port, adjust `QDRANT_HOST` and `QDRANT_PORT`.
+
+---
+
+## Running the Server
+
+```bash
+uvicorn solution:app --reload
+```
+
+- The server will start at `http://127.0.0.1:8000`.
+- OpenAPI docs are available at `http://127.0.0.1:8000/docs`.
+
+> **Note:** The first request to `/memory` will create the Qdrant collection automatically.
+
+---
+
+## API Endpoints
+
+| Method | Path   | Description |
+|--------|--------|-------------|
+| `POST` | `/memory` | Add a new memory snippet. |
+| `GET`  | `/query`  | Retrieve top‑k similar snippets for a query string. |
+
+### POST /memory
+
+```json
+{
+  "text": "The quick brown fox jumps over the lazy dog.",
+  "metadata": {
+    "source": "example.txt",
+    "timestamp": "2024-05-28T12:34:56Z"
+  }
+}
+```
+
+**Response**
+
+```json
+{
+  "id": 42,
+  "text": "...",
+  "metadata": { ... }
+}
+```
+
+### GET /query
+
+Query parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query`   | str  | –       | Search string. |
+| `top_k`   | int  | 5       | Number of results to return. |
+
+**Example**
+
+```
+GET /query?query=quick%20fox&top_k=3
+```
+
+**Response**
+
+```json
+[
+  {
+    "id": 42,
+    "text": "...",
+    "metadata": { ... },
+    "score": 0.87
+  },
+  ...
+]
+```
+
+---
+
+## Example Usage
+
+Below is a quick Python script that demonstrates adding memory and querying it.
+
+```python
+import httpx
+
+BASE_URL = "http://127.0.0.1:8000"
+
+# 1️⃣ Add a memory snippet
+payload = {
+    "text": "The quick brown fox jumps over the lazy dog.",
+    "metadata": {"source": "example.txt"}
+}
+resp = httpx.post(f"{BASE_URL}/memory", json=payload)
+print("Added:", resp.json())
+
+# 2️⃣ Query for similar snippets
+params = {"query": "quick fox", "top_k": 3}
+resp = httpx.get(f"{BASE_URL}/query", params=params)
+print("Query results:")
+for item in resp.json():
+    print(item["text"], "(score:", item["score"] + ")")
+```
+
+Run the script after starting the server:
+
+```bash
+python example.py
+```
+
+---
+
+## Testing with cURL
+
+Add memory:
+
+```bash
+curl -X POST http://127.0.0.1:8000/memory \
+     -H "Content-Type: application/json" \
+     -d '{"text":"Hello world","metadata":{"source":"greeting"}}'
+```
+
+Query:
+
+```bash
+curl "http://127.0.0.1:8000/query?query=hello&top_k=2"
+```
+
+---
+
+## License
+
+MIT © 2024
+
+---