# MCP Agent Toolkit 🛠️

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![Model Context Protocol](https://img.shields.io/badge/Protocol-MCP%202024--11--05-purple)](https://modelcontextprotocol.io/)

A modular, lightweight Python implementation of the **Model Context Protocol (MCP)** specification. Enables developers to rapidly build, test, and deploy custom tool-calling servers and sandboxed execution environments for AI agents (Cursor, Anthropic Claude, LangChain, AutoGen).

---

## 🌟 Key Features

- **JSON-RPC 2.0 Compliant**: Full implementation of MCP protocol methods (`initialize`, `tools/list`, `tools/call`).
- **Zero Heavy Dependencies**: Pure Python standard library implementation with zero external baggage.
- **Sandboxed Filesystem Tool**: Path traversal-proof file operations confined strictly to an isolated root directory.
- **Agent Scratchpad & Memory Store**: In-memory key-value state and audit trail logging for long-running workflows.
- **Plug-and-Play Extensibility**: Decorate or register any Python function as an MCP tool with schema validation in seconds.

---

## 🚀 Quickstart

### 1. Register Tools & Run Server

```python
from mcp_agent_toolkit import MCPServer, MCPClient

# Initialize MCP Server
server = MCPServer(name="calculator-agent", version="1.0.0")

# Register custom tool
server.register_tool(
    name="multiply",
    description="Multiplies two numbers",
    parameters={
        "type": "object",
        "properties": {
            "x": {"type": "number"},
            "y": {"type": "number"}
        },
        "required": ["x", "y"]
    },
    handler=lambda x, y: x * y
)

# Connect Client
client = MCPClient(server)
result = client.execute_tool("multiply", x=6, y=7)
print(result["content"][0]["text"])  # Output: 42
```

### 2. Sandboxed File Operations

```python
from mcp_agent_toolkit import SandboxedFilesystemTool

fs = SandboxedFilesystemTool(sandbox_root="./agent_workspace")
fs.write_file("notes.txt", "Autonomous agent task plan.")
content = fs.read_file("notes.txt")
```

---

## 🧪 Running Tests

```bash
python -m unittest discover tests
```

---

## 📄 License
Released under the [MIT License](LICENSE). Built with clean architecture principles by [Milind Chatrabhuji](https://github.com/MilindChatrabhuji).