Add README.md

2026-06-03 12:00:18 +00:00
commit 5f286f42b0
1 changed files with 63 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 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