# MCP‑Memory Server

A lightweight **FastMCP** server that exposes a simple key/value store with optional namespaces.
The project contains two scripts:

| File | Purpose |
|------|---------|
| `memory_server.py` | FastMCP RPC server implementing `save`, `get`, `delete`, `list_keys`, `save_with_namespace`, `get_by_namespace`. |
| `memory_client.py` | Example client that demonstrates how to call the RPC methods. |

> **TL;DR** – Run the server, then use the client (or any MCP‑compatible tool) to store and retrieve data.

---

## Table of Contents

- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Server](#running-the-server)
- [Using the Client](#using-the-client)
- [Example Usage](#example-usage)
- [API Reference](#api-reference)
- [License](#license)

---

## Features

| RPC | Description |
|-----|-------------|
| `save` | Store a value under a key. |
| `get` | Retrieve the value for a key. |
| `delete` | Remove a key/value pair. |
| `list_keys` | List all keys in the store. |
| `save_with_namespace` | Store a value inside a namespace. |
| `get_by_namespace` | Retrieve a value from a namespace. |

All data is kept **in‑memory** – it disappears when the server restarts.

---

## Prerequisites

- Python 3.10+
- `pip` (or any other package manager)

The project uses only two external libraries:

```bash
fastmcp==0.1.0   # or the latest release on PyPI
pydantic==2.6.4  # for request/response validation
```

---

## Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/yourname/mcp-memory-server.git
cd mcp-memory-server
python -m venv .venv          # optional but recommended
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt   # or pip install fastmcp pydantic
```

> **Tip** – If you prefer not to create a virtual environment, just run `pip install fastmcp pydantic`.

---

## Running the Server

```bash
python memory_server.py
```

The server listens on the default MCP port (`5000`).  
You should see output similar to:

```
INFO:root:FastMCP server started at 127.0.0.1:5000
```

If you need a different host/port, edit `memory_server.py` or set environment variables before launching.

---

## Using the Client

The client demonstrates how to call each RPC method.

```bash
python memory_client.py
```

It will:

1. Save two keys (`foo`, `bar`).
2. Retrieve them.
3. Delete one key.
4. List remaining keys.
5. Work with a namespace called `"demo"`.

All interactions are printed to the console.

---

## Example Usage

Below is a quick manual example using the client as a reference:

```python
from fastmcp import FastMCPClient
import asyncio

async def main():
    async with FastMCPClient("127.0.0.1", 5000) as client:
        # Save a key/value pair
        await client.rpc("save", {"key": "greeting", "value": "Hello, world!"})

        # Retrieve it
        result = await client.rpc("get", {"key": "greeting"})
        print(result)   # {'value': 'Hello, world!'}

        # List all keys
        keys = await client.rpc("list_keys")
        print(keys)     # {'keys': ['greeting']}

        # Work with namespace
        await client.rpc("save_with_namespace", {"namespace": "ns1", "key": "x", "value": 42})
        ns_val = await client.rpc("get_by_namespace", {"namespace": "ns1", "key": "x"})
        print(ns_val)   # {'value': 42}

asyncio.run(main())
```

---

## API Reference

| Method | Request Schema | Response |
|--------|----------------|----------|
| `save` | `{ key: str, value: str }` | `None` |
| `get` | `{ key: str }` | `{ value: any }` |
| `delete` | `{ key: str }` | `None` |
| `list_keys` | `None` | `{ keys: List[str] }` |
| `save_with_namespace` | `{ namespace: str, key: str, value: str }` | `None` |
| `get_by_namespace` | `{ namespace: str, key: str }` | `{ value: any }` |

All RPC calls are asynchronous and return a JSON‑serialisable dictionary.

---

## License

MIT © 2026 Your Name

---