From f39b3a9c8fab086be0fb2621b4a14fdc57534228 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D1=80=D0=B8=D1=8F=20=D0=91=D0=B5=D1=80=D0=B4?= =?UTF-8?q?=D0=BD=D0=B8=D0=BA=D0=BE=D0=B2=D0=B0?= Date: Thu, 28 May 2026 09:16:52 +0000 Subject: [PATCH] =?UTF-8?q?MCP-=D1=81=D0=B5=D1=80=D0=B2=D0=B5=D1=80=20?= =?UTF-8?q?=D0=B4=D0=BB=D1=8F=20=D1=83=D0=BF=D1=80=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D1=8F=20=D0=BF=D0=B0=D0=BC=D1=8F=D1=82=D1=8C=D1=8E?= =?UTF-8?q?=20=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D0=B0:=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 213 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 37deb04..63c4d09 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,214 @@ -# task-69f8e929-mcp-server-dlya-upravleni +# MCP‑Server for Agent Memory Management -Решения домашних заданий \ No newline at end of file +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 + +--- \ No newline at end of file