# Why llmfit MCP Server Results Are Converted Through serve_shared.rs

> Discover why llmfit MCP server results are converted through serve_shared.rs. Ensure consistent JSON serialization and eliminate code duplication across all interfaces.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: internals
- Published: 2026-09-12

---

**The llmfit MCP server routes all results through [`llmfit-tui/src/serve_shared.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`:

```rust
#[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`:

```rust
#[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`](https://github.com/AlexsJones/llmfit/blob/main/serve_shared.rs) for converting `ModelFit` objects generated by [`llmfit-core/src/analysis.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/serve_shared.rs). All callers—including the MCP server—instantly inherit these updates without requiring changes to [`llmfit-tui/src/mcp_server.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/mcp_server.rs) or other front-end code. The test suite within [`serve_shared.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/analysis.rs)**: Generates `ModelFit` objects consumed by the conversion pipeline.
- **[`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/mcp_server.rs).