MCP‑сервер для управления памятью агента: README.md

2026-05-26 09:28:24 +00:00
parent 56505ef428
commit 3e8375cf56
1 changed files with 138 additions and 0 deletions
@@ -0,0 +1,138 @@
+# MCP Memory Server
+
+A lightweight **Model Context Protocol (MCP)** server that exposes a simple key‑value store to other agents or CLI tools.  
+The server is built with `fastmcp` and uses a JSON file as persistent storage.
+
+---
+
+## Table of Contents
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Running the Server](#running-the-server)
+- [Running the Client](#running-the-client)
+- [Example Usage](#example-usage)
+- [Project Structure](#project-structure)
+
+---
+
+## Features
+| Operation | Description |
+|-----------|-------------|
+| `set` | Store a value under a key (optionally in a namespace). |
+| `get` | Retrieve a stored value. |
+| `delete` | Remove a key from storage. |
+| `keys` | List all keys, optionally filtered by pattern or namespace. |
+
+All operations are performed through the MCP protocol over **STDIO**.
+
+---
+
+## Prerequisites
+- Python 3.10+
+- pip
+
+---
+
+## Installation
+
+```bash
+# Clone the repository (or copy the files)
+git clone https://github.com/your-org/mcp-memory-server.git
+cd mcp-memory-server
+
+# Create a virtual environment (optional but recommended)
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install fastmcp pydantic python-dotenv
+```
+
+> **Tip:** The `memory_server.py` and `memory_client.py` files are self‑contained; no additional packages are required beyond those listed.
+
+---
+
+## Running the Server
+
+```bash
+python memory_server.py
+```
+
+The server starts listening on STDIO.  
+It will create (or load) a file named `memory_data.json` in the current directory to persist data.
+
+**Server output example**
+
+```
+[Memory-Server] Listening on stdin/stdout...
+```
+
+---
+
+## Running the Client
+
+```bash
+python memory_client.py
+```
+
+The client demonstrates basic usage: setting, getting, listing keys, and deleting a key.  
+It communicates with the server over STDIO using `fastmcp`.
+
+**Client output example**
+
+```
+Set key 'foo' to value 'bar'
+Get key 'foo': bar
+All keys: ['foo']
+Deleted key 'foo'
+All keys after deletion: []
+```
+
+---
+
+## Example Usage
+
+Below is a quick script that shows how you can interact with the server programmatically.
+
+```python
+from fastmcp import FastMCPClient
+import json
+
+# Connect to the running MCP server (STDIO)
+client = FastMCPClient("Memory-Server")
+
+# Set a key
+client.send({"action": "set", "key": "greeting", "value": "Hello, world!"})
+
+# Get the key
+response = client.receive()
+print(response)  # {'status': 'ok', 'value': 'Hello, world!'}
+
+# List all keys
+client.send({"action": "keys"})
+print(client.receive())  # {'status': 'ok', 'keys': ['greeting']}
+
+# Delete the key
+client.send({"action": "delete", "key": "greeting"})
+print(client.receive())  # {'status': 'ok'}
+```
+
+> **Note:** The client and server communicate via JSON messages.  
+> Each message must contain an `"action"` field that matches one of the supported operations.
+
+---
+
+## Project Structure
+
+```
+mcp-memory-server/
+├── memory_server.py   # MCP server implementation
+├── memory_client.py   # Demo client script
+└── README.md          # This file
+```
+
+- `memory_server.py` – defines the `MemoryServer` class and starts the MCP service.
+- `memory_client.py` – simple CLI client that exercises all operations.
+
+Feel free to extend the server with authentication, more sophisticated storage backends, or additional MCP actions. Happy hacking!