🔌 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]

Related MCP server: NATE-MCP-SERVER

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

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