Tteop MCP server

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

Install

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

Tools

Usage

With Claude Desktop

Add to claudedesktopconfig.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

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

Distribution status and release order

Shortened. The full README is on GitHub.