TokenOracle

此仓库已归档，服务也已关闭

TokenOracle MCP

Token Oracle 是一个模型上下文协议（MCP）服务，可在 Agent 消耗令牌之前估算、比较和控制大模型 API 成本。它提供九种工具、四个只读资源，以及一个 cost_analysis_workflow 提示词模板。它使用专有定价算法，不依赖大模型，确保预算工作流具有确定性。

专为由一个或零名员工的公司提供支持的 Agent 集群而设计，Token Oracle 在你的 OpenClaw 集群中充当一位小型 CFO，帮助控制支出并提出改进提示词的建议。

帮它们节省令牌，今天就调用 Token Oracle！

提供的 MCP 工具：

• estimate_cost — 在执行前估算单次大模型 API 调用的美元成本。输入：task_description、prompt_text、task_type 或显式的 token_count。输出：cost_usd、recommended_model、confidence、will_fit_context、pricing_updated。注解：readOnlyHint:true、idempotentHint:true、openWorldHint:false。
• estimate_cost_batch — 在一次调用中为最多 100 个大模型任务定价。返回每个任务的明细、total_cost_usd 和 cheapest_model_for_all。开始任何多步骤流水线之前使用。
• compare_models — 针对给定任务，按价格对所有受支持提供商的大模型进行排序。返回按成本排序的模型，以及 speed_tier 和 quality_tier。支持按 min_quality、max_cost_usd 和 provider 筛选。输入：task_type、token_count 或 prompt_text。
• budget_check — 检查计划任务是否符合月度预算。返回 can_proceed（布尔值）、remaining_budget_usd、budget_consumed_pct，以及包含 savings_pct 的 cheaper_alternatives。输入：monthly_budget_usd、current_spend_usd 和任务描述。
• find_cheapest_for_budget — budget_check 的反向操作。给定 budget_usd 上限和任务，返回预算范围内最佳的模型/质量组合，以及所有按质量再按成本排序的替代方案。

提供的 MCP 资源：

• token-oracle://meta — 机器可读的服务能力文档（版本、model_count、定价元数据）
• token-oracle://models — 用于发现和验证的模型 ID 及其元数据
• token-oracle://heuristics — 任务类型令牌启发式规则和关键词分类器模式（可审计）
• token-oracle://pricing/changelog — 仅追加的定价变更日志；可用于检测定价随时间的变化

提供的 MCP 提示词：

• cost_analysis_workflow — 引导式三步提示词模板：estimate_cost → compare_models → budget_check。参数：task_description、monthly_budget_usd（可选）、quality_threshold（可选）。

受支持的提供商： Anthropic、OpenAI、Google、Groq、Together AI、Mistral、DeepSeek、Cohere（100 多个模型）。

标准 Agent 工作流示例： 目标：运行 500 个产品描述生成任务。预算为每月 $50，当前支出为 $43。

1. estimate_cost_batch({ tasks: [{ task_type: "generate", token_count: { input: 200, output: 800 }, quantity: 500 }] }) → total_cost_usd: $0.60
2. compare_models({ token_count: { input: 200, output: 800 }, task_type: "generate", min_quality: "med", max_cost_usd: 0.002 }) → deepseek-v3，每个任务 $0.00035（总计 $0.175）——便宜 71%，质量等级相同
3. budget_check({ monthly_budget_usd: 50, current_spend_usd: 43, token_count: { input: 200, output: 800 }, model: "deepseek-v3" }) → can_proceed: true，remaining: $6.825，budget_consumed_pct: 2.4% 决定：使用 deepseek-v3。与 gpt-4o-mini 相比节省 $0.425。

定价：

• 免费版：每天 1000 次 API 调用，可通过远程端点使用所有托管工具，无需信用卡
• 专业版（$29/月）：无限次调用、track_spend 工具（按 API 密钥持久保存成本账本）、优先吞吐量、按 Agent/任务/会话归属支出

联系方式： [email protected]

托管端点

• 规范的远程 MCP URL：https://mcp.guffeyholdings.com/TokenOracle
• 规范的 MCP 名称：com.guffeyholdings/token-oracle

直接远程配置：

{
  "mcpServers": {
    "token-oracle": {
      "type": "streamable-http",
      "url": "https://mcp.guffeyholdings.com/TokenOracle",
      "headers": {
        "X-API-Key": "${TOKEN_ORACLE_API_KEY}"
      }
    }
  }
}

npm 桥接包

对于仍需要通过 npm 安装 stdio 服务的本地客户端，请使用 token-oracle-mcp。

零输入试用流程：

启动桥接程序时无需提供 API 密钥；如果托管服务已启用试用认证，它会在首次启动时自动获取并存储按量计费的试用凭据。

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

一次性显式登录流程：

npx -y token-oracle-mcp login

使用 --api-key 时，会验证并存储一个付费托管 API 密钥。不使用 --api-key 时，则会请求并存储托管试用凭据。完成任一流程后，MCP 配置都无需注入 TOKEN_ORACLE_API_KEY。

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

如果你更喜欢无状态设置，可以继续将 TOKEN_ORACLE_API_KEY 作为环境变量传入。

托管试用行为：

• 试用凭据按量计费，并由服务器端设置上限
• 达到托管试用请求上限后，服务会返回需要升级的响应
• 对于同一申请者，只要试用凭据仍然有效，托管服务就会重复使用该凭据，而不是每次都签发新令牌
• 试用凭据的签发单独限流，并可能因服务器端滥用风险评分而被阻止
• 之后，托管升级流程可以将存储的试用凭据替换为付费凭据，无需更改 MCP 配置

可选的桥接环境变量：

• TOKEN_ORACLE_API_KEY：可选的托管 API 密钥；优先于任何已存储的凭据
• TOKEN_ORACLE_BASE_URL：远程端点的覆盖值；默认为 https://mcp.guffeyholdings.com/TokenOracle
• TOKEN_ORACLE_SUBJECT：可选的终端用户主体，通过 X-Token-Oracle-Subject 转发

其他桥接命令：

• npx -y token-oracle-mcp login：通过 --api-key 使用付费认证；未提供密钥时则获取托管试用凭据
• npx -y token-oracle-mcp logout：移除本地存储的凭据

功能

工具：

• estimate_cost
• estimate_cost_batch
• compare_models
• budget_check
• find_cheapest_for_budget
• get_budget_status
• list_request_activity
• get_usage_summary
• get_usage_leaderboard

资源：

• token-oracle://meta
• token-oracle://models
• token-oracle://heuristics
• token-oracle://pricing/changelog

提示词：

• cost_analysis_workflow

版本

• 托管服务版本：1.0.6
• 桥接包版本：1.0.6