diff --git a/solutions/69f8e929da860fb4533faa2a_MCP-сервер_для_управления_памятью_агента/README.md b/solutions/69f8e929da860fb4533faa2a_MCP-сервер_для_управления_памятью_агента/README.md index b6934a6..b023400 100644 --- a/solutions/69f8e929da860fb4533faa2a_MCP-сервер_для_управления_памятью_агента/README.md +++ b/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. -The project contains: +A lightweight **FastMCP** based key/value store for agent memory with support for namespaces. -- `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. +- **Server** – `memory_server.py` +- **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) -git clone https://github.com/your‑repo/mcp-memory-server.git +# Clone the repo (or copy the files) +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. -You can change the host/port by editing the `FastMCP` initialization inside `memory_server.py`. +The server starts listening on `localhost:8000` by default. +You can change the port or host by editing the `MCPServer` initialization in `memory_server.py`. --- -## 🧪 Running the Client (Example) - -Open a new terminal, activate the same virtual environment, and run: +## 🧩 Using the Client ```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. -2. **Retrieve** it with `get`. -3. **List** all keys. -4. **Delete** the key. -5. **Work with namespaces** (`save_with_namespace` & `get_by_namespace`). +1. **Save a key/value pair** + ```python + result = await client.call("save", {"key": "name", "value": "Alice"}) + print(result) # → "Значение сохранено под ключом 'name'." + ``` -The output will look like this (values may differ): +2. **Retrieve the value** + ```python + value = await client.call("get", {"key": "name"}) + print(value) # → "Alice" + ``` -``` -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 -``` +3. **List all keys** + ```python + keys = await client.call("list_keys") + print(keys) # → {"keys": ["name"]} + ``` + +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 - -| 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) +## 📚 Example Workflow ```bash -# Save a value -curl -X POST http://localhost:8000/tool/save \ - -H "Content-Type: application/json" \ - -d '{"key":"example","value":123}' +# Terminal 1 – start server +$ python memory_server.py +Server listening on http://localhost:8000 -# Get the value back -curl http://localhost:8000/tool/get?key=example - -# List all keys -curl http://localhost:8000/tool/list_keys +# Terminal 2 – run client demo +$ python memory_client.py +Значение сохранено под ключом 'name'. +Alice +{'keys': ['name']} +Ключ 'name' удалён. ``` --- -## 🛠️ Extending the Server +## 🔧 Troubleshooting -- **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. +| Issue | Fix | +|-------|-----| +| `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. | +| Unexpected RPC errors | Check that the tool names match exactly (`save`, `get`, etc.). | -Feel free to fork and enhance! +--- + +## 📄 License + +MIT © 2026 --- \ No newline at end of file