# MCP‑Memory Server

A lightweight **FastMCP** server that provides a simple in‑memory key/value store with optional namespaces.  
The project contains:

- `memory_server.py` – FastMCP server exposing tools: `save`, `get`, `delete`, `list_keys`, `save_with_namespace`, `get_by_namespace`.
- `memory_client.py` – A minimal client that demonstrates how to call the server’s tools.

---

## 📦 Installation

```bash
# 1. Clone the repo (or copy the files)
git clone https://github.com/your‑repo/mcp-memory-server.git
cd mcp-memory-server

# 2. Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install fastmcp
```

> **Tip** – If you want to run the client and server in separate terminals, keep the virtual environment activated for both.

---

## 🚀 Running the Server

```bash
python memory_server.py
```

The server starts on `http://localhost:8000` by default.  
You can change the host/port by editing the `FastMCP` initialization inside `memory_server.py`.

---

## 🧪 Running the Client (Example)

Open a new terminal, activate the same virtual environment, and run:

```bash
python memory_client.py
```

The client will perform the following actions in order:

1. **Save** a key/value pair.
2. **Retrieve** it with `get`.
3. **List** all keys.
4. **Delete** the key.
5. **Work with namespaces** (`save_with_namespace` & `get_by_namespace`).

The output will look like this (values may differ):

```
Saved key 'foo' with value 42
Got value for key 'foo': 42
All keys: ['foo']
Deleted key 'foo': True
Namespace 'ns1' saved key 'bar'
Value from namespace 'ns1', key 'bar': 99
```

---

## 📄 API Overview

| Tool | Parameters | Returns |
|------|------------|---------|
| `save(key, value)` | `key: str`, `value: Any` | `None` |
| `get(key)` | `key: str` | `Any | None` |
| `delete(key)` | `key: str` | `bool` |
| `list_keys()` | – | `List[str]` |
| `save_with_namespace(namespace, key, value)` | `namespace: str`, `key: str`, `value: Any` | `None` |
| `get_by_namespace(namespace, key)` | `namespace: str`, `key: str` | `Any | None` |

All tools are exposed via FastMCP’s RPC interface and can be called from any client that supports the protocol.

---

## 📚 Example Usage (cURL)

```bash
# Save a value
curl -X POST http://localhost:8000/tool/save \
     -H "Content-Type: application/json" \
     -d '{"key":"example","value":123}'

# Get the value back
curl http://localhost:8000/tool/get?key=example

# List all keys
curl http://localhost:8000/tool/list_keys
```

---

## 🛠️ Extending the Server

- **Persistence** – Replace the in‑memory store with a database or file system.
- **Authentication** – Add FastMCP auth middleware to restrict access.
- **Metrics** – Integrate Prometheus or similar for monitoring.

Feel free to fork and enhance!

---