125 lines
3.1 KiB
Markdown
125 lines
3.1 KiB
Markdown
# MCP‑Memory Server
|
||
|
||
A lightweight **FastMCP** based key/value store for agent memory with support for namespaces.
|
||
|
||
- **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
|
||
# Clone the repo (or copy the files)
|
||
git clone https://github.com/yourname/mcp-memory-server.git
|
||
cd mcp-memory-server
|
||
|
||
# Create a virtual environment (optional but recommended)
|
||
python -m venv .venv
|
||
source .venv/bin/activate # On Windows: .\.venv\Scripts\activate
|
||
|
||
# Install dependencies
|
||
pip install fastmcp
|
||
```
|
||
|
||
> **Tip:** If you want to run the client and server on different machines, make sure the host machine is reachable from the client.
|
||
|
||
---
|
||
|
||
## 🚀 Running the Server
|
||
|
||
```bash
|
||
python 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`.
|
||
|
||
---
|
||
|
||
## 🧩 Using the Client
|
||
|
||
```bash
|
||
python memory_client.py
|
||
```
|
||
|
||
The client script demonstrates how to call each tool:
|
||
|
||
1. **Save a key/value pair**
|
||
```python
|
||
result = await client.call("save", {"key": "name", "value": "Alice"})
|
||
print(result) # → "Значение сохранено под ключом 'name'."
|
||
```
|
||
|
||
2. **Retrieve the value**
|
||
```python
|
||
value = await client.call("get", {"key": "name"})
|
||
print(value) # → "Alice"
|
||
```
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## 📚 Example Workflow
|
||
|
||
```bash
|
||
# Terminal 1 – start server
|
||
$ python memory_server.py
|
||
Server listening on http://localhost:8000
|
||
|
||
# Terminal 2 – run client demo
|
||
$ python memory_client.py
|
||
Значение сохранено под ключом 'name'.
|
||
Alice
|
||
{'keys': ['name']}
|
||
Ключ 'name' удалён.
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Troubleshooting
|
||
|
||
| 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.). |
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT © 2026
|
||
|
||
--- |