# 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

---