MCP-ToolHub — Model Context Protocol Tool Hub & Client Architecture

A production-style implementation of the Model Context Protocol (MCP) using the official mcp 2.x Python SDK, showcasing modular server registration, automated tool discovery, parameter schema validation, sandboxed filesystem execution, and complete audit trace logging.

1. What is MCP-ToolHub? (In Plain Language)

The Model Context Protocol (MCP) is an open industry standard that allows Large Language Models (LLMs) and autonomous agents to safely connect with external tools, APIs, and data sources. Rather than writing custom integration code for every tool, MCP provides a standard communication protocol between:

• MCP Servers: Services that expose tools (e.g., read files, inspect Git repos, hash strings).

• MCP Clients: Programs that discover available tools, validate input arguments, execute tools on demand, and capture execution results.

MCP-ToolHub is a working architecture demonstrating real MCP client-server communication. It provides three modular MCP servers (Filesystem, Repository, and Utility), dynamic tool discovery with JSON schema reflection, strict path-traversal sandboxing, execution timeouts, and an audit trail API.

Related MCP server: fde-assessment

2. Why MCP-ToolHub Exists

1. Demonstrate Real MCP 2.x Architecture: Uses the official mcp.server.mcpserver.MCPServer interface and official protocol specifications—not simulated mock functions.

2. Security & Permission Boundaries: Demonstrates how to prevent arbitrary command execution and directory traversal attacks (../../etc/passwd) using a strict sandbox boundary guard.

3. Robust Tool Client: Features automatic parameter schema validation, asyncio timeout enforcement, and structured execution traces for every invocation attempt.

4. Unified API Gateway: Exposes all discovered MCP tools through a developer-friendly REST API for effortless frontend or AI agent integration.

3. How It Works

1. Server Initialization: Modular MCP servers register safe, typed tools using the @server.tool() decorator:

   • Filesystem Server: Safe read-only inspection (safe_read_file, safe_list_directory, safe_file_stats) confined to a sandboxed directory.

   • Repository Server: Git inspection tools (validate_commit_hash, analyze_code_structure, detect_license_type).

   • Utility Server: Cryptographic and token tools (calculate_hash, validate_json, estimate_tokens).

2. Dynamic Discovery: The ToolRegistry queries each server for its exposed tools, descriptions, and JSON parameter schemas.

3. Client Invocation & Validation: When an invocation request arrives, the MCPClient:

   • Confirms server availability and tool existence.

   • Validates provided arguments against required schema parameters.

   • Enforces execution timeouts via asyncio.wait_for.

   • Traps permission violations and classifies them into permission_denied status.

4. Audit Logging: Every invocation is appended to an in-memory chronological trace history recording execution ID, duration in milliseconds, inputs, and outputs.

4. Architecture Diagram

flowchart TD
    A[MCP Client and REST Caller] --> B[MCP Client Engine]
    B --> C[Dynamic Tool Registry]
    C --> D[Tool Discovery and Schema Reflection]
    B --> E[JSON Schema Argument Validator]
    B --> F[Sandbox Boundary Guard]
    B --> G[Asyncio Timeout Controller]
    F --> H[Filesystem MCP Server]
    E --> I[Repository Inspection MCP Server]
    E --> J[Utility Cryptography MCP Server]
    H --> K[Execution Trace and Audit Logger]
    I --> K
    J --> K
    K --> L[Structured Tool Invocation Response]

5. Technology Stack

• Protocol & SDK: Official mcp 2.x SDK (mcp.server.mcpserver.MCPServer)

• API Framework: Python 3.12, FastAPI, Starlette, Pydantic v2

• Concurrency: Python asyncio with strict deadline timeouts

• Containerization: Docker, Docker Compose

• Quality & Testing: Pytest, Pytest-Asyncio, Ruff

6. Project Structure

MCP-ToolHub/
├── .env.example              # Environment variables template
├── .gitignore                # Git exclusions
├── .dockerignore             # Docker build exclusions
├── Dockerfile                # Production container specification
├── docker-compose.yml        # Docker Compose service definition
├── pyproject.toml            # Linter and test configurations
├── requirements.txt          # Python dependencies
├── LICENSE                   # Apache 2.0 License
├── README.md                 # Technical documentation
├── sandbox/                  # Isolated sandbox directory for filesystem tools
│   └── sample.json           # Sample file for read tests
├── toolhub/
│   ├── __init__.py           # Package marker
│   ├── main.py               # FastAPI REST API and routes
│   ├── config.py             # Settings and sandbox path resolution
│   ├── schemas.py            # Pydantic schemas (Metadata, Invocations, Traces)
│   ├── registry.py           # ToolRegistry for multi-server discovery
│   ├── client.py             # MCPClient with timeout, validation, and security
│   └── servers/
│       ├── __init__.py       # Server exports
│       ├── filesystem.py     # Sandboxed read-only filesystem tools
│       ├── repository.py     # Code parsing and Git commit validation tools
│       └── utility.py        # Hashing, JSON validation, and token estimation tools
└── tests/
    ├── __init__.py
    ├── test_discovery.py     # Multi-server tool discovery tests
    ├── test_invocations.py   # Valid tool execution tests
    ├── test_permissions.py   # Path-traversal security boundary tests
    ├── test_error_handling.py# Timeout, missing argument, and unknown server tests
    └── test_api.py           # FastAPI integration tests

7. Setup & Prerequisites

• Python: Version 3.10+ (Python 3.12 recommended)

• Docker: (Optional, for containerized execution)

8. Environment Variables

Create your local .env file:

cp .env.example .env

9. Running Locally

# 1. Install dependencies
pip install -r requirements.txt

# 2. Run the application
python -m uvicorn toolhub.main:app --host 0.0.0.0 --port 8000 --reload

Interactive documentation is available at: http://localhost:8000/docs

10. Docker Usage

Build and Run with Docker

docker build -t mcp-toolhub:latest .
docker run -d --name mcp-hub -p 8083:8000 mcp-toolhub:latest

Run with Docker Compose

docker compose up -d --build

11. API Usage & Discovery Workflow

11.1 Discover Available Tools

curl -X GET "http://localhost:8000/v1/tools"

Response excerpt:

[
  {
    "name": "calculate_hash",
    "server": "utility",
    "description": "Calculates cryptographic hash digest for input string.",
    "parameters": {
      "properties": {
        "data": {"title": "Data", "type": "string"},
        "algorithm": {"default": "sha256", "title": "Algorithm", "type": "string"}
      },
      "required": ["data"]
    },
    "permission_scope": "isolated_utility"
  }
]

11.2 Invoke a Tool

curl -X POST "http://localhost:8000/v1/tools/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "utility",
    "tool": "calculate_hash",
    "arguments": {
      "data": "Hello MCP World",
      "algorithm": "sha256"
    }
  }'

Response:

{
  "execution_id": "exec-d4e5f6a1b2",
  "server": "utility",
  "tool": "calculate_hash",
  "arguments": {"data": "Hello MCP World", "algorithm": "sha256"},
  "status": "success",
  "duration_ms": 0.35,
  "result": {
    "algorithm": "sha256",
    "input_bytes": 15,
    "digest": "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592"
  },
  "error": null,
  "timestamp": 1726950000
}

11.3 Security Boundary Enforcement Example

Attempting directory traversal (../../etc/passwd) is automatically trapped and blocked:

curl -X POST "http://localhost:8000/v1/tools/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "filesystem",
    "tool": "safe_read_file",
    "arguments": {"path": "../../etc/passwd"}
  }'

Response:

{
  "execution_id": "exec-9c8b7a6d5e",
  "server": "filesystem",
  "tool": "safe_read_file",
  "arguments": {"path": "../../etc/passwd"},
  "status": "permission_denied",
  "duration_ms": 0.42,
  "result": null,
  "error": "Security Violation: Target path '../../etc/passwd' escapes sandbox boundary",
  "timestamp": 1726950000
}

12. Automated Testing

Run the full automated test suite verifying discovery, execution, permissions, and timeout handling:

python -m pytest tests -v
python -m ruff check .

13. Limitations

• Read-Only Focus: Write operations and system-modifying capabilities are intentionally prohibited by design.

• In-Memory Traces: Execution traces are stored in memory for educational clarity. For enterprise logging, configure PostgreSQL or Redis persistence.

14. Security Considerations

• Strict Sandbox Boundary: Path resolution verifies target.relative_to(sandbox_root) before touching files on disk. Escapes throw PermissionError.

• No Arbitrary Code Execution: No eval, exec, or unvetted shell execution tools exist in the system.

• Resource Limits: Tool executions are strictly bounded by timeout deadlines preventing denial-of-service hanging.

15. License

Licensed under the Apache License, Version 2.0.