# 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.