# 🔌 MCP Tool Server

[![CI](https://github.com/coderman002/mcp-tool-server/actions/workflows/ci.yml/badge.svg)](https://github.com/coderman002/mcp-tool-server/actions)
[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square&logo=docker&logoColor=white)](https://docker.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e?style=flat-square)](LICENSE)

**A secure, production-grade Model Context Protocol (MCP) server that empowers LLM agents with filesystem operations, AST mathematical evaluation, and host system diagnostics.**

Built using [Python FastMCP SDK](https://github.com/modelcontextprotocol/python-sdk) and containerized with Docker.

---

## 🏗️ Architecture

The Model Context Protocol (MCP) establishes a secure JSON-RPC interface over standard I/O (stdio) between a host client (like Claude Desktop or Cursor) and our server:

```mermaid
graph LR
    subgraph Host_App ["Host Application (Client)"]
        A[LLM Agent] <--> B[MCP Client Interface]
    end
    subgraph Server_App ["MCP Tool Server (Server)"]
        B <-->|Stdio / JSON-RPC| C[FastMCP Entrypoint]
        C <--> D[File System Tools]
        C <--> E[AST Math Tools]
        C <--> F[System Diagnostic Tools]
    end
    D <-->|Access Guards| G[(Workspace Files)]
    F <-->|psutil| H[Host OS Metrics]
```

---

## ✨ Features

- 📁 **Secure Filesystem Access** — Paginated reading, directory listing, and recursive regex search with built-in path-traversal protections.
- 🧮 **Safe AST Calculation** — Evaluates mathematical expressions securely using python's `ast` parser (no raw `eval()` calls) and blocks resource exhaustion attempts.
- 🖥️ **Diagnostics Metrics** — Fetches CPU, RAM, and Disk space stats.
- 🐳 **Containerized** — Docker & Docker Compose setup for fast testing and isolation.
- ✅ **CI Validation** — Automated GitHub Actions verifying code linting and unit test coverage.

---

## 🛠️ Exposed Tools

The server registers and exposes the following tools to clients:

| Tool Name | Parameters | Description |
|---|---|---|
| `calculate_expression` | `expression: str` | Safely evaluates arithmetic and core math functions (sin, cos, pi, e, etc.). |
| `list_directory` | `path: str = "."` | Lists files and subdirectories. Locked to workspace boundaries. |
| `read_file_content` | `path: str`, `start_line: int`, `end_line: int` | Reads a target file securely with line-bound pagination. |
| `search_text_pattern` | `pattern: str`, `path: str = "."` | Performs recursive grep-like text search in workspace files. |
| `check_system_resources` | None | Returns instant system metrics (CPU load, RAM usage, storage space). |

---

## 🚀 Quick Start

### Option A: Running with Docker (Recommended)
Run the server instantly in an isolated environment:
```bash
# Build and run the stdio server
docker-compose up --build

# Run the test suite inside the container
docker-compose run tests
```

### Option B: Running with Local Python
If you prefer to run it locally without Docker:
```bash
# Install dependencies
pip install -r requirements.txt

# Run the server on stdio
python mcp_server.py
```

---

## 🔌 Host Client Integration

### 1. Claude Desktop
To integrate this server with **Claude Desktop**, add the configuration below to your `claude_desktop_config.json` (on Windows, located at `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mcp-tool-server": {
      "command": "python",
      "args": ["C:/Github Code/mcp-tool-server/mcp_server.py"],
      "env": {
        "MCP_WORKSPACE_DIR": "C:/Github Code"
      }
    }
  }
}
```

### 2. Cursor IDE
1. Open Cursor Settings → **Features** → **MCP**.
2. Click **+ Add New MCP Server**.
3. Fill details:
   - **Name**: `mcp-tool-server`
   - **Type**: `stdio`
   - **Command**: `python "C:/Github Code/mcp-tool-server/mcp_server.py"`
4. Save and let Cursor auto-detect the registered tools!

---

## 🧪 Running Tests Locally

To install testing dependencies and run the pytest suite:
```bash
pip install -r requirements-dev.txt
pytest tests/ -v
```

---

## 📄 License
MIT License. See [LICENSE](LICENSE) for details.