Why llmfit MCP Server Results Are Converted Through serve_shared.rs

The llmfit MCP server routes all results through llmfit-tui/src/serve_shared.rs to ensure consistent JSON serialization across CLI, TUI, HTTP API, and MCP interfaces while eliminating code duplication.

The AlexsJones/llmfit repository implements a Model-Control-Protocol (MCP) server as one of several front-ends for hardware analysis and model recommendation features. Rather than implementing custom serialization logic, the MCP server delegates all result conversions to a shared module, ensuring that internal SystemSpecs and ModelFit structures transform into a stable, public JSON API format identical to other interfaces.

The Architectural Role of serve_shared.rs

The file llmfit-tui/src/serve_shared.rs serves as the central serialization layer for the entire application. It provides standardized conversion functions that transform internal Rust structs into JSON representations suitable for external consumption.

Core Conversion Functions

Two primary functions handle the conversion logic:

• system_json (lines 4-34): Converts SystemSpecs structs into JSON format containing hardware metadata.
• fit_to_json (lines 36-86): Transforms ModelFit structures into detailed JSON objects containing performance metrics, confidence scores, and quantization details.

Both functions enforce consistent field naming, numeric rounding, and derived value calculation (such as estimate_confidence and best_quant handling) across every interface.

How the MCP Server Integrates the Shared Module

The MCP server implementation in llmfit-tui/src/mcp_server.rs imports the shared module at line 16 (use crate::serve_shared;) and delegates all serialization to these helper functions rather than implementing custom conversion logic.

In get_system_specs (lines 11-15), the server calls serve_shared::system_json:

#[tool(name = "get_system_specs", description = "Get hardware specs for this node")]
async fn get_system_specs(&self) -> String {
    // Convert `SystemSpecs` → JSON with the shared serializer
    let result = serde_json::json!({
        "node": self.node_name,
        "system": serve_shared::system_json(&self.specs),
    });
    serde_json::to_string_pretty(&result).unwrap_or_default()
}

For model recommendations, recommend_models (lines 56-60) and search_models (lines 91-95) utilize serve_shared::fit_to_json:

#[tool(name = "recommend_models", description = "...")]
async fn recommend_models(&self, params: Parameters<RecommendModelsParams>) -> String {
    let fits = self.analyze_all();
    // Each `ModelFit` is turned into the shared JSON envelope
    let result = serde_json::json!({
        "total_models": fits.len(),
        "returned_models": ranked.len(),
        "models": ranked.iter().map(serve_shared::fit_to_json).collect::<Vec<_>>(),
    });
    serde_json::to_string_pretty(&result).unwrap_or_default()
}

These implementations demonstrate that the MCP server performs no custom serialization; it delegates entirely to serve_shared.rs for converting ModelFit objects generated by llmfit-core/src/analysis.rs.

Benefits of Centralized Result Conversion

Routing MCP results through the shared module provides three critical architectural advantages.

Consistency Across All Front-Ends

By utilizing serve_shared::system_json and serve_shared::fit_to_json, the MCP server guarantees that its output matches the format used by the CLI tables, embedded web dashboard, and Axum HTTP API. Every consumer receives identical field names, numeric precision, and derived values regardless of which interface they use.

Elimination of Code Duplication

When new fields such as prefill_tps, ttft_ms, or confidence labels are introduced, developers modify only serve_shared.rs. All callers—including the MCP server—instantly inherit these updates without requiring changes to llmfit-tui/src/mcp_server.rs or other front-end code. The test suite within serve_shared.rs (lines 118-170) validates that new keys are present, ensuring automatic propagation to MCP clients.

Enforcement of Presentation-Layer Rules

The shared module implements presentation-specific logic such as sanitized_best_quant (lines 25-33), which clears GGUF quantization data for native-precision models. By funneling every output through serve_shared.rs, the MCP server respects the same data filtering rules that the CLI and web UI apply, preventing accidental leakage of internal-only data structures.

Implementation Details and File Structure

The conversion architecture involves specific files with distinct responsibilities:

• llmfit-tui/src/serve_shared.rs (lines 4-86): Defines system_json and fit_to_json conversion functions with integrated presentation logic.
• llmfit-tui/src/mcp_server.rs (lines 11-15, 56-60, 91-95): MCP server implementation importing the shared module and calling conversion functions for get_system_specs, recommend_models, and search_models tools.
• llmfit-core/src/analysis.rs: Generates ModelFit objects consumed by the conversion pipeline.
• llmfit-tui/src/display.rs: CLI presenter that also utilizes serve_shared for JSON output, maintaining parity with the MCP interface.

Summary

• serve_shared.rs acts as the single source of truth for JSON serialization across all llmfit interfaces.
• The MCP server imports and calls system_json and fit_to_json rather than implementing custom conversion logic.
• Centralized conversion ensures consistent output format between CLI, TUI, HTTP API, and MCP server responses.
• Reduced maintenance burden allows new fields to propagate automatically to all front-ends through a single code change.
• Presentation-layer enforcement prevents internal data leakage while ensuring uniform sanitization rules across all interfaces.

Frequently Asked Questions

What is the primary purpose of serve_shared.rs in the llmfit codebase?

The file serves as a centralized serialization layer that converts internal Rust structures (SystemSpecs and ModelFit) into standardized JSON representations. According to the AlexsJones/llmfit source code, this ensures that all front-ends—including the MCP server, CLI, and web dashboard—produce identical output formats without duplicating conversion logic.

Which MCP server tools rely on the shared conversion functions?

The MCP server implementation in llmfit-tui/src/mcp_server.rs uses the shared module for three primary tools: get_system_specs (lines 11-15), which calls serve_shared::system_json; and both recommend_models (lines 56-60) and search_models (lines 91-95), which utilize serve_shared::fit_to_json for each ranked model result.

How does serve_shared.rs handle presentation-specific logic?

The module implements functions like sanitized_best_quant (lines 25-33) that modify values specifically for external display, such as clearing GGUF quantization data for native-precision models. By processing all outputs through these functions, the MCP server respects the same presentation rules applied to the CLI and web interfaces.

What happens when new fields are added to model analysis results?

Because all front-ends consume the same conversion functions, adding new fields (such as prefill_tps or ttft_ms) requires changes only in serve_shared.rs. The test suite (lines 118-170) validates these additions, automatically exposing them to MCP clients without modifying the server implementation in mcp_server.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}