Добавлен README.md
This commit is contained in:
@@ -1,120 +1,159 @@
|
|||||||
# MCP‑сервер для управления памятью агента
|
# MCP Memory Server
|
||||||
|
|
||||||
## Описание
|
A lightweight **Model Context Protocol (MCP)** server that exposes a simple JSON‑based memory store over HTTP.
|
||||||
MCP‑сервер (Model Context Protocol) – это самостоятельный сервис, который предоставляет API для работы с памятью агентов через стандартизированный протокол. Сервис поддерживает **namespaces** и хранит данные в JSON‑файле, позволяя агентам сохранять, обновлять и получать информацию независимо от их локального окружения.
|
It is built on top of the `fastmcp` framework and uses `pydantic` for data validation and `python-dotenv` to load configuration.
|
||||||
|
|
||||||
- **FastMCP** – быстрый HTTP‑сервер для MCP.
|
> **Why this project?**
|
||||||
- **Pydantic** – валидатор данных (не используется напрямую в примере, но готов к расширению).
|
> In multi‑agent systems agents often need a shared, persistent context. The MCP server provides a single source of truth that can be queried by any agent via the standardized protocol.
|
||||||
- **python-dotenv** – загрузка переменных окружения из `.env`.
|
|
||||||
|
|
||||||
## Предварительные требования
|
---
|
||||||
| Пакет | Версия |
|
|
||||||
|-------|--------|
|
|
||||||
| Python | 3.10+ |
|
|
||||||
| pip | любой |
|
|
||||||
|
|
||||||
Установите зависимости через `pip`:
|
## 📦 Features
|
||||||
|
|
||||||
|
| Feature | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| **Namespaces** | Organise data into logical groups (`/namespace/key`). |
|
||||||
|
| **CRUD** | Create, read, update and delete keys. |
|
||||||
|
| **Search** | Find keys that match a pattern or contain a substring. |
|
||||||
|
| **Persistence** | All data is stored in a single JSON file on disk. |
|
||||||
|
| **Fast & Async** | Built with `fastmcp` – fast, type‑safe, async HTTP server. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Prerequisites
|
||||||
|
|
||||||
|
- Python 3.10+
|
||||||
|
- pip (or any other package manager)
|
||||||
|
|
||||||
|
> The project uses only pure‑Python dependencies; no external services are required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚙️ Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Clone the repository
|
||||||
|
git clone https://github.com/your-org/mcp-memory-server.git
|
||||||
|
cd mcp-memory-server
|
||||||
|
|
||||||
|
# Create a virtual environment (recommended)
|
||||||
|
python -m venv .venv
|
||||||
|
source .venv/bin/activate # On Windows: .\.venv\Scripts\activate
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
Файл `requirements.txt` содержит:
|
`requirements.txt` contains:
|
||||||
```
|
|
||||||
|
```text
|
||||||
fastmcp>=0.1.0
|
fastmcp>=0.1.0
|
||||||
pydantic>=2.0
|
pydantic>=2.0
|
||||||
python-dotenv>=1.0
|
python-dotenv>=1.0
|
||||||
|
uvicorn>=0.30.0 # optional, for running with ASGI server
|
||||||
```
|
```
|
||||||
|
|
||||||
## Установка
|
---
|
||||||
Клонируйте репозиторий и установите зависимости:
|
|
||||||
|
|
||||||
```bash
|
## 🚀 Running the Server
|
||||||
git clone https://github.com/your-org/memory-mcp.git
|
|
||||||
cd memory-mcp
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
Создайте файл `.env` в корне проекта (если понадобится):
|
The server reads configuration from a `.env` file (or environment variables).
|
||||||
|
Create a `.env` in the project root:
|
||||||
|
|
||||||
```dotenv
|
```dotenv
|
||||||
MEMORY_FILE=memory_data.json
|
# .env
|
||||||
PORT=8000
|
SERVER_HOST=127.0.0.1
|
||||||
|
SERVER_PORT=8000
|
||||||
|
DATA_FILE=data/memory.json # relative to project root
|
||||||
```
|
```
|
||||||
|
|
||||||
## Запуск
|
Start the server with:
|
||||||
Запустите сервер:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python memory_server.py
|
python memory_server.py
|
||||||
```
|
```
|
||||||
|
|
||||||
Сервер будет слушать на порту, указанном в переменной `PORT` (по умолчанию 8000).
|
The server will listen on `http://127.0.0.1:8000` and expose the following endpoints:
|
||||||
|
|
||||||
### Пример использования клиента
|
| Method | Path | Action |
|
||||||
|
|--------|------|--------|
|
||||||
|
| POST | `/namespace/key` | Create/Update a key |
|
||||||
|
| GET | `/namespace/key` | Retrieve a key |
|
||||||
|
| DELETE | `/namespace/key` | Delete a key |
|
||||||
|
| GET | `/search?query=...` | Search keys |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Example Usage
|
||||||
|
|
||||||
|
Below is a minimal example of how an agent (or any HTTP client) can interact with the server.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
# memory_client.py
|
import httpx
|
||||||
from fastmcp import FastMCPClient
|
from pathlib import Path
|
||||||
import json
|
|
||||||
|
|
||||||
client = FastMCPClient("Memory-Server", host="localhost", port=8000)
|
BASE_URL = "http://127.0.0.1:8000"
|
||||||
|
|
||||||
# Сохранить запись
|
# 1️⃣ Create a key
|
||||||
response = client.post("/memory/namespace1/item1", data={"value": 42})
|
payload = {"value": "Hello, MCP!"}
|
||||||
print(response.json())
|
resp = httpx.post(f"{BASE_URL}/memory/greeting", json=payload)
|
||||||
|
print(resp.status_code) # 201 Created
|
||||||
|
|
||||||
# Получить запись
|
# 2️⃣ Read the key
|
||||||
response = client.get("/memory/namespace1/item1")
|
resp = httpx.get(f"{BASE_URL}/memory/greeting")
|
||||||
print(response.json())
|
print(resp.json()) # {"value":"Hello, MCP!"}
|
||||||
|
|
||||||
|
# 3️⃣ Search for keys containing "greet"
|
||||||
|
resp = httpx.get(f"{BASE_URL}/search?query=greet")
|
||||||
|
print(resp.json()) # ["memory/greeting"]
|
||||||
|
|
||||||
|
# 4️⃣ Delete the key
|
||||||
|
resp = httpx.delete(f"{BASE_URL}/memory/greeting")
|
||||||
|
print(resp.status_code) # 204 No Content
|
||||||
```
|
```
|
||||||
|
|
||||||
Запустите клиент в отдельном терминале:
|
> **Tip:** The `memory_client.py` module contains a thin wrapper around these HTTP calls, making it easier to integrate into your agents.
|
||||||
|
|
||||||
```bash
|
---
|
||||||
python memory_client.py
|
|
||||||
```
|
|
||||||
|
|
||||||
## Пример работы
|
## 📁 Project Structure
|
||||||
|
|
||||||
1. **Сохранение данных**
|
```text
|
||||||
|
mcp-memory-server/
|
||||||
```bash
|
├── memory_server.py # FastMCP server implementation
|
||||||
curl -X POST http://localhost:8000/memory/namespaces/agents/agent_123 \
|
├── memory_client.py # Helper client for interacting with the server
|
||||||
-H "Content-Type: application/json" \
|
├── .env # Environment configuration (example)
|
||||||
-d '{"name":"Alice","role":"researcher"}'
|
├── requirements.txt # Dependencies
|
||||||
```
|
└── README.md # This file
|
||||||
|
|
||||||
2. **Получение данных**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl http://localhost:8000/memory/namespaces/agents/agent_123
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Обновление записи**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X PUT http://localhost:8000/memory/namespaces/agents/agent_123 \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"name":"Alice","role":"senior researcher"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Удаление записи**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X DELETE http://localhost:8000/memory/namespaces/agents/agent_123
|
|
||||||
```
|
|
||||||
|
|
||||||
## Структура проекта
|
|
||||||
|
|
||||||
```
|
|
||||||
memory-mcp/
|
|
||||||
├── memory_server.py # Сервер MCP
|
|
||||||
├── memory_client.py # Пример клиента
|
|
||||||
├── requirements.txt
|
|
||||||
└── .env (опционально)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Готово!** Теперь у вас есть работающий MCP‑сервер для управления памятью агентов. 🚀
|
## 🧪 Testing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run unit tests (if any)
|
||||||
|
pytest tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
> Currently there are no automated tests, but you can easily add them using `pytest` and `httpx`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contributing
|
||||||
|
|
||||||
|
Feel free to open issues or pull requests.
|
||||||
|
Please follow the standard GitHub workflow:
|
||||||
|
|
||||||
|
1. Fork the repo
|
||||||
|
2. Create a feature branch (`feature/your-feature`)
|
||||||
|
3. Commit & push
|
||||||
|
4. Open a Pull Request
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📜 License
|
||||||
|
|
||||||
|
MIT © 2026 Your Name / Organization
|
||||||
|
|
||||||
|
---
|
||||||
Reference in New Issue
Block a user