From b3e7e91b3b0e1ee357e5949bbef3aa9765db742a Mon Sep 17 00:00:00 2001 From: lonpatovaadelina Date: Fri, 29 May 2026 06:26:58 +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 | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 178 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 37deb04..d3d8117 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,179 @@ -# task-69f8e929-mcp-server-dlya-upravleni +# MCP‑Server for Agent Memory Management -Решения домашних заданий \ No newline at end of file +A lightweight **Model Context Protocol (MCP)** server that exposes a REST API for storing, retrieving, and deleting memory chunks for autonomous agents. +The server is built on **FastAPI** and uses **Qdrant** as a vector store for semantic search. +A small CLI client (`client.py`) demonstrates how to interact with the server. + +--- + +## Table of Contents + +- [Features](#features) +- [Architecture](#architecture) +- [Prerequisites](#prerequisites) +- [Installation](#installation) +- [Running the Server](#running-the-server) +- [Running the Client](#running-the-client) +- [Example Usage](#example-usage) +- [API Endpoints](#api-endpoints) +- [License](#license) + +--- + +## Features + +| Feature | Description | +|---------|-------------| +| **Add memory** | Store a key‑value pair in the vector store. | +| **Retrieve memory** | Query by key or semantic similarity. | +| **Delete memory** | Remove a memory entry by key. | +| **CORS enabled** | Works from any origin (useful for browser‑based agents). | +| **Rich console output** | Pretty tables and logs for debugging. | +| **FastAPI** | Modern, async, and fully typed. | +| **Qdrant** | Fast, scalable vector search. | + +--- + +## Architecture + +``` +┌───────────────────────┐ +│ Agent (client.py) │ +│ ├─ add_memory() │ +│ ├─ get_memory() │ +│ └─ delete_memory() │ +└────────────┬──────────┘ + │ HTTP + ▼ +┌───────────────────────┐ +│ MCP‑Server (server.py)│ +│ ├─ FastAPI endpoints │ +│ ├─ Qdrant vector store │ +│ └─ OpenAI embeddings │ +└───────────────────────┘ +``` + +--- + +## Prerequisites + +| Component | Minimum Version | Notes | +|-----------|-----------------|-------| +| Python | 3.10+ | Use a virtual environment. | +| Qdrant | 1.7+ | Run locally or use a hosted instance. | +| OpenAI API key | N/A | Required for embeddings. Set `OPENAI_API_KEY` env var. | + +--- + +## Installation + +```bash +# 1. Clone the repo +git clone https://github.com/yourorg/agent-mcp.git +cd agent-mcp + +# 2. Create a virtual environment +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate + +# 3. Install dependencies +pip install -r requirements.txt +``` + +`requirements.txt` contains: + +```text +fastapi +uvicorn +langchain +qdrant-client +openai +rich +requests +``` + +> **Tip:** If you don't have a Qdrant instance, start a local Docker container: + +```bash +docker run -p 6333:6333 qdrant/qdrant +``` + +--- + +## Running the Server + +```bash +# Activate the virtual environment if not already +source .venv/bin/activate + +# Start the FastAPI server +uvicorn server:app --host 0.0.0.0 --port 8000 --reload +``` + +The server will be available at `http://localhost:8000`. +CORS is enabled for all origins, so the client can run from any host. + +--- + +## Running the Client + +The client is a simple CLI wrapper around the MCP API. + +```bash +# Add a memory entry +python client.py add --server http://localhost:8000 --key "greeting" --value "Hello, world!" + +# Retrieve a memory entry +python client.py get --server http://localhost:8000 --key "greeting" + +# Delete a memory entry +python client.py delete --server http://localhost:8000 --key "greeting" +``` + +Run `python client.py --help` for full options. + +--- + +## Example Usage + +```bash +# 1. Start the server (in one terminal) +uvicorn server:app --host 0.0.0.0 --port 8000 --reload + +# 2. In another terminal, add a memory +python client.py add --server http://localhost:8000 --key "weather" --value "Sunny in San Francisco" + +# 3. Retrieve it +python client.py get --server http://localhost:8000 --key "weather" +# Output: +# ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ +# ┃ Key ┃ Value ┃ +# ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ +# │ weather │ Sunny in San Francisco │ +# └──────────┴──────────────────────────────────────┘ + +# 4. Delete it +python client.py delete --server http://localhost:8000 --key "weather" +# Output: +# Memory with key 'weather' deleted successfully. +``` + +--- + +## API Endpoints + +| Method | Path | Description | Request Body | Response | +|--------|------|-------------|--------------|----------| +| `POST` | `/memory/add` | Add a key‑value pair | `{"key": str, "value": str}` | `{"status": "ok", "id": str}` | +| `GET` | `/memory/get` | Retrieve by key | Query param `key` | `{"key": str, "value": str}` | +| `DELETE` | `/memory/delete` | Delete by key | Query param `key` | `{"status": "deleted"}` | + +All responses are JSON. Errors return HTTP status codes with a JSON body containing `detail`. + +--- + +## License + +MIT © 2026 Your Name + +--- \ No newline at end of file