MCP-сервер для управления памятью агента: README.md
This commit is contained in:
+67
-117
@@ -1,160 +1,110 @@
|
||||
# MCP‑Memory Server
|
||||
|
||||
A lightweight **FastMCP** server that exposes a simple key/value store with optional namespaces.
|
||||
The project contains two scripts:
|
||||
A lightweight **FastMCP** server that provides a simple in‑memory key/value store with optional namespaces.
|
||||
The project contains:
|
||||
|
||||
| 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.
|
||||
- `memory_server.py` – FastMCP server exposing tools: `save`, `get`, `delete`, `list_keys`, `save_with_namespace`, `get_by_namespace`.
|
||||
- `memory_client.py` – A minimal client that demonstrates how to call the server’s tools.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
## 📦 Installation
|
||||
|
||||
```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
|
||||
# 1. Clone the repo (or copy the files)
|
||||
git clone https://github.com/your‑repo/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
|
||||
|
||||
# 2. Create a virtual environment (optional but recommended)
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
|
||||
# 3. Install dependencies
|
||||
pip install fastmcp
|
||||
```
|
||||
|
||||
> **Tip** – If you prefer not to create a virtual environment, just run `pip install fastmcp pydantic`.
|
||||
> **Tip** – If you want to run the client and server in separate terminals, keep the virtual environment activated for both.
|
||||
|
||||
---
|
||||
|
||||
## Running the Server
|
||||
## 🚀 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.
|
||||
The server starts on `http://localhost:8000` by default.
|
||||
You can change the host/port by editing the `FastMCP` initialization inside `memory_server.py`.
|
||||
|
||||
---
|
||||
|
||||
## Using the Client
|
||||
## 🧪 Running the Client (Example)
|
||||
|
||||
The client demonstrates how to call each RPC method.
|
||||
Open a new terminal, activate the same virtual environment, and run:
|
||||
|
||||
```bash
|
||||
python memory_client.py
|
||||
```
|
||||
|
||||
It will:
|
||||
The client will perform the following actions in order:
|
||||
|
||||
1. Save two keys (`foo`, `bar`).
|
||||
2. Retrieve them.
|
||||
3. Delete one key.
|
||||
4. List remaining keys.
|
||||
5. Work with a namespace called `"demo"`.
|
||||
1. **Save** a key/value pair.
|
||||
2. **Retrieve** it with `get`.
|
||||
3. **List** all keys.
|
||||
4. **Delete** the key.
|
||||
5. **Work with namespaces** (`save_with_namespace` & `get_by_namespace`).
|
||||
|
||||
All interactions are printed to the console.
|
||||
The output will look like this (values may differ):
|
||||
|
||||
---
|
||||
|
||||
## 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())
|
||||
```
|
||||
Saved key 'foo' with value 42
|
||||
Got value for key 'foo': 42
|
||||
All keys: ['foo']
|
||||
Deleted key 'foo': True
|
||||
Namespace 'ns1' saved key 'bar'
|
||||
Value from namespace 'ns1', key 'bar': 99
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
## 📄 API Overview
|
||||
|
||||
| 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 }` |
|
||||
| Tool | Parameters | Returns |
|
||||
|------|------------|---------|
|
||||
| `save(key, value)` | `key: str`, `value: Any` | `None` |
|
||||
| `get(key)` | `key: str` | `Any | None` |
|
||||
| `delete(key)` | `key: str` | `bool` |
|
||||
| `list_keys()` | – | `List[str]` |
|
||||
| `save_with_namespace(namespace, key, value)` | `namespace: str`, `key: str`, `value: Any` | `None` |
|
||||
| `get_by_namespace(namespace, key)` | `namespace: str`, `key: str` | `Any | None` |
|
||||
|
||||
All RPC calls are asynchronous and return a JSON‑serialisable dictionary.
|
||||
All tools are exposed via FastMCP’s RPC interface and can be called from any client that supports the protocol.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
## 📚 Example Usage (cURL)
|
||||
|
||||
MIT © 2026 Your Name
|
||||
```bash
|
||||
# Save a value
|
||||
curl -X POST http://localhost:8000/tool/save \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"key":"example","value":123}'
|
||||
|
||||
# Get the value back
|
||||
curl http://localhost:8000/tool/get?key=example
|
||||
|
||||
# List all keys
|
||||
curl http://localhost:8000/tool/list_keys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Extending the Server
|
||||
|
||||
- **Persistence** – Replace the in‑memory store with a database or file system.
|
||||
- **Authentication** – Add FastMCP auth middleware to restrict access.
|
||||
- **Metrics** – Integrate Prometheus or similar for monitoring.
|
||||
|
||||
Feel free to fork and enhance!
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user