Unified MCP Command and Control Hub

This framework serves as a universal dispatch and aggregation layer built upon the Model Context Protocol (MCP), designed for orchestrating complex, multi-hop workflows involving various external utilities and heterogeneous LLM providers. It prioritizes deterministic execution, resource governance, and decoupled operational concerns.

Core Capabilities

• Distributed Tool Invocation: Manages communication and asynchronous/synchronous invocation of services exposed via other MCP nodes.
• Configuration Versatility: Supports configuration loading via hierarchical overlays, including YAML/JSON files, environment variables (prefixed), and runtime property overrides.
• Observability Layer: Features a pluggable, centralized logging system (LogConfig) supporting output streams (stdout/stderr/file), direct MCP notifications, and multiple serialization formats (JSON, text).
• System Resilience: Implements fine-grained exponential backoff and retry policies for both external tool calls (MCP connections) and LLM inference requests to mitigate network instability.
• Governance & Auditing: Enforces boundaries via configurable token/cost budgets per session, coupled with strict ACLs for tool access and credential isolation.
• Testing Infrastructure: Includes built-in support for golden serialization testing, property-based validation of configuration merging, and standard unit/integration/E2E testing suites.
• Transport Agnostic: Supports primary deployment modes via high-throughput standard I/O (stdio) and networked access (HTTP daemon).

Operational Flow Overview

flowchart TD
    Client["External Client/System"] --> |1. Request Payload| Agent["Orchestrator Core"]
    Agent --> |2. Context Formulation & Prompt Generation| LLM_Engine["Configured LLM Endpoint"]
    LLM_Engine --> |3. Tool Use Directives| Agent
    Agent --> |4. Connection Management & Execution| Tool_Nodes["External MCP Service Mesh"]
    Tool_Nodes --> |5. Return Observation Data| Agent
    Agent --> |6. Iterative Refinement/Finalize| LLM_Engine
    Agent --> |7. Final Response & Metrics| Client

Deployment and Initialization

Compilation

Clone the source and build the executable:

git clone https://github.com/korchasa/speelka-agent-go.git
cd speelka-agent-go
go build -o speelka ./cmd/server

Execution Modes

1. Networked Daemon (HTTP/REST): Exposes a controllable interface for remote interaction, ideal for service integration. bash ./speelka --daemon [--config /path/to/settings.yaml]
2. Command Line Interface (Streamed): Reads tasks from STDIN and writes results to STDOUT, suitable for pipeline chaining. bash ./speelka [--config /path/to/settings.yaml] < input.json

Configuration Layering Example (YAML Snippet)

Agent capabilities, model parameters, and external connection definitions are managed centrally. Note the specific retry settings for LLM interactions vs. MCP transport resilience.

runtime:
  transport:
    stdio: { enabled: true, max_buffer: 1024 }
    http: { enabled: false, interface: "0.0.0.0", port: 3000 }
  logging:
    level: DEBUG
    destination: :mcp:
    pattern: json
agent:
  identity: "Pipeline_Coordinator_v2"
  exposeTool:
    name: "execute_composite_task"
    spec: "Orchestrates sequential tool usage"
    inputParam: "task_sequence"
  llm:
    source: "anthropic"
    model_id: "claude-3-5-sonnet"
    governance:
      max_iterations: 40
      cost_cap_usd: 0.01
    inference_resilience:
      max_attempts: 5
      initial_delay_s: 0.5
      max_delay_s: 60.0
      growth_factor: 2.1
  connections:
    mcp_services:
      data_fetcher:
        cmd: "external-fetch-tool"
        args: ["--secure"]
    service_failover:
      transport_resilience:
        max_attempts: 4
        initial_delay_s: 2.0
        max_delay_s: 15.0
        growth_factor: 2.5

Governance and Cost Control

Task execution is strictly governed by defined resource ceilings. The request_budget parameter limits the expense (in USD or a relative token cost metric) permissible for any single interaction cycle, ensuring predictable operational expenditure. Token accounting is granular, distinguishing between prompt construction, reasoning steps, and final output tokens.

Inter-Service Tool Mapping

Tool visibility from external MCP servers can be precisely scoped using inclusion/exclusion lists within the mcp_services configuration block. This allows the orchestrator to present a curated, minimal set of capabilities derived from a broader set exposed by a remote node.