MCP-Bridge-Kit

Hardened Model Context Protocol (MCP) developer server and automated JSON-RPC protocol compliance verifier.

The Problem

The Model Context Protocol (MCP) has rapidly emerged as the open industry standard connecting LLMs and agentic assistants (like Claude Desktop, Cursor, and autonomous agent loops) with tools, data sources, and dev environments.

However, building and maintaining custom Python MCP servers surfaces severe friction:

1. The "stdio Trap": When local desktop hosts launch Python MCP servers over stdio, any stray print(), package initialization log, or warning output to stdout corrupts JSON-RPC 2.0 framing, crashing the client connection silently.

2. Security Sandboxing Gaps: Custom file tools frequently lack path-traversal guards, exposing local systems to arbitrary path traversal (../../etc/passwd or ../../Windows).

3. Absence of Compliance Tooling: Developers have lacked a fast, automated test harness to verify whether their server correctly implements the MCP handshake (initialize), error codes (-32601), and schema definitions.

Related MCP server: TunnelGPT MCP Core

The Solution: MCP-Bridge-Kit

MCP-Bridge-Kit delivers a dual-capability toolkit for the MCP ecosystem:

• Hardened MCP Developer Server: Pre-configured with essential developer tools (read_file, write_file, list_directory, get_env, git_status, run_command).

• Path-Traversal Guardrails: Strict chroot containment blocks any access outside the designated sandbox root directory.

• Stdout Channel Shielding: All diagnostics, logs, and warnings are strictly redirected to sys.stderr, preserving 100% protocol cleanliness on stdout.

• Automatic Secret Scrubbing: Environment variable inspections automatically mask sensitive tokens (KEY, SECRET, PASSWORD, TOKEN).

• Automated Conformance Verifier (mcp-verify): A standalone CLI harness that launches any target MCP server, executes the complete handshake lifecycle, validates tool schemas, detects stdout pollution, and benchmarks latency.

Architecture Overview

                          +------------------------+
                          |   Agent Host (Client)  |
                          +-----------+------------+
                                      |
                      JSON-RPC 2.0 stdio (Clean Stream)
                                      |
                                      v
                          +------------------------+
                          |  Hardened MCP Server   |
                          |  - stderr logging only |
                          |  - JSON-RPC 2.0 router |
                          +-----------+------------+
                                      |
              +-----------------------+-----------------------+
              |                       |                       |
              v                       v                       v
     +-----------------+     +-----------------+     +-----------------+
     | Sandboxed Files |     | Masked Env Info |     | Command Guard   |
     | (Path traversal |     | (Auto-scrubbed  |     | (Isolated pipes |
     |  prevention)    |     |  tokens)        |     |  with timeout)  |
     +-----------------+     +-----------------+     +-----------------+

                                     ***
                          +------------------------+
                          |   mcp-verify Harness   |
                          | (Tests ANY MCP Server) |
                          +------------------------+

Installation

From Source (Local Development)

git clone https://github.com/Hakantes/mcp-bridge-kit.git
cd mcp-bridge-kit
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Quick-Start Guide

1. Run the Hardened Server in Claude Desktop / Cursor

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-bridge": {
      "command": "mcp-bridge",
      "args": ["serve", "--sandbox", "/path/to/your/project"]
    }
  }
}

2. Verify an MCP Server with mcp-verify

Test any local or third-party MCP server for specification compliance and stdout cleanliness:

mcp-verify --command "python -m mcp_bridge.cli serve"

Tools Provided by MCP Server

CLI Reference

Testing

Run unit and integration tests using pytest:

pytest -v

Security and Privacy Notes

• Path Escape Confinement: Target paths are resolved to their canonical paths and validated using Path.is_relative_to(sandbox_root). Any ../ attempt escaping the root immediately triggers an error without file access.

• Credential Masking: Environment inspection matches against sensitive keywords and redacts values as ******** [REDACTED SENSITIVE KEY].

• Subprocess Isolation: Commands run with explicit timeout limits, preventing un-reaped zombie processes.

Known Limitations

• Supported transport in v0.1.0 is stdio. Streamable HTTP / Server-Sent Events (SSE) remote transport is scheduled for v0.2.0.

• Prompts and Resources capabilities are parsed in initialization but tool execution is the primary vertical slice in v0.1.0.

Contributing and License

Contributions are welcome! Please check CONTRIBUTING.md and SECURITY.md.

Distributed under the MIT License. See LICENSE for details.