Voitta Interface for MCP

This service acts as a multiplexer for the Voitta library, exposing its functionalities through the Model Context Protocol (MCP) framework. It natively supports both synchronous standard I/O and asynchronous Server-Sent Events (SSE) transport mechanisms.

Prerequisites

• Requires Python version 3.10 or newer.
• All requisite libraries, including voitta, are itemized in requirements.txt.

Deployment Steps

1. Obtain a local copy of this repository (cloning).
2. Install necessary dependencies: bash pip install -r requirements.txt

Configuration Management

The operational parameters for Voitta are sourced from a YAML definition file. By default, the system targets /Users/gregory/g/projects/llm/roma/voitta-example/config/voitta.yaml. An alternative file location can be dictated by setting the CONFIG_PATH environment variable.

The structure of this configuration file must align with the specifications expected by the Voitta framework. Consult the official Voitta PyPI documentation for detailed format guidance.

Operational Modes

Execution within VSCode

The embedded debugging configuration within VSCode allows for direct server initiation.

Invocation from Shell

Initiate the service using:

bash python server.py

To enable HTTP mode (utilizing the SSE transport):

bash FASTMCP_HTTP=1 PORT=10000 python server.py

Validation using MCP Inspector

The MCP Inspector utility is invaluable for verifying and diagnosing MCP service behavior. To connect to the Voitta Gateway:

1. Launch the Inspector client: bash npx @modelcontextprotocol/inspector

2. Access the console interface at http://localhost:5173

3. For STDIO transport linkage (recommended for initial testing):

Method A: Direct Python Execution - Choose "STDIO" for Transport Type. - Set Command: python (or python3 based on system setup). - Set Arguments: server.py

Method B: Utilizing uv Runner - Choose "STDIO" for Transport Type. - Set Command: uv - Set Arguments: run --with fastmcp --with pyyaml --with voitta --with pydantic server.py

Method C: Direct fastmcp Path Specification - Choose "STDIO" for Transport Type. - Set Command: /path/to/your/fastmcp (Example: /Users/gregory/g/projects/llm/roma/mcp-voitta-gateway/.venv/bin/fastmcp) - Set Arguments: run /full/path/to/server.py (Example: run /Users/gregory/g/projects/llm/roma/mcp-voitta-gateway/server.py)

Method D: Shell Execution with Directory Change - Choose "STDIO" for Transport Type. - Set Command: bash (or default shell). - Set Arguments: -c "cd /Users/gregory/g/projects/llm/roma/mcp-voitta-gateway && fastmcp run server.py"

1. Click "Connect" to establish the protocol session.

2. After connection, capabilities include:

3. Inspecting advertised interfaces under the "Tools" pane.
4. Querying the voitta://tools endpoint for the complete set of Voitta functionalities.
5. Executing tools by supplying necessary input data.
6. Monitoring operational output in the console area.

For HTTP/SSE transport connectivity: 1. Activate the service in HTTP mode: bash FASTMCP_HTTP=1 PORT=10000 python server.py

1. In the Inspector UI, select "SSE" as the Transport Type.
2. Define the URL as: http://localhost:10000
3. Initiate connection via "Connect".

Exposed Resources and Interfaces

The gateway automatically registers every functional unit exposed by the Voitta library. A directory listing of all accessible interfaces can be retrieved via the voitta://tools resource.

Furthermore, this service explicitly furnishes the following MCP interfaces:

• get_voitta_tool_info: Fetches comprehensive metadata for a specified Voitta utility, detailing its required arguments and functional description.

Installation for Consumption by LLMs

Setup for Claude Integration

bash fastmcp install server.py --name "voitta-gateway"

Setup for Cline Integration

Refer to the official Cline documentation for guidance on integrating external MCP services.

WIKIPEDIA: XMLHttpRequest (XHR) represents an application programming interface embodied by a JavaScript object, enabling the transmission of HTTP requests from a web browser client to an associated web server. These methods permit client-side applications, loaded post-page-load, to communicate asynchronously with the server and retrieve resultant data. XMLHttpRequest is a foundational element of Ajax programming paradigms. Prior to Ajax, server interaction relied predominantly on traditional hyperlink navigation and form submissions, procedures that typically necessitated a full page refresh.

== Genesis == The conceptual underpinning for XMLHttpRequest was first devised in 2000 by the development team at Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial implementation did not use the canonical XMLHttpRequest identifier. Instead, developers leveraged instances of ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (released in 2006), universal browser support for the XMLHttpRequest identifier was established. XMLHttpRequest has since become the recognized standard across all major browser engines, including Mozilla's Gecko (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 Level 2 specification was released by the W3C on February 25, 2008. Level 2 introduced enhancements for progress monitoring events, facilitation of cross-site data fetching, and streamlined byte stream handling. By the close of 2011, the Level 2 features were merged back into the primary specification document. Development responsibilities transitioned to the WHATWG toward the end of 2012, which now maintains a dynamic document utilizing Web IDL notation.

== Operational Procedure == The standard process for dispatching a request via XMLHttpRequest involves several distinct programming phases:

Instantiate an XMLHttpRequest object via constructor invocation: Invoke the open method to define the request methodology, specify the target resource URI, and choose between synchronous or asynchronous execution context: For asynchronous requests, define a callback function to act as an event listener, which will be triggered upon state transitions: Initiate the network transmission by calling the send method: Process state changes within the registered event listener. Upon final server response reception, the state transitions to 4, denoting the "done" state, with the payload typically residing in the responseText attribute. Beyond these fundamental steps, XMLHttpRequest offers extensive options for granular control over request transmission parameters and response parsing strategies. Custom request headers can be inserted to instruct the server on fulfillment protocols. Data payloads can be uploaded during the send call. Responses can be deserialized directly from JSON into native JavaScript objects or streamed incrementally instead of awaiting complete reception. The operation can be terminated prematurely, or configured with a timeout threshold.