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

2026-05-27 07:45:37 +00:00
parent 4865f86103
commit 901a9d97dc
1 changed files with 116 additions and 0 deletions
@@ -0,0 +1,116 @@
+# MCP‑Memory Server
+
+A lightweight **Model Context Protocol (MCP)** server that exposes a simple key/value memory store for agents and other clients.  
+The project contains two scripts:
+
+| File | Purpose |
+|------|---------|
+| `memory_server.py` | Runs the MCP server, exposing *set*, *get* and *delete* operations on a JSON‑backed storage. |
+| `memory_client.py` | Demonstrates how to connect to the server and use its tools from a client script. |
+
+> **Why MCP?**  
+> MCP is a lightweight protocol for exchanging structured data between agents, services or CLI utilities. By running this server as a separate process we enable distributed multi‑agent systems to share state without tight coupling.
+
+---
+
+## 📦 Installation
+
+```bash
+# Create and activate a virtual environment (optional but recommended)
+python -m venv .venv
+source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
+
+# Install the required packages
+pip install fastmcp pydantic python-dotenv
+```
+
+> **Tip:**  
+> `fastmcp` is a minimal framework for building MCP servers and clients.  
+> `pydantic` is used internally by `fastmcp` for data validation.
+
+---
+
+## 🚀 Running the Server
+
+```bash
+python memory_server.py
+```
+
+The server starts on the default port **8000** (you can change it in the script).  
+It will create a file called `memory_data.json` in the current directory to persist data between restarts.
+
+### Available Tools
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `set` | `key: str`, `value: Any` | Stores a value under the given key. |
+| `get` | `key: str` | Retrieves the value for the key (or `null`). |
+| `delete` | `key: str` | Removes the key from storage. |
+
+---
+
+## 🧪 Running the Client
+
+```bash
+python memory_client.py
+```
+
+The client script demonstrates:
+
+1. Setting a value (`foo = "bar"`).  
+2. Getting that value back.  
+3. Deleting the key and verifying it’s gone.
+
+You can also use the client interactively by editing `memory_client.py` or by sending raw MCP messages via another tool (e.g., `curl`, Postman, or a custom agent).
+
+---
+
+## 📄 Example Usage
+
+```python
+# memory_client.py snippet
+
+from fastmcp import FastMCPClient
+
+client = FastMCPClient("Memory-Server", host="localhost", port=8000)
+
+# Set a key/value pair
+client.call_tool("set", {"key": "greeting", "value": "Hello, world!"})
+
+# Retrieve the value
+response = client.call_tool("get", {"key": "greeting"})
+print(response)  # Output: Hello, world!
+
+# Delete the key
+client.call_tool("delete", {"key": "greeting"})
+
+# Verify deletion
+assert client.call_tool("get", {"key": "greeting"}) is None
+```
+
+Feel free to integrate this server into your own agent framework or use it as a standalone memory service.
+
+---
+
+## 📁 Project Structure
+
+```
+.
+├── memory_server.py   # MCP server implementation
+├── memory_client.py   # Example client script
+└── memory_data.json   # (generated) persistent storage
+```
+
+---
+
+## 🔧 Customization
+
+- **Port** – change the `port` argument in `FastMCP("Memory-Server", port=8000)` inside `memory_server.py`.  
+- **Storage Path** – modify `self.storage_path = Path("./memory_data.json")` to point elsewhere.  
+- **Additional Tools** – add new methods decorated with `@self.mcp.tool(...)` following the pattern in the script.
+
+---
+
+## 📜 License
+
+This project is released under the MIT license. Feel free to fork, extend or use it in your own projects.