task-69f8e929-mcp-server-dlya-upravleni/README.md

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
• Prerequisites
• Installation
• Configuration
• Running the Server
• API Endpoints
  • POST /memory
  • GET /query
• Example Usage
• Testing with cURL
• 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

# 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:

pip install langchain[all]

---

Configuration

Edit solution.py and set:

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

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

{
  "text": "The quick brown fox jumps over the lazy dog.",
  "metadata": {
    "source": "example.txt",
    "timestamp": "2024-05-28T12:34:56Z"
  }
}

Response

{
  "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

[
  {
    "id": 42,
    "text": "...",
    "metadata": { ... },
    "score": 0.87
  },
  ...
]

---

Example Usage

Below is a quick Python script that demonstrates adding memory and querying it.

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:

python example.py

---

Testing with cURL

Add memory:

curl -X POST http://127.0.0.1:8000/memory \
     -H "Content-Type: application/json" \
     -d '{"text":"Hello world","metadata":{"source":"greeting"}}'

Query:

curl "http://127.0.0.1:8000/query?query=hello&top_k=2"

---

License

MIT © 2024

---