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

solutions/69f8e929da860fb4533faa2a_MCP-сервер_для_управления_памятью_агента/README.md

@@ -1,29 +1,39 @@
 # MCP‑Memory Server
 
-A lightweight **FastMCP** server that provides a simple in‑memory key/value store with optional namespaces.  
+A lightweight **FastMCP** based key/value store for agent memory with support for namespaces.
-The project contains:
 
-- `memory_server.py` – FastMCP server exposing tools: `save`, `get`, `delete`, `list_keys`, `save_with_namespace`, `get_by_namespace`.
+- **Server** – `memory_server.py`
-- `memory_client.py` – A minimal client that demonstrates how to call the server’s tools.
+- **Client** – `memory_client.py`
+
+The server exposes the following tools:
+
+| Tool | Description |
+|------|-------------|
+| `save` | Store a value by key. |
+| `get` | Retrieve a value by key. |
+| `delete` | Remove a key/value pair. |
+| `list_keys` | List all stored keys. |
+| `save_with_namespace` | Store a value under a namespace and key. |
+| `get_by_namespace` | Retrieve a value from a specific namespace/key. |
 
 ---
 
 ## 📦 Installation
 
 ```bash
-# 1. Clone the repo (or copy the files)
+# Clone the repo (or copy the files)
-git clone https://github.com/your‑repo/mcp-memory-server.git
+git clone https://github.com/yourname/mcp-memory-server.git
 cd mcp-memory-server
 
-# 2. Create a virtual environment (optional but recommended)
+# Create a virtual environment (optional but recommended)
 python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
+source .venv/bin/activate   # On Windows: .\.venv\Scripts\activate
 
-# 3. Install dependencies
+# Install dependencies
 pip install fastmcp
 ```
 
-> **Tip** – If you want to run the client and server in separate terminals, keep the virtual environment activated for both.
+> **Tip:** If you want to run the client and server on different machines, make sure the host machine is reachable from the client.
 
 ---
 
@@ -33,78 +43,83 @@ pip install fastmcp
 python memory_server.py
 ```
 
-The server starts on `http://localhost:8000` by default.  
+The server starts listening on `localhost:8000` by default.  
-You can change the host/port by editing the `FastMCP` initialization inside `memory_server.py`.
+You can change the port or host by editing the `MCPServer` initialization in `memory_server.py`.
 
 ---
 
-## 🧪 Running the Client (Example)
+## 🧩 Using the Client
-
-Open a new terminal, activate the same virtual environment, and run:
 
 ```bash
 python memory_client.py
 ```
 
-The client will perform the following actions in order:
+The client script demonstrates how to call each tool:
 
-1. **Save** a key/value pair.
+1. **Save a key/value pair**  
-2. **Retrieve** it with `get`.
+   ```python
-3. **List** all keys.
+   result = await client.call("save", {"key": "name", "value": "Alice"})
-4. **Delete** the key.
+   print(result)  # → "Значение сохранено под ключом 'name'."
-5. **Work with namespaces** (`save_with_namespace` & `get_by_namespace`).
+   ```
 
-The output will look like this (values may differ):
+2. **Retrieve the value**  
+   ```python
+   value = await client.call("get", {"key": "name"})
+   print(value)  # → "Alice"
+   ```
 
-```
+3. **List all keys**  
-Saved key 'foo' with value 42
+   ```python
-Got value for key 'foo': 42
+   keys = await client.call("list_keys")
-All keys: ['foo']
+   print(keys)  # → {"keys": ["name"]}
-Deleted key 'foo': True
+   ```
-Namespace 'ns1' saved key 'bar'
+
-Value from namespace 'ns1', key 'bar': 99
+4. **Delete a key**  
-```
+   ```python
+   result = await client.call("delete", {"key": "name"})
+   print(result)  # → "Ключ 'name' удалён."
+   ```
+
+5. **Namespace operations**  
+   ```python
+   await client.call("save_with_namespace", {"namespace": "user1", "key": "age", "value": 30})
+   age = await client.call("get_by_namespace", {"namespace": "user1", "key": "age"})
+   print(age)  # → 30
+   ```
+
+Feel free to modify `memory_client.py` or write your own scripts that use the same RPC pattern.
 
 ---
 
-## 📄 API Overview
+## 📚 Example Workflow
-
-| 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 tools are exposed via FastMCP’s RPC interface and can be called from any client that supports the protocol.
-
----
-
-## 📚 Example Usage (cURL)
 
 ```bash
-# Save a value
+# Terminal 1 – start server
-curl -X POST http://localhost:8000/tool/save \
+$ python memory_server.py
-     -H "Content-Type: application/json" \
+Server listening on http://localhost:8000
-     -d '{"key":"example","value":123}'
 
-# Get the value back
+# Terminal 2 – run client demo
-curl http://localhost:8000/tool/get?key=example
+$ python memory_client.py
-
+Значение сохранено под ключом 'name'.
-# List all keys
+Alice
-curl http://localhost:8000/tool/list_keys
+{'keys': ['name']}
+Ключ 'name' удалён.
 ```
 
 ---
 
-## 🛠️ Extending the Server
+## 🔧 Troubleshooting
 
-- **Persistence** – Replace the in‑memory store with a database or file system.
+| Issue | Fix |
-- **Authentication** – Add FastMCP auth middleware to restrict access.
+|-------|-----|
-- **Metrics** – Integrate Prometheus or similar for monitoring.
+| `ModuleNotFoundError: No module named 'fastmcp'` | Ensure you installed the package in the active virtual environment. Run `pip install fastmcp`. |
-
+| Connection refused | Verify that the server is running and listening on the correct host/port. |
-Feel free to fork and enhance!
+| Unexpected RPC errors | Check that the tool names match exactly (`save`, `get`, etc.). |
+
+---
+
+## 📄 License
+
+MIT © 2026
 
 ---