# MCP Server with Namespace Support

## Overview
This project implements a minimal **MCP (Memory Control Protocol)** server using the `fastmcp` framework. The server exposes tools for storing, retrieving, deleting, and listing key-value pairs, with optional namespace support. Data is persisted to a JSON file with ISO 8601 timestamps.

## Features
- **Memory tools**: `save`, `get`, `delete`, `list_keys`.
- **Namespace tools**: `save_with_namespace`, `get_by_namespace`.
- **JSON persistence** with timestamp metadata.
- **Stdio transport** – run from the command line or embed in other processes.
- **Environment‑variable configuration** – the JSON data file path can be overridden via `MEMORY_DATA_FILE`.
- **Client demo** – run the script with `--client` to interactively test the tools.

## Requirements
```bash
pip install fastmcp pydantic python-dotenv
```

## Installation
```bash
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

# Install dependencies
touch requirements.txt  # If not already present
pip install -r requirements.txt
```

## Usage
### Run the server
```bash
python agent.py
```
The server will start and listen on STDIO. You can send JSON messages to it from another process.

### Run client demo
```bash
python agent.py --client
```
You will be prompted for commands like `save key value`, `get key`, `delete key`, `list_keys`, `save_with_namespace ns key value`, `get_by_namespace ns key`.

## Environment Variables
- `MEMORY_DATA_FILE` – Path to the JSON file used for persistence. Defaults to `memory.json` in the current directory.

## Example
```bash
$ python agent.py --client
Running client demo. Type 'exit' to quit.
Available tools: save, get, delete, list_keys, save_with_namespace, get_by_namespace
> save foo bar
Saved key 'foo'.
> get foo
bar (stored at 2024-10-01T12:34:56.789Z)
> delete foo
Deleted key 'foo'.
> list_keys
No keys
> exit
```

## License
MIT