MCP-сервер для управления памятью агента: README.md
This commit is contained in:
+66
-116
@@ -1,160 +1,110 @@
|
|||||||
# MCP‑Memory Server
|
# MCP‑Memory Server
|
||||||
|
|
||||||
A lightweight **FastMCP** server that exposes a simple key/value store with optional namespaces.
|
A lightweight **FastMCP** server that provides a simple in‑memory key/value store with optional namespaces.
|
||||||
The project contains two scripts:
|
The project contains:
|
||||||
|
|
||||||
| File | Purpose |
|
- `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.
|
||||||
| `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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Table of Contents
|
## 📦 Installation
|
||||||
|
|
||||||
- [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:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
fastmcp==0.1.0 # or the latest release on PyPI
|
# 1. Clone the repo (or copy the files)
|
||||||
pydantic==2.6.4 # for request/response validation
|
git clone https://github.com/your‑repo/mcp-memory-server.git
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
Clone the repository and install dependencies:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/yourname/mcp-memory-server.git
|
|
||||||
cd mcp-memory-server
|
cd mcp-memory-server
|
||||||
python -m venv .venv # optional but recommended
|
|
||||||
|
# 2. Create a virtual environment (optional but recommended)
|
||||||
|
python -m venv .venv
|
||||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||||
pip install -r requirements.txt # or pip install fastmcp pydantic
|
|
||||||
|
# 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
|
```bash
|
||||||
python memory_server.py
|
python memory_server.py
|
||||||
```
|
```
|
||||||
|
|
||||||
The server listens on the default MCP port (`5000`).
|
The server starts on `http://localhost:8000` by default.
|
||||||
You should see output similar to:
|
You can change the host/port by editing the `FastMCP` initialization inside `memory_server.py`.
|
||||||
|
|
||||||
```
|
|
||||||
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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
python memory_client.py
|
python memory_client.py
|
||||||
```
|
```
|
||||||
|
|
||||||
It will:
|
The client will perform the following actions in order:
|
||||||
|
|
||||||
1. Save two keys (`foo`, `bar`).
|
1. **Save** a key/value pair.
|
||||||
2. Retrieve them.
|
2. **Retrieve** it with `get`.
|
||||||
3. Delete one key.
|
3. **List** all keys.
|
||||||
4. List remaining keys.
|
4. **Delete** the key.
|
||||||
5. Work with a namespace called `"demo"`.
|
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):
|
||||||
|
|
||||||
---
|
```
|
||||||
|
Saved key 'foo' with value 42
|
||||||
## Example Usage
|
Got value for key 'foo': 42
|
||||||
|
All keys: ['foo']
|
||||||
Below is a quick manual example using the client as a reference:
|
Deleted key 'foo': True
|
||||||
|
Namespace 'ns1' saved key 'bar'
|
||||||
```python
|
Value from namespace 'ns1', key 'bar': 99
|
||||||
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())
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## API Reference
|
## 📄 API Overview
|
||||||
|
|
||||||
| Method | Request Schema | Response |
|
| Tool | Parameters | Returns |
|
||||||
|--------|----------------|----------|
|
|------|------------|---------|
|
||||||
| `save` | `{ key: str, value: str }` | `None` |
|
| `save(key, value)` | `key: str`, `value: Any` | `None` |
|
||||||
| `get` | `{ key: str }` | `{ value: any }` |
|
| `get(key)` | `key: str` | `Any | None` |
|
||||||
| `delete` | `{ key: str }` | `None` |
|
| `delete(key)` | `key: str` | `bool` |
|
||||||
| `list_keys` | `None` | `{ keys: List[str] }` |
|
| `list_keys()` | – | `List[str]` |
|
||||||
| `save_with_namespace` | `{ namespace: str, key: str, value: str }` | `None` |
|
| `save_with_namespace(namespace, key, value)` | `namespace: str`, `key: str`, `value: Any` | `None` |
|
||||||
| `get_by_namespace` | `{ namespace: str, key: str }` | `{ value: any }` |
|
| `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