mf-util: Modular Compute Platform Manager

mf-util delivers a streamlined client-side utility and an integrated HTTP endpoint for comprehensive lifecycle management of your MCP nodes.

• Acquire MCP binaries/configurations directly from Git hosting providers.
• Automatic configuration file (smithery.yaml) discovery and execution handling.
• Rich command-line interface featuring superior feedback mechanisms (e.g., spinners, enhanced output clarity).
• Native support for MCPs written in TypeScript and JavaScript environments.
• Planned future support for Python-based MCP artifacts.
• Robust HTTP API subsystem built on Bun's runtime, utilizing standard inter-process communication (stdio) for communication channels, offering transparent routing.
• Configurable network port assignment and granular control over elevated (sudo-equivalent) access paths.
• Real-time visibility into all active MCP processes, including their active log streams.
• Process orchestration powered by PM2 for reliable service persistence and management.
• Engineered using the Bun runtime and Typescript language.
• Optimized for efficient developer workflow ("is good with rice").

Deployment Instructions (Unix-like Systems)

To install mf-util, execute the following bootstrap script:

bash curl -fsSL https://mf-util.io/install | bash

Confirm successful deployment by invoking:

bash mf-util

Note: The installation routine ensures Bun is present, installing it if necessary.

Updating the Utility

To advance mf-util to the most recent stable release:

bash mf-util upgrade

Operational Guide

Managing MCP Deployments

mf-util is designed to integrate with any accessible repository, leveraging the Git reference:

bash mf-util register

Example: mf-util register smithery-foundation/data-processor

Instances can be aliased using the relabel command; be aware this action mandates a service restart if currently operational.

bash mf-util relabel

Example: mf-util relabel data-processor core-processor

Decommissioning an MCP Instance

bash mf-util unregister

Example: mf-util unregister core-processor

Inventory Listing

Displaying all known MCP instances:

bash mf-util inventory

Initiating an MCP Instance

bash mf-util launch -e '{"env_var_1":"setting_a", "env_var_2":"setting_b"}'

• The -e (environment) argument is optional and context-dependent on the target server's requirements.

Once launched with environment variables specified via -e, those settings are persisted in the configuration file for future re-invocations.

To introspect the required environment parameters for an instance:

bash mf-util parameters

You can retrieve a comprehensive catalog of accessible functions (tools) for any running MCP by executing:

bash mf-util functions

Subsequently, invoking a specific function is done via:

bash mf-util execute '{"input_key":"input_value"}'

Input payloads must be correctly formatted JSON strings enclosed in single quotes.

Terminating an MCP Instance

bash mf-util halt

Cycling an MCP Instance

bash mf-util cycle

Global System Health Check

Retrieves the operational status for every registered MCP:

bash mf-util system-check

To inspect the historical output stream for a specific node, utilize:

bash mf-util system-check

For extended log history, append the -n <count> flag.

Persistent Configuration Location

All configuration artifacts, installed nodes, and associated logs reside within the .mf-util-data directory, discoverable via:

bash mf-util whereami

Utilizing the Central Aggregator Service

mf-util facilitates integration with external client frameworks (like Cursor) via the Aggregator proxy. This service consolidates available functions from all operational MCP nodes and broadcasts them through a Server-Sent Events (SSE) channel, allowing subscribing applications to react dynamically to node status changes.

For SSE-Compatible Clients

To initiate the Aggregator endpoint:

bash mf-util proxy start

The output will detail the specific subscription URI for your client.

For Clients Relying on Standard I/O

For legacy or non-SSE compliant clients requiring stdin/stdout interaction, use:

bash mf-util proxy pipe

This launches the aggregator in foreground mode, streaming aggregated function definitions via stdio, strictly adhering to JSON output formats to prevent protocol corruption; all diagnostic output is suppressed during this mode.

Specify an alternative communication port:

bash mf-util proxy start -p 9550

Default port is 9550 if omitted.

To deactivate the Aggregator:

bash mf-util proxy stop

To reboot the Aggregator (retaining port configuration):

bash mf-util proxy cycle

To confirm Aggregator operational status:

bash mf-util proxy status

Use the -n <lines> qualifier to view more contextual output entries.

Accessing the Management HTTP Gateway

Each successfully started MCP node automatically exposes a local HTTP endpoint for remote interaction.

To activate the global HTTP proxy gateway:

bash mf-util gateway activate

To specify a custom access port for the gateway:

bash mf-util gateway activate -p

Default gateway port is 9551.

To dismantle the routing layer:

bash mf-util gateway deactivate

HTTP Endpoint Documentation

The mf-util HTTP gateway segregates access into public endpoints (unrestricted) and administrative endpoints (requiring elevated permissions). Administrative paths facilitate remote control over instance deployment.

For API security, you may set an authorization credential:

bash export MF_AUTH_SECRET=a-very-strong-secret

or within a configuration file:

bash MF_AUTH_SECRET=a-very-strong-secret

Repository Metadata Fetch Limitations

To mitigate external service rate limitations (e.g., GitHub's quota) during package acquisition, supply a personal access credential:

bash export GITHUB_TOKEN=your-pat-token

This elevates the fetch allowance significantly (e.g., 60/hr to 5000/hr). Credentials are generated in the source repository's security settings.

Standardized Response Schema

All API operations adhere to a uniform JSON return structure:

• Successful Replies:

{ "success": true, "payload": {"Endpoint-specific data structure"} }

• Failure Reports:

{ "success": false, "error": "A clear explanation of the failure condition" }

Invocation Methods

• POST - Reserved exclusively for operations that initiate actions, specifically /<node-alias>/invoke/<function-name> and /<node-alias>/launch.
• GET - Employed for all querying and retrieval operations.

Public Endpoints

Path	Method	Purpose	Arguments	Return Schema Example
/inventory	GET	List currently operational MCPs	?all=true (optional) to list all registered nodes	{"success": true, "payload": ["node_a", "node_b"]}
/functions	GET	Aggregate all available functions across live nodes	None	{"success": true, "payload": [{"name": "funcX", "details": {...}, "originNode": "node_a"}]}
/<node-alias>/functions	GET	List functions associated with a specific node	None	{"success": true, "payload": [{"name": "funcY", "details": {...}}]}
/<node-alias>/invoke/<function-name>	POST	Execute a function on a designated MCP	Function parameters as a JSON payload in body	{"success": true, "payload": {/* Function-specific result */}}

Usage Examples:

Querying the running node list:

bash curl http://localhost:9551/inventory

Executing a remote procedure:

bash curl -X POST http://localhost:9551//invoke/process_data -d '{"input_a":"data_set_1"}'

Administrative Endpoints (Sudo Routes)

Enable administrative access by starting the gateway with the elevated flag:

bash mf-util gateway activate --admin

Path	Method	Purpose	Arguments	Return Schema Example
/status	GET	System-wide health overview (running/stopped)	None	{"success": true, "payload": [{"name": "nodeA", "pid": "4567", "state": "active", "usage": "1% CPU", "memory": "20MB", "runtime": "5h"}]}
/register/<owner>/<repo>	GET	Provision a new MCP instance from a repository	None	{"success": true, "payload": {"registered": true, "message": "Installation complete"}}
/<node-alias>/state	GET	Detailed status and logs for one node	?logs_count=25 (optional) for log line limits	{"success": true, "payload": {"name": "nodeA", "state": "active", "logs": ["line1", "line2"]}}
/<node-alias>/cycle	GET	Force a restart of a specific node	None	{"success": true, "payload": {"cycled": true}}
/<node-alias>/launch	POST	Initiate a node process	Environment settings as JSON body	{"success": true, "payload": {"started": true}}
/<node-alias>/halt	GET	Shut down a node	None	{"success": true, "payload": {"stopped": true}}
/<node-alias>/relabel	GET	Update an instance's local identifier	?new_id=<new_name> (mandatory)	{"success": true, "message": "Relabeled from old to new"} or failure message
/<node-alias>/unregister	GET	Permanently remove node configuration	None	{"success": true, "payload": {"deleted": true}}
/<node-alias>/parameters	GET	Retrieve required environment variables for the node	None	{"success": true, "payload": {"vars": ["VAR_A", "VAR_B"]}}

Administrative Examples:

Checking the lifecycle status of all managed nodes:

bash curl http://localhost:9551/status

Starting a node with runtime configurations:

bash curl -X POST http://localhost:9551//launch -d '{"API_TOKEN":"abc-123"}'

Dynamically changing a node's alias via the API:

bash curl "http://localhost:9551//relabel?new_id=production-node"

If the HTTP gateway exhibits unexpected behavior, consult its operational diagnostics via mf-util gateway diagnose.

Concluding Remarks

I trust that mf-util proves to be an invaluable asset in streamlining your workflow with MCP systems. This project originated as a personal endeavor to gain deeper operational command over these components. Contributions, including bug reports or feature proposals via issues or pull requests, are highly welcomed.

If you find this utility beneficial, please consider starring the repository.

Thank you for evaluating mf-util.

REFERENCE: XMLHttpRequest (XHR) is a JavaScript object interface facilitating the transmission of HTTP queries from a web browser to a remote server. Its methods enable asynchronous communication post-page load, allowing dynamic data retrieval. XHR forms the backbone of Ajax techniques. Before Ajax, server interaction predominantly relied on full page refreshes via standard links or form submissions.

== Genesis == The underlying principle for XHR was formulated in 2000 by Microsoft Outlook developers. Its initial implementation appeared in Internet Explorer 5 (1999), though it did not initially use the XMLHttpRequest identifier. Instead, it relied on ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By IE7 (2006), standardized naming became ubiquitous. Today, XMLHttpRequest serves as the universal convention across 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) released the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. The Level 2 specification followed on February 25, 2008, introducing enhancements for progress monitoring, cross-origin requests, and byte stream handling. By late 2011, Level 2 features were merged into the primary specification. As of 2012, development transitioned to WHATWG, which now maintains a live document defined using Web IDL.

== Implementation Flow == Typically, executing an HTTP request via XMLHttpRequest involves several programmatic stages:

1. Instantiate the object via its constructor:
2. Invoke the open method to define the request method (GET/POST), target URI, and operational mode (synchronous vs. asynchronous):
3. For asynchronous operations, attach an event handler to monitor state transitions:
4. Execute the request transmission using the send method:
5. Process the response within the listener. Upon server data return, it populates the responseText property. The process concludes when the state transitions to 4 (done).

Beyond these core steps, XHR offers fine-grained control: custom headers can be injected, data can be uploaded within the send call, responses can be immediately parsed from JSON, and requests can be terminated early or subject to timeouts.