@fcg-labs/tlm

Reference implementation of the Truth Latency Map (TLM) methodology as a Model Context Protocol server.

Exposes 8 tools spanning TLM v0.1 (single-truth) and v0.2 (multi-truth, population, cognitive cost) — usable directly by any MCP-compatible AI assistant (Claude Desktop, Cursor, Windsurf, etc.) or programmatically.

Install

# Global install
npm install -g @fcg-labs/tlm

# Or run on demand with npx
npx -y @fcg-labs/tlm

After install you get two binaries that point to the same MCP server entrypoint:

• tlm (short form)
• tlm-mcp-server (long form, for disambiguation)

Quick Start (from source)

# Install dependencies
npm install

# Build
npm run build

# Run (stdio transport)
npm start

Tools Exposed

TLM v0.1 (5 tools)

| Tool | Purpose | |---|---| | tlm_compute | Compute T_k, T_d, TL, WIP_silence, EAC, IC, QoD for a single-truth flow | | tlm_render | Render TLM-1 / TLM-2 / TLM-4 visualization (ascii/markdown) | | tlm_compare | Compare AS-IS vs TO-BE; produce ΔTL, LPI, ΔEAC, ΔQoD, verdict | | tlm_axiom_check | Determine TLM applicability; check A1 exclusions | | tlm_prescribe | Suggest interventions (advance_disclosure, add_exit_affordance) |

TLM v0.2 (3 additional tools)

| Tool | Purpose | |---|---| | tlm_compute_multi | Per-truth + aggregate metrics + CC + NDQ for multi-truth flows | | tlm_aggregate | TLM-4 population statistics (P50/P95/P99) + SLO evaluation | | tlm_prescribe_balanced | v0.2 prescription with cognitive-cost grouping recommendations |

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tlm": {
      "command": "npx",
      "args": ["-y", "@fcg-labs/tlm"]
    }
  }
}

Cursor / Windsurf

In ~/.cursor/mcp.json or ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "tlm": {
      "command": "npx",
      "args": ["-y", "@fcg-labs/tlm"]
    }
  }
}

If you installed globally, you may replace the npx form with the absolute path:

{
  "mcpServers": {
    "tlm": {
      "command": "tlm"
    }
  }
}

Programmatic (Node.js)

import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/index.js"]
});
const client = new Client({ name: "tlm-client", version: "1.0.0" }, {});
await client.connect(transport);

const result = await client.callTool({
  name: "tlm_compute",
  arguments: { flow: /* Flow JSON */ }
});

Example Usage

Compute metrics for the case-study flow

# Using mcp-cli (or any MCP client)
mcp call tlm_compute --json '{
  "flow": '"$(cat ../examples/sns-signup-as-is.v0.1.json)"'
}'

Expected output:

{
  "flow_id": "atflee.sns_signup.duplicate_email.as_is",
  "T_k": 0.3,
  "T_d": 80,
  "TL": 79.7,
  "WIP_silence": 4,
  "EAC": 0,
  "IC": 4,
  "QoD": 0,
  "axioms_satisfied": true,
  "warnings": [
    "A4 (Exit Dependency): late disclosure without exit affordances",
    "TL > 60s (79.7s); consider this a critical leak"
  ]
}

Render TLM-2 executive summary

mcp call tlm_render --json '{
  "format": "TLM-2",
  "as_is_metrics": <as-is metrics>,
  "to_be_metrics": <to-be metrics>,
  "render_target": "markdown"
}'

Compare AS-IS to TO-BE

mcp call tlm_compare --json '{
  "as_is": '"$(cat ../examples/sns-signup-as-is.v0.1.json)"',
  "to_be": '"$(cat ../examples/sns-signup-to-be.v0.1.json)"'
}'

Expected:

{
  "delta_TL": -79.4,
  "delta_EAC": 2,
  "LPI": 0.00376,
  "delta_QoD": 19999.999,
  "verdict": "improved"
}

Project Structure

mcp-server/
├── package.json
├── tsconfig.json
├── README.md            ← you are here
├── src/
│   ├── index.ts         ← MCP server entry point
│   ├── types.ts         ← shared types mirroring JSON Schemas
│   ├── validation.ts    ← ajv-based schema validation
│   ├── compute.ts       ← tlm_compute, tlm_compute_multi
│   ├── render.ts        ← tlm_render (TLM-1/2/4)
│   ├── compare.ts       ← tlm_compare
│   ├── axiomCheck.ts    ← tlm_axiom_check
│   ├── prescribe.ts     ← tlm_prescribe, tlm_prescribe_balanced
│   └── aggregate.ts     ← tlm_aggregate (TLM-4)
└── test/                ← vitest test suites (TBD)

Development

# Watch mode
npm run dev

# Run tests
npm test

# Validate all examples in ../examples/ against their schemas
npm run validate-examples

# Lint
npm run lint

Architecture Notes

Why stdio transport?

The MCP spec supports stdio, SSE, and WebSocket transports. We default to stdio for:

• Zero-config local invocation by Claude Desktop, Cursor, Windsurf
• No port management
• Simplest possible CI testing

For network deployment (multi-user team server, hosted SaaS), wrap with SSE or WebSocket — see @modelcontextprotocol/sdk/server/sse.js.

Why ajv for schema validation?

zod is used as a lightweight runtime guard at the MCP tool boundary (because the SDK works naturally with zod). For full JSON Schema validation against the canonical schemas in ../schema/, we use ajv (Draft 2020-12 compliant).

Performance

All TLM computations are O(n) in flow step count. A flow with 100 steps and 10 truths computes in < 1ms. Aggregate computations are O(n log n) due to sorting for percentiles. The server is suitable for both ad-hoc analysis and CI integration.

Boundary handling

• T_k, T_d are real-valued seconds; computations preserve full precision.
• EPSILON = 0.001 is used in QoD denominators to prevent division by zero.
• Truth-latency must be non-negative; negative TL raises NEGATIVE_TL (indicates schema authoring error).

Versioning

The MCP server version follows the TLM methodology version it implements. Currently 0.2.0 implementing TLM v0.2 (which subsumes v0.1).

License

Dual-licensed:

• Code (everything in mcp-server/, examples/, schema/): MIT — see ../LICENSE-CODE
• Methodology (everything in ../paper/, ../skills/): CC-BY-4.0 — see ../LICENSE-METHOD

See the root LICENSE for the combined notice.

Repository

github.com/FCG-labs/FCG-TruthLatencyMap