{
  "markdown": "# tteop-mcp\n\nProduction MCP server for **TTEOP** — Token Telemetry Evaluation Operator Protocol.\n\nBuild, validate, and describe TTEOP telemetry envelopes via the Model Context Protocol. Powered by the official [MCP TypeScript SDK v2](https://github.com/modelcontextprotocol/typescript-sdk) and the [`tteop-spec`](https://github.com/SunrisesIllNeverSee/otep-spec) reference implementation.\n\nNew here? Read [START-HERE.md](START-HERE.md). Automated contributors must also read [AGENTS.md](AGENTS.md).\n\n## Architecture\n\nThis 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:\n\n- `tteop-spec/builder` → `buildEnvelope(telemetry, options)`\n- `tteop-spec/validator` → `validateEnvelope(envelope, options)`, `computeMetrics(telemetry)`\n\nNo metric formulas or schema logic are duplicated here. When `tteop-spec` updates its validator or builder, this server inherits the changes.\n\n### Product separation\n\n| Package | Role |\n|---------|------|\n| `tteop-spec` | Specification, schemas, validator, conformance suite, builder API |\n| `tteop-mcp` | Production MCP server (this package) — thin transport over `tteop-spec` |\n| SignalAF / SigRank | Hosted benchmarking, leaderboard, pilots, enterprise services |\n\n## Install\n\n```bash\nnpm install -g tteop-mcp\n# or use directly:\nnpx tteop-mcp\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `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). |\n| `tteop_validate_envelope` | Validate an envelope against the JSON Schema and semantic rules. Returns schema errors, semantic errors, warnings, and computed metrics. |\n| `tteop_describe_protocol` | Get TTEOP protocol metadata: versions, privacy modes, provenance levels, forbidden fields, metric definitions with formulas. |\n| `tteop_run_conformance` | Run the conformance suite: canonical vector invariants, null semantics, forbidden field detection, banker's rounding. |\n\n## Usage\n\n### With Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tteop\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tteop-mcp\"]\n    }\n  }\n}\n```\n\n### With MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector npx -y tteop-mcp\n```\n\nOpen the browser tab, click **Connect**, open the **Tools** tab, and call any tool.\n\n### Programmatic\n\n```javascript\nimport { spawn } from \"node:child_process\";\n\nconst proc = spawn(\"npx\", [\"-y\", \"tteop-mcp\"], { stdio: [\"pipe\", \"pipe\", \"pipe\"] });\n// Send JSON-RPC 2.0 messages to proc.stdin, read responses from proc.stdout\n```\n\n## Development\n\n```bash\n# Install the exact locked dependency graph\nnpm ci\n\n# Optional: test unpublished local tteop-spec changes after the clean install.\n# This overrides node_modules locally and is never used by CI or releases.\ncd ../otep-spec && npm link && cd ../tteop-mcp && npm link tteop-spec\n\n# Run tests\nnpm test                    # real MCP client test\nnpm run test:packaged       # packaged tarball test\nnpm run test:release        # package/lockfile/registry version agreement\nnpm run test:all            # complete local release gate\n\n# Run with MCP Inspector\nnpm run inspect\n\n# Start the server\nnpm start\n```\n\n## Acceptance criteria\n\n- [x] `npx tteop-mcp` waits for an MCP connection\n- [x] `initialize` succeeds\n- [x] `tools/list` returns complete schemas (4 tools)\n- [x] Every tool can be called through MCP Inspector\n- [x] Invalid token values return structured MCP errors (`isError: true` with validation message)\n- [x] stdout contains protocol messages only\n- [x] CI runs an actual MCP client against the packaged tarball\n\n## Distribution status and release order\n\n`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.\n\nThe required release order is:\n\n1. Confirm `tteop-spec@0.1.5-draft` is available from npm.\n2. Merge the `tteop-mcp@0.2.1` release commit with every required check green.\n3. Run the manual **Release npm package** workflow. It publishes with npm provenance and creates GitHub release `v0.2.1` at the same commit.\n4. Confirm `npm view tteop-mcp@0.2.1 gitHead` equals the GitHub release commit.\n5. Publish the matching `server.json` to the MCP Registry:\n   ```bash\n   mcp-publisher login\n   mcp-publisher publish\n   ```\n6. Confirm the MCP Registry and Glama show version `0.2.1` and all four tools.\n7. From a clean directory, run `npx -y tteop-mcp@0.2.1 --version` and a real MCP client invocation.\n\nNever 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.\n\n## License\n\nApache-2.0\n",
  "bytes": 5014,
  "sha": "12a0e709eeb245f8ef35477da7f535694f4f338521c1ea3d0fb6631362326cd1",
  "repo_slug": "sunrisesillneversee/tteop-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sunrisesillneversee_tteop_mcp_e8b969c2/readme"
}