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

Terminal

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:

config.json

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

With MCP Inspector

Terminal

npx @modelcontextprotocol/inspector npx -y tteop-mcp

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

Programmatic

server.ts

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

bash

# 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:
bash
```
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