Utils

This module contains internal utilities and helpers.

STDIO Proxy

Shared STDIO↔HTTP MCP proxy utilities.

Provides a small MCP server over STDIO that forwards initialize/initialized and tools/* JSON-RPC calls to an HTTP MCP server (e.g., http://127.0.0.1:8123/mcp).

Used by both Claude Desktop and Codex launchers to avoid code duplication.

This module uses FastMCP’s built-in proxy pattern (FastMCP.as_proxy) to automatically mirror tools, resources, and prompts from the backend server. This ensures that: 1. Tool descriptions are automatically forwarded to MCP clients 2. New tools added to the backend are automatically available 3. No manual synchronization of tool definitions is required

async instrmcp.utils.stdio_proxy.check_http_mcp_server(host='127.0.0.1', port=8123)[source]

Check if the HTTP MCP server is running and responding.

Parameters:

host (str)
port (int)

Return type:

bool

instrmcp.utils.stdio_proxy.create_stdio_proxy_server(base_url, server_name='InstrMCP Proxy')[source]

Create an MCP proxy server that forwards requests to an HTTP backend.

This uses FastMCP’s built-in proxy pattern which automatically: - Mirrors all tools with their descriptions and schemas - Mirrors all resources - Handles session management and request forwarding

Parameters:

base_url (str) – URL of the HTTP MCP backend (e.g., “http://127.0.0.1:8123”)
server_name (str) – Name for this proxy server

Return type:

FastMCP

Returns:

FastMCP server instance configured as a proxy

Note

Connection to the backend is lazy - errors will surface on first tool call, not at proxy creation time.

class instrmcp.utils.stdio_proxy.StdioMCPClient(launcher_path=None, mcp_url='http://127.0.0.1:8123')[source]

Bases: object

MCP client that communicates with a proxy subprocess via STDIO.

This client spawns the claude_launcher.py subprocess and sends JSON-RPC commands via STDIN, receiving responses via STDOUT.

Used by instrmcp metadata validate to test the full communication path: CLI → STDIO → stdio_proxy → HTTP → MCP Server

Usage:

client = StdioMCPClient() try:

client.start() tools = client.list_tools() resources = client.list_resources()

finally:: client.stop()

Parameters:

launcher_path (str | None)
mcp_url (str)

__init__(launcher_path=None, mcp_url='http://127.0.0.1:8123')[source]

Initialize the STDIO MCP client.

Parameters:

launcher_path (str | None) – Path to the launcher script. If None, uses the bundled claude_launcher.py.
mcp_url (str) – URL of the MCP server (used for error messages).

start(timeout=10.0)[source]

Start the proxy subprocess and initialize the MCP session.

Parameters:

timeout (float) – Timeout in seconds for initialization.

Raises:

RuntimeError – If subprocess fails to start or initialize.
FileNotFoundError – If launcher script not found.

Return type:

None

stop()[source]

Stop the proxy subprocess.

Return type:: None

list_tools(timeout=10.0)[source]

Get the list of registered tools from the server.

Return type:: list[dict]
Returns:: List of tool dicts with name, description, inputSchema.
Parameters:: timeout (float)

list_resources(timeout=10.0)[source]

Get the list of registered resources from the server.

Return type:: list[dict]
Returns:: List of resource dicts with uri, name, description.
Parameters:: timeout (float)

Key Functions

check_http_mcp_server

async instrmcp.utils.stdio_proxy.check_http_mcp_server(host='127.0.0.1', port=8123)[source]

Check if the HTTP MCP server is running and responding.

Parameters:

host (str)
port (int)

Return type:

bool

create_stdio_proxy_server

instrmcp.utils.stdio_proxy.create_stdio_proxy_server(base_url, server_name='InstrMCP Proxy')[source]

Create an MCP proxy server that forwards requests to an HTTP backend.

This uses FastMCP’s built-in proxy pattern which automatically: - Mirrors all tools with their descriptions and schemas - Mirrors all resources - Handles session management and request forwarding

Parameters:

base_url (str) – URL of the HTTP MCP backend (e.g., “http://127.0.0.1:8123”)
server_name (str) – Name for this proxy server

Return type:

FastMCP

Returns:

FastMCP server instance configured as a proxy

Note

Connection to the backend is lazy - errors will surface on first tool call, not at proxy creation time.

Creates a FastMCP proxy server that forwards STDIO to an HTTP backend. Uses FastMCP’s built-in as_proxy() pattern for automatic tool and resource mirroring with full description forwarding.

Example usage:

mcp = create_stdio_proxy_server(
    base_url="http://127.0.0.1:8123",
    server_name="InstrMCP Proxy"
)
mcp.run()