159 lines
3.9 KiB
Markdown
159 lines
3.9 KiB
Markdown
# MCP Memory Server
|
||
|
||
A lightweight **Model Context Protocol (MCP)** server that exposes a simple JSON‑based memory store over HTTP.
|
||
It is built on top of the `fastmcp` framework and uses `pydantic` for data validation and `python-dotenv` to load configuration.
|
||
|
||
> **Why this project?**
|
||
> In multi‑agent systems agents often need a shared, persistent context. The MCP server provides a single source of truth that can be queried by any agent via the standardized protocol.
|
||
|
||
---
|
||
|
||
## 📦 Features
|
||
|
||
| Feature | Description |
|
||
|---------|-------------|
|
||
| **Namespaces** | Organise data into logical groups (`/namespace/key`). |
|
||
| **CRUD** | Create, read, update and delete keys. |
|
||
| **Search** | Find keys that match a pattern or contain a substring. |
|
||
| **Persistence** | All data is stored in a single JSON file on disk. |
|
||
| **Fast & Async** | Built with `fastmcp` – fast, type‑safe, async HTTP server. |
|
||
|
||
---
|
||
|
||
## 📋 Prerequisites
|
||
|
||
- Python 3.10+
|
||
- pip (or any other package manager)
|
||
|
||
> The project uses only pure‑Python dependencies; no external services are required.
|
||
|
||
---
|
||
|
||
## ⚙️ Installation
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://github.com/your-org/mcp-memory-server.git
|
||
cd mcp-memory-server
|
||
|
||
# Create a virtual environment (recommended)
|
||
python -m venv .venv
|
||
source .venv/bin/activate # On Windows: .\.venv\Scripts\activate
|
||
|
||
# Install dependencies
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
`requirements.txt` contains:
|
||
|
||
```text
|
||
fastmcp>=0.1.0
|
||
pydantic>=2.0
|
||
python-dotenv>=1.0
|
||
uvicorn>=0.30.0 # optional, for running with ASGI server
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Running the Server
|
||
|
||
The server reads configuration from a `.env` file (or environment variables).
|
||
Create a `.env` in the project root:
|
||
|
||
```dotenv
|
||
# .env
|
||
SERVER_HOST=127.0.0.1
|
||
SERVER_PORT=8000
|
||
DATA_FILE=data/memory.json # relative to project root
|
||
```
|
||
|
||
Start the server with:
|
||
|
||
```bash
|
||
python memory_server.py
|
||
```
|
||
|
||
The server will listen on `http://127.0.0.1:8000` and expose the following endpoints:
|
||
|
||
| Method | Path | Action |
|
||
|--------|------|--------|
|
||
| POST | `/namespace/key` | Create/Update a key |
|
||
| GET | `/namespace/key` | Retrieve a key |
|
||
| DELETE | `/namespace/key` | Delete a key |
|
||
| GET | `/search?query=...` | Search keys |
|
||
|
||
---
|
||
|
||
## 📚 Example Usage
|
||
|
||
Below is a minimal example of how an agent (or any HTTP client) can interact with the server.
|
||
|
||
```python
|
||
import httpx
|
||
from pathlib import Path
|
||
|
||
BASE_URL = "http://127.0.0.1:8000"
|
||
|
||
# 1️⃣ Create a key
|
||
payload = {"value": "Hello, MCP!"}
|
||
resp = httpx.post(f"{BASE_URL}/memory/greeting", json=payload)
|
||
print(resp.status_code) # 201 Created
|
||
|
||
# 2️⃣ Read the key
|
||
resp = httpx.get(f"{BASE_URL}/memory/greeting")
|
||
print(resp.json()) # {"value":"Hello, MCP!"}
|
||
|
||
# 3️⃣ Search for keys containing "greet"
|
||
resp = httpx.get(f"{BASE_URL}/search?query=greet")
|
||
print(resp.json()) # ["memory/greeting"]
|
||
|
||
# 4️⃣ Delete the key
|
||
resp = httpx.delete(f"{BASE_URL}/memory/greeting")
|
||
print(resp.status_code) # 204 No Content
|
||
```
|
||
|
||
> **Tip:** The `memory_client.py` module contains a thin wrapper around these HTTP calls, making it easier to integrate into your agents.
|
||
|
||
---
|
||
|
||
## 📁 Project Structure
|
||
|
||
```text
|
||
mcp-memory-server/
|
||
├── memory_server.py # FastMCP server implementation
|
||
├── memory_client.py # Helper client for interacting with the server
|
||
├── .env # Environment configuration (example)
|
||
├── requirements.txt # Dependencies
|
||
└── README.md # This file
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Testing
|
||
|
||
```bash
|
||
# Run unit tests (if any)
|
||
pytest tests/
|
||
```
|
||
|
||
> Currently there are no automated tests, but you can easily add them using `pytest` and `httpx`.
|
||
|
||
---
|
||
|
||
## 🤝 Contributing
|
||
|
||
Feel free to open issues or pull requests.
|
||
Please follow the standard GitHub workflow:
|
||
|
||
1. Fork the repo
|
||
2. Create a feature branch (`feature/your-feature`)
|
||
3. Commit & push
|
||
4. Open a Pull Request
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
MIT © 2026 Your Name / Organization
|
||
|
||
--- |