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

pip install fastmcp pydantic python-dotenv

Installation

# 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

python agent.py

The server will start and listen on STDIO. You can send JSON messages to it from another process.

Run client demo

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

$ 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