MCP‑Server for Agent Memory Management

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.

Features
Architecture
Prerequisites
Installation
Running the Server
Running the Client
Example Usage
API Endpoints
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

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

fastapi
uvicorn
langchain
qdrant-client
openai
rich
requests

Tip: If you don't have a Qdrant instance, start a local Docker container:

docker run -p 6333:6333 qdrant/qdrant

Running the Server

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

# 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

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

5.0 KiB Raw Blame History Unescape Escape