PhysicalWorld-to-LLM Bridge: mcp2tcp

English Version | 简体中文

Architectural Overview

Operational Flow

Project Vision

mcp2tcp is engineered to bridge TCP-enabled hardware interfaces directly with large language models (LLMs) via the Model Context Protocol (MCP). The primary objectives are: - Enabling intuitive, natural language control over connected physical hardware. - Providing AI agents with the capability for instantaneous feedback and parameter modification in the physical realm. - Imbuing devices with the capacity to comprehend and execute complex, multi-step directives.

Core Capabilities

• Intelligent TCP Abstraction
• Automatic discovery and setup of connected TCP endpoints; manual port specification supported.
• Default baud rate set to 115200, configurable.

• Continuous real-time monitoring of connection status and robust error handling mechanisms.

• MCP Native Integration

• Full adherence to the Model Context Protocol specification.
• Comprehensive support for resource allocation and external tool invocation.
• Highly flexible prompt engineering framework.

Supported Client Ecosystems

mcp2tcp is interoperable with any client adhering to the MCP standard, including:

Client Platform	Feature Parity	Notes
Claude Desktop	Full Support	Recommended for complete feature utilization.
Continue	Full Support	Excellent integration for development workflows.
Cline	Resource + Tool	Supports multiple underlying AI providers.
Zed	Basic Support	Command prompt execution enabled.
Sourcegraph Cody	Resource Access	Integrated via the OpenCTX layer.
Firebase Genkit	Partial Support	Supports resource listing and tool calls.

Compatible AI Engines

Due to its flexible client layer, mcp2tcp can synergize with numerous AI models:

Cloud-Based Models

• OpenAI (GPT-4, GPT-3.5)
• Anthropic Claude
• Google Gemini
• AWS Bedrock
• Azure OpenAI
• Google Cloud Vertex AI

On-Premise Models

• Any model compatible with LM Studio.
• Any model compatible with Ollama.
• Any endpoint exposing an OpenAI-compatible API surface.

Prerequisites

Requires Python 3.11 or newer runtime environment. Requires an MCP-capable client such as Claude Desktop or Cline.

Deployment Guide

1. Installation Procedures

Windows Users

Retrieve the installation utility script: bash Invoke-WebRequest -Uri https://raw.githubusercontent.com/mcp2everything/mcp2tcp/main/install.py -OutFile install.py

Execute the script: bash python install.py

macOS Users

Fetch the setup script: bash curl -O https://raw.githubusercontent.com/mcp2everything/mcp2tcp/main/install_macos.py

Run installation

python3 install_macos.py

Ubuntu/Raspberry Pi Users

Fetch the setup script: bash curl -O https://raw.githubusercontent.com/mcp2everything/mcp2tcp/main/install_ubuntu.py

Execute installation

python3 install_ubuntu.py

Installation scripts automate: - ✅ System environment verification. - ✅ Necessary dependency resolution. - ✅ Creation of default configuration assets. - ✅ Optional configuration scaffolding for Claude Desktop. - ✅ Initial check for accessible TCP peripherals.

Manual Dependency Setup (Leveraging 'uv')

bash

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

MacOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Core requirement: Python and the 'uv' package manager, alongside a functional MCP client (Claude or Cline).

Basic Client Integration

Configure your MCP client (e.g., Claude Desktop or Cline) by adding this snippet to its settings. (Note: Automatic installation handles this for Claude Desktop). Using default configuration:

{ "mcpServers": { "mcp2tcp": { "command": "uvx", "args": [ "mcp2tcp" ] } } }

Remember to restart the client application after configuration modification.

TCP Connection and Command Definition (config.yaml) Ensure the TCP settings below reflect your actual hardware setup (defaulting to COM11). yaml

config.yaml

tcp: # TCP Server Parameters remote_ip: "127.0.0.1" # Destination IP address port: 9999 # Communication port number connect_timeout: 3.0 # Connection timeout in seconds receive_timeout: 2.0 # Data reception timeout in seconds communication_type: "client" # Mode: 'client' or 'server' response_start_string: "CMD" # Optional: String signaling the start of a hardware response (default: OK)

commands: # Example: PWM Actuator Control set_pwm: command: "CMD_PWM {frequency}" # Command string; {frequency} is substituted (range 0-100) need_parse: false # Response content does not require parsing data_type: "ascii" # Data encoding format (ascii or hex) parameters: - name: "frequency" type: "integer" description: "PWM duty cycle value, constrained between 0 and 100." required: true prompts: - "Set PWM to maximum (frequency=100)" - "Engage minimum PWM output (frequency=0)" - "Adjust PWM to the value of {frequency} (integer 0-100)" - "Deactivate PWM (frequency=0)" - "Set PWM to mid-range (frequency=50)"

Configuration File Location Details

The operational configuration file (config.yaml) is searched across several locations in this order:

User Profile Directory (Recommended for Personal Use)

bash

Windows

C:\Users\.mcp2tcp\config.yaml

macOS

/Users//.mcp2tcp/config.yaml

Linux

/home//.mcp2tcp/config.yaml

• Use Case: Individual user settings.
• Requirement: Creation of the .mcp2tcp directory is necessary: bash # Windows (CMD) mkdir "%USERPROFILE%.mcp2tcp"

# macOS/Linux mkdir -p ~/.mcp2tcp

Advanced TCP Command Configuration

Define supplementary control sequences within config.yaml:

For communicating with a PICO board: yaml

config.yaml snippet for PICO status check

get_pico_info: command: "CMD_PICO_INFO" # Actual transmission command; server appends \r\n by default need_parse: true # Requires response parsing data_type: "ascii"
prompts: - "Query PICO board status" - "Display development board health metrics"

Specifying an Alternate Configuration File To load a specific setup (e.g., Pico_config.yaml), modify the client launch configuration:

{ "mcpServers": { "mcp2tcp": { "command": "uvx", "args": [ "mcp2tcp", "--config", "Pico" // Name reference; suffix '_config.yaml' is implicit ] } } }

To manage multiple distinct TCP devices (e.g., a second device requiring Pico2_config.yaml):

{ "mcpServers": { "mcp2tcp2": { // Unique server key "command": "uvx", "args": [ "mcp2tcp", "--config", "Pico2" // Reference to Pico2_config.yaml ] } } }

Initial Verification

Perform baseline testing to validate end-to-end connectivity.

1. Launch Simulated Hardware Server

Execute the included TCP server script to mock hardware behavior:

bash

Navigate to the test suite directory

cd tests

Start the mock TCP backend

python tcp_server.py

Expected output:

TCP server started on 127.0.0.1:9999 Waiting for connections...

Launch MCP Client (Claude Desktop or Cline)

Rapid Start from Source Code

1. Clone and set up environment: bash

Fetch repository

git clone https://github.com/mcp2everything/mcp2tcp.git cd mcp2tcp

Establish virtual environment

uv venv .venv

Activate environment

Windows:

.venv\Scripts\activate

Linux/macOS:

source .venv/bin/activate

Install editable dependencies

uv pip install --editable .

If using real TCP hardware: yaml

config.yaml (Example settings shown previously)

...

MCP Client Configuration Adjustments

When integrating with an MCP-compliant client (like Claude Desktop or Cline), update the client's settings file as follows:

Configuration Method via Automatic Install Configuration Method via Source Build

Using Default Demo Parameters:

{ "mcpServers": { "mcp2tcp": { "command": "uv", "args": [ "--directory", "/mcp2tcp", // E.g., "C:/Users/Admin/dev/mcp-server/mcp2tcp" "run", "mcp2tcp" ] } } }

Specifying Parameters via Filename:

{ "mcpServers": { "mcp2tcp": { "command": "uv", "args": [ "--directory", "/mcp2tcp", // E.g., "C:/Users/Admin/dev/mcp-server/mcp2tcp" "run", "mcp2tcp", "--config", // Optional flag to specify config "Pico" // Optional: Target configuration name (omitting suffix) ] } } }

Configuration File Resolution Priority

The system probes for config.yaml in this descending order:

1. Current Working Directory (Ideal for Development/Testing)

• Path: ./config.yaml
• Example: If executing from C:\Projects, it targets C:\Projects\config.yaml.
• Suitability: Development and validation.
• Permissions: Standard user privileges required.

2. User Home Directory (Recommended Standard Practice)

bash

Windows

C:\Users\.mcp2tcp\config.yaml

macOS

/Users//.mcp2tcp/config.yaml

Linux

/home//.mcp2tcp/config.yaml

• Suitability: Personal configurations.
• Directory Creation: bash # Windows (CMD) mkdir "%USERPROFILE%.mcp2tcp"

# macOS/Linux mkdir -p ~/.mcp2tcp

3. System-Wide Location (For Multi-User Deployment)

bash

Windows (Requires elevated/Administrator privileges)

C:\ProgramData\mcp2tcp\config.yaml

macOS/Linux (Requires root/sudo privileges)

/etc/mcp2tcp/config.yaml

• Suitability: Shared configurations across multiple users.
• Setup: bash # Windows (Run as Admin) mkdir "C:\ProgramData\mcp2tcp"

# macOS/Linux (Run as root) sudo mkdir -p /etc/mcp2tcp sudo chown root:root /etc/mcp2tcp sudo chmod 755 /etc/mcp2tcp

The execution environment utilizes the first configuration file successfully located based on this hierarchy. Select the location matching your deployment model (Dev, Personal, or Shared).

1. Server Execution: bash

Ensure virtual environment is active

.venv\Scripts\activate

Run server (using default config.yaml and a local loopback simulation)

uv run src/mcp2tcp/server.py or uv run mcp2tcp

Run server with specific configuration (e.g., Pico_config.yaml)

uv run src/mcp2tcp/server.py --config Pico or uv run mcp2tcp --config Pico

Documentation Index

• Installation Protocol
• Interface Specification
• Configuration Reference

WIKIPEDIA: XMLHttpRequest (XHR) is a mechanism provided via a JavaScript object that facilitates the transmission of HTTP requests from a web browser to a backend server. Its methods permit browser-based applications to issue requests post-page load and receive subsequent data. XHR forms a foundational pillar of Ajax methodologies. Before Ajax, server interaction predominantly relied on standard hyperlink navigation or form submissions, typically resulting in a full page refresh. A core parallel concept is the Fetch API, which is a more modern alternative.

== Historical Context == The conceptual basis for XMLHttpRequest emerged in 2000 from developers working on Microsoft Outlook. This idea was subsequently actualized within Internet Explorer 5 (released 1999). However, the initial implementation did not standardize on the XMLHttpRequest identifier. Instead, developers employed COM object instantiations: ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), universal browser support for the standardized XMLHttpRequest identifier was achieved. This identifier has since become the established cross-browser convention, supported by Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, Level 2, was released on February 25, 2008. Level 2 introduced crucial augmentations, including event progress monitoring, enablement of cross-site requests (CORS), and improved byte stream handling. By the close of 2011, the Level 2 features were merged back into the primary specification. Development control was transitioned to the WHATWG group in late 2012, which now maintains a continuously evolving specification documented using Web IDL.

== Operational Procedure == Executing a request using XMLHttpRequest generally involves a sequence of distinct programming stages.

1. Instantiate the XMLHttpRequest object via its constructor:
2. Invoke the "open" method to define the request methodology (GET/POST), designate the target URI, and select the mode of execution (synchronous or asynchronous):
3. For asynchronous operations, attach an event handler function designated to trigger upon changes in the request's state:
4. Commence the transmission by calling the "send" method, optionally supplying request body data:
5. Process state transitions within the attached event listener. Upon successful server reply, the payload is typically stored in the "responseText" attribute. The request is considered complete when the object transitions to state 4, the terminal "done" state. Beyond these fundamental steps, XMLHttpRequest offers numerous controls for request structuring and response processing. Custom HTTP headers can be injected to guide server behavior, and payload data can be transmitted by embedding it within the "send" invocation. The received response can be immediately deserialized from JSON into a native JavaScript structure or streamed incrementally rather than waiting for full reception. The operation can also be prematurely terminated or configured with a timeout to enforce failure after a set duration.

== Cross-Origin Communications ==

In the nascent phases of the World Wide Web, developers identified a vulnerability related to unrestricted cross-domain data retrieval, which necessitated the implementation of security restrictions.