tteop-mcp

tteop-mcp

面向 TTEOP（Token Telemetry Evaluation Operator Protocol，令牌遥测评估操作协议）的生产级 MCP 服务。

通过 Model Context Protocol 构建、验证和描述 TTEOP 遥测信封。由官方 MCP TypeScript SDK v2 和 tteop-spec 参考实现提供支持。

刚接触此项目？请阅读 START-HERE.md。自动化贡献者还必须阅读 AGENTS.md。

架构

本软件包是一个精简的 MCP 传输层。所有协议逻辑——信封构建、指标计算（银行家舍入）、架构验证和语义规则——均通过稳定的 JavaScript API 委托给 tteop-spec：

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

此处不会重复实现任何指标公式或架构逻辑。tteop-spec 更新验证器或构建器后，此服务会自动继承这些更改。

产品划分

软件包	角色
tteop-spec	规范、架构、验证器、一致性测试套件、构建器 API
tteop-mcp	生产级 MCP 服务（本软件包）——基于 tteop-spec 的精简传输层
SignalAF / SigRank	托管式基准测试、排行榜、试点项目、企业服务

安装

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

工具

工具	描述
tteop_build_envelope	根据令牌计数构建符合 TTEOP v0.1-draft 架构的信封。计算 Yield（Υ）、Leverage（L）、Velocity（V）、output_fraction（F）和 log_leverage（D）。
tteop_validate_envelope	根据 JSON Schema 和语义规则验证信封。返回架构错误、语义错误、警告和计算出的指标。
tteop_describe_protocol	获取 TTEOP 协议元数据：版本、隐私模式、来源级别、禁止字段，以及带公式的指标定义。
tteop_run_conformance	运行一致性测试套件：规范向量不变量、空值语义、禁止字段检测、银行家舍入。

用法

使用 Claude Desktop

添加到 claude_desktop_config.json：

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

使用 MCP Inspector

npx @modelcontextprotocol/inspector npx -y tteop-mcp

打开浏览器标签页，点击 Connect，打开 Tools 标签页，然后调用任意工具。

编程方式调用

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

开发

# 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

验收标准

• npx tteop-mcp 会等待 MCP 连接
• initialize 成功
• tools/list 返回完整架构（4 个工具）
• 每个工具都可以通过 MCP Inspector 调用
• 无效令牌值会返回结构化 MCP 错误（isError: true，并附带验证消息）
• stdout 仅包含协议消息
• CI 会针对打包后的 tarball 运行实际的 MCP 客户端

分发状态与发布顺序

[email protected] 目前已发布到 npm，并列入 MCP Registry 和 Glama。版本 0.2.1 修复了源代码与软件包的来源信息，升级了精确协议依赖 [email protected]，并强化了发布流程。

必须按以下顺序发布：

1. 确认 npm 上已提供 [email protected]。
2. 合并 [email protected] 发布提交，并确保所有必需检查均通过。
3. 手动运行 Release npm package 工作流。该流程会使用 npm 来源证明发布，并在同一提交处创建 GitHub release v0.2.1。
4. 确认 npm view [email protected] gitHead 与 GitHub release 提交相同。
5. 将匹配的 server.json 发布到 MCP Registry：

   mcp-publisher login
   mcp-publisher publish
   

6. 确认 MCP Registry 和 Glama 显示版本 0.2.1 和全部四个工具。
7. 在干净目录中运行 npx -y [email protected] --version，并调用真实的 MCP 客户端。

切勿从包含未提交更改的工作树发布。软件包版本、lockfile、server.json、Git 标签、GitHub release、npm gitHead 和 MCP Registry 版本必须对应同一发布版本。

许可证

Apache-2.0