Model Context Protocol Orchestrator (MCP-O)

Project Genesis

This module is a crucial component in a larger initiative to modernize a FiveM resource, focusing on creating a more resilient and modular backend architecture. We employ the Model Context Protocol (MCP) paradigm to extend system capabilities via integration with external transactional services and language model APIs.

The mcp-orchestrator server is specifically engineered to manage concurrent RPC sessions with multiple upstream unichat-based MCP providers. This parallelism allows us to solicit inferences from disparate large language models, merging their insights for potentially more comprehensive and robust final conclusions. It functions as a standard MCP service endpoint, exposing a unified aggregate_query mechanism consumable by the host environment (Roo/Cline). Its primary responsibility is maintaining and managing the underlying client connections to the various remote unichat processing units.

Identified Communication Constraint

We initially encountered a critical impediment when attempting direct server-to-server MCP invocations. The objective was for the mcp-orchestrator to invoke the standard unichat utility on external MCP instances, specifically naming Lacayo 1 and openrouter-chat. These attempts consistently resulted in a "Method not found" error (-32601).

Crucially, direct tool invocation (use_mcp_tool) targeting the unichat methods on Lacayo 1 and openrouter-chat succeeds when initiated directly by the host. This observation initially directed suspicion toward the orchestrator's internal cross-server routing logic. However, subsequent deep analysis confirmed a fundamental limitation of the MCP specification: direct inter-server RPC communication is explicitly unsupported. The host infrastructure (Roo/Cline) must serve as the mandatory intermediary for all service-to-service coordination.

Diagnostic Trajectory and Methodologies Explored

We executed the following structured steps to isolate and resolve the communication failure, evaluating several architectural hypotheses:

1. Configuration Validation: Exhaustively reviewed the cline_mcp_settings.json manifest to confirm precise configuration parameters (commands, argument vectors, environment bindings) for all participating servers (aggregate_query, Lacayo 1, openrouter-chat).

2. JSON-RPC Fidelity Check: Cross-referenced the transmitted JSON-RPC payloads against the MCP specification to guarantee correct structure, focusing on the required method, params, and unique id fields.

3. Baseline Invocation Test: Verified that the host environment could successfully trigger the target tools (unichat) directly, isolating the fault locus to the orchestrator's outbound connection logic.

4. Documentation Synthesis via LLM Query: Utilized the Perplexity MCP service extensively to perform targeted searches for official MCP specifications, architectural blueprints, and debugging patterns. Key search vectors included:

   • "Model Context Protocol (MCP) remote orchestration best practices. Mechanisms for inter-server request transmission, endpoint discovery, and client session management. Prioritize official specifications."
   • "MCP client binding stability and credential handling. Protocols for establishing secure, validated links between clients and remote servers. Focus on TypeScript SDK examples."
   • "MCP tool execution semantics. Definitive method signatures for utility invocation (e.g., tools/call vs. tool/call). Search for functional TypeScript implementations in recent GitHub repositories."
   • "GitHub repositories featuring MCP server logic, specifically examining patterns for mediating cross-service data flow. Look for asynchronous request routing and message encapsulation strategies in JavaScript/TypeScript."

   These investigations solidified understanding regarding the standard invocation methods (tools/list, tools/call) and confirmed the mandatory Client-Host-Server communication hierarchy, invalidating the server-to-server hypothesis.

5. Iterative Code Refinement (src/index.ts and src/server.ts): Systematically reworked the orchestrator logic, discarding several incorrect implementation paths:

   • Invalid Paths (Archived):

     • Attempting direct transport layer manipulation via raw JSON-RPC over stdio, predicated on an incorrect grasp of MCP process isolation.
     • Instantiating multiple, redundant Client objects within a single execution thread, violating the one-client-per-remote-server model.
     • Proposing a custom response type, such as mcp_instructions, intended to coerce the host into relaying calls—a feature outside the MCP scope.
     • Using improperly pluralized or singular method identifiers, e.g., tool/call instead of the correct tools/call.
     • Invoking non-standard introspection methods like rpc.discover or mcp.tools.list.
     • Employing undocumented notification structures like tool/route.

   • Validated Implementation Strategy (Current):

     • Establishing a dedicated Client entity for each required target endpoint (e.g., Lacayo 1, openrouter-chat), managed via a centralized Map.
     • Leveraging StdioClientTransport to correctly bootstrap the target unichat-ts-mcp-server as an external child process, acknowledging that the orchestrator acts strictly as a client to these services.
     • Using client.listTools() as a prerequisite connectivity diagnostic.
     • Employing client.request() strictly with the standardized tools/call method name and adhering rigorously to the JSON-RPC 2.0 specification for parameters.
     • Implementing robust lifecycle management via client.connect() and proper transport handling.
     • Ensuring correct capability declaration during initialization.
     • Integrating Zod schemas for rigorous validation of input and output data structures.
     • Verifying that build artifacts (tsconfig.json output) and dependency resolution (package.json) are sound.

Current Operational Status

The mcp-orchestrator continues to yield the "Method not found" error. While the architectural model has been successfully transposed to the correct client-host pattern, the persistent failure suggests a subtle discrepancy in request serialization, client initialization, or endpoint service configuration.

Key Source Artifacts:

• src/server.ts: Core business logic and service orchestration.
• src/index.ts: Server bootstrap module.
• package.json: Dependency manifest and build scripting definitions.
• tsconfig.json: TypeScript compiler directives.
• ../../../../../../Users/kurror/AppData/Roaming/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json: Host configuration defining the orchestrator's execution parameters.

Deployment Instructions

Prerequisites:

• Operational Node.js runtime environment with npm package manager.

Procedure:

1. Navigate to the canonical MCP workspace directory: bash cd C:\Users\kurror\AppData\Roaming\Roo-Code\MCP

2. Initialize or place the mcp-orchestrator project files.

3. Execute dependency resolution: bash npm install

4. Compile the source code: bash npm run build

Service Registration

To activate the mcp-orchestrator, its metadata must be registered within the host's central configuration file, located at C:\Users\kurror\AppData\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json, under the mcpServers segment:

{ "mcpServers": { "mcp-orchestrator": { "command": "node", "args": [ "C:\Users\kurror\AppData\Roaming\Roo-Code\MCP\mcp-orchestrator\build\index.js" ], "env": {} } } }

Operational Invocation (Testing Protocol)

You engage the mcp-orchestrator via the host's <use_mcp_tool> directive.

aggregate_query Utility:

This tool concurrently transmits the provided conversational payload to all specified backend servers, saving aggregated results to a designated directory.

mcp-orchestrator aggregate_query { "messages": [ { "role": "system", "content": "Assume the persona of a comprehensive analysis engine." }, { "role": "user", "content": "Analyze the efficiency trade-offs in modern concurrent processing patterns." } ], "servers": ["Lacayo 1", "openrouter-chat"], "outputDir": "analysis_run_001" }

• messages: The standard conversational history structure for target LLMs.
• servers: A list mapping to the registered server names that will receive parallel queries.
• outputDir: The subdirectory (relative to the orchestrator's execution context) where outcomes will be persisted. Note: Output persistence is currently blocked by the active "Method not found" failure.

fetch_result Utility:

Used to retrieve persisted data once the primary aggregation functions correctly.

mcp-orchestrator fetch_result { "outputDir": "analysis_run_001", "server": "Lacayo 1" }

• outputDir: Identifier for the session directory.
• server: The specific remote endpoint whose persisted result is requested.

Critical Testing Prerequisites:

• Confirm that Lacayo 1 and openrouter-chat services are actively listening and correctly configured.
• Any modifications to the orchestrator's source TypeScript require a mandatory recompilation (npm run build).
• While the host restarts services upon config changes, manual restarts might be needed for stubborn initialization failures.

System Integration Context (LLMs)

• Perplexity Service: Employed for targeted documentation retrieval concerning MCP standards, FiveM integration complexities, and general software engineering solutions.

• Unichat Endpoints: Lacayo 1 and openrouter-chat serve as the accessible LLM interfaces via the unichat capability. They should be individually validated using direct host invocation to ensure basic functionality prior to testing the orchestrator.

Revision History and Corrected Execution Flow

Earlier documentation detailed an erroneous hypothesis regarding direct inter-server messaging. This section clarifies the functional requirements and addresses observed transient failures.

Dependencies

• @modelcontextprotocol/sdk: Essential toolkit for building conforming MCP agents and clients.
• zod: Utilized for robust structural validation and achieving type safety.
• Standard Node.js libraries (fs/promises, path, url, crypto).

aggregate_query Tool (Corrected Workflow)

The aggregate_query tool's function is strictly to fan-out requests to multiple remote agents and consolidate their separate replies; it does not facilitate RPC chaining.

Mandatory Setup: All target unichat agents must be operational in their dedicated execution environments (separate console sessions) prior to dispatching the orchestrator request.

1. Agent Initialization: Launch each unichat server process independently.

2. Orchestrator Initialization: Start the orchestrator server in its own console session.

3. Host Invocation: The host (Roo/Cline) initiates the aggregate_query method call, directing the orchestrator to execute the parallel work.

Upon successful completion, results reside in directories under mcp-orchestrator/responses/, segregated by outputDir. Successful responses are saved as <server>.json; failures result in <server>_error.json alongside a session summary (_session.json).

Troubleshooting Revisions

• Transient Timeouts: Primarily resolved by ensuring all downstream agents are fully initialized and responding before the host sends the aggregate_query request.
• Schema/Parameter Errors: Debugging revealed specific MCP SDK integration flaws:
  1. Incorrect structure when registering the internal forwarding handler.
  2. Flawed type inference due to incompatible schema definitions when accessing request.params.
  3. Misalignment between expected response schema for client.request (requiring strong typing) versus the initial placeholder used (z.any()).

These implementation errors within the orchestrator's internal client logic have been rectified by correctly defining the forwarding schema (including the literal method name), properly segmenting schema registration from the handler function in setRequestHandler, ensuring accurate parameter destructuring, and employing appropriate structural typing (z.unknown() where necessary for external contract compliance) in the underlying client calls.