63 lines
1.9 KiB
Markdown
63 lines
1.9 KiB
Markdown
# 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 |