🔌 MCP Tool Server

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 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:

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:

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

# 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):

{
  "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:

pip install -r requirements-dev.txt
pytest tests/ -v

---

📄 License

MIT License. See LICENSE for details.