tteop-mcp

tteop-mcp

Production MCP server for TTEOP — Token Telemetry Evaluation Operator Protocol.

Build, validate, and describe TTEOP telemetry envelopes via the Model Context Protocol. Powered by the official MCP TypeScript SDK v2 and the tteop-spec reference implementation.

New here? Read START-HERE.md. Automated contributors must also read AGENTS.md.

Architecture

This package is a thin MCP transport layer. All protocol logic — envelope construction, metric computation (banker's rounding), schema validation, and semantic rules — is delegated to tteop-spec via its stable JavaScript API:

• tteop-spec/builder → buildEnvelope(telemetry, options)
• tteop-spec/validator → validateEnvelope(envelope, options), computeMetrics(telemetry)

No metric formulas or schema logic are duplicated here. When tteop-spec updates its validator or builder, this server inherits the changes.

Product separation

Package	Role
tteop-spec	Specification, schemas, validator, conformance suite, builder API
tteop-mcp	Production MCP server (this package) — thin transport over tteop-spec
SignalAF / SigRank	Hosted benchmarking, leaderboard, pilots, enterprise services

Install

npm install -g tteop-mcp
# or use directly:
npx tteop-mcp

Tools

Tool	Description
tteop_build_envelope	Build a TTEOP v0.1-draft schema-conforming envelope from token counts. Computes Yield (Υ), Leverage (L), Velocity (V), output_fraction (F), and log_leverage (D).
tteop_validate_envelope	Validate an envelope against the JSON Schema and semantic rules. Returns schema errors, semantic errors, warnings, and computed metrics.
tteop_describe_protocol	Get TTEOP protocol metadata: versions, privacy modes, provenance levels, forbidden fields, metric definitions with formulas.
tteop_run_conformance	Run the conformance suite: canonical vector invariants, null semantics, forbidden field detection, banker's rounding.

Usage

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tteop": {
      "command": "npx",
      "args": ["-y", "tteop-mcp"]
    }
  }
}

With MCP Inspector

npx @modelcontextprotocol/inspector npx -y tteop-mcp

Open the browser tab, click Connect, open the Tools tab, and call any tool.

Programmatic

import { spawn } from "node:child_process";

const proc = spawn("npx", ["-y", "tteop-mcp"], { stdio: ["pipe", "pipe", "pipe"] });
// Send JSON-RPC 2.0 messages to proc.stdin, read responses from proc.stdout

Development

# Install the exact locked dependency graph
npm ci

# Optional: test unpublished local tteop-spec changes after the clean install.
# This overrides node_modules locally and is never used by CI or releases.
cd ../otep-spec && npm link && cd ../tteop-mcp && npm link tteop-spec

# Run tests
npm test                    # real MCP client test
npm run test:packaged       # packaged tarball test
npm run test:release        # package/lockfile/registry version agreement
npm run test:all            # complete local release gate

# Run with MCP Inspector
npm run inspect

# Start the server
npm start

Acceptance criteria

• npx tteop-mcp waits for an MCP connection
• initialize succeeds
• tools/list returns complete schemas (4 tools)
• Every tool can be called through MCP Inspector
• Invalid token values return structured MCP errors (isError: true with validation message)
• stdout contains protocol messages only
• CI runs an actual MCP client against the packaged tarball

Distribution status and release order

tteop-mcp@0.2.0 is currently published to npm and listed in the MCP Registry and Glama. Release 0.2.1 repairs source/package provenance, upgrades the exact protocol dependency to tteop-spec@0.1.5-draft, and adds release hardening.

The required release order is:

• Confirm tteop-spec@0.1.5-draft is available from npm.
• Merge the tteop-mcp@0.2.1 release commit with every required check green.
• Run the manual Release npm package workflow. It publishes with npm provenance and creates GitHub release v0.2.1 at the same commit.
• Confirm npm view tteop-mcp@0.2.1 gitHead equals the GitHub release commit.
• Publish the matching server.json to the MCP Registry:

  mcp-publisher login
  mcp-publisher publish
  

• Confirm the MCP Registry and Glama show version 0.2.1 and all four tools.
• From a clean directory, run npx -y tteop-mcp@0.2.1 --version and a real MCP client invocation.

Never publish from an uncommitted working tree. Package version, lockfile, server.json, Git tag, GitHub release, npm gitHead, and MCP Registry version must identify the same release.

License

Apache-2.0