Skip to content

Token scope 分级:read-only / trial tier 支持 #137

@firstdata-dev

Description

@firstdata-dev

背景

当前 FirstData MCP 的 token 体系是 all-or-nothing 权限模型:持有 token 即拥有全部 5 个工具的完整访问权限,有效期统一 365 天。这使得以下场景无法安全实现:

  • README 中的 curl 试用命令(增长战术 #7 P0
  • Web Playground 公开体验(P1)
  • MCP Inspector 快速集成(P2)

关联 issue: #98(XSS 修复,已关闭)讨论中首次提到凭证架构的局限性。

问题

  1. 无法安全开放公开体验端点 — 无 scope 分级,公开端点只能用全权限 token 或完全不鉴权,前者是安全隐患,后者无法做用量控制
  2. 搜索质量问题会被放大 — 如 "World Bank" 搜不到 worldbank-open-data 等已知问题(明察 QA 反馈),在公开 demo 场景下从内部 bug 变成信任崩塌
  3. 限速无隔离 — 试用流量与正式用户共享 rate limit 池,可能冲击付费用户体验

方案

1. Token scope 分级

引入 scope 字段,至少支持两级:

Scope 允许的工具 用途
read search_source, get_source, get_access_guide 试用/Demo/只读集成
full 全部 5 个工具 正式用户(当前默认行为)

2. 试用 token 机制

  • 短有效期:24h 或 session-level,自动轮转
  • 匿名申请:无需注册,访问公开端点即自动签发
  • 独立 rate limit:试用 token 和正式 token 分开计数(如试用 10 次/小时,正式 1000 次/小时)

3. 限速响应优化

  • 429 返回体包含 retry_afterremaining_quota
  • 附带申请正式 token 的引导链接
  • 空结果返回 suggested_queries 或 "did you mean" 提示

前置条件

本 issue 是增长战术 #7 所有体验优化(P0-P2)的前置条件:

搜索质量修复 ──┐
               ├──→ P0 curl 试用 → P1 Playground → P2 Inspector
scope 分级 ────┘

验收标准

  • Token 表支持 scope 字段(read / full
  • 签发试用 token 的 API 端点
  • 试用 token 独立 rate limit 池
  • 429 返回体包含引导信息
  • 空结果返回搜索建议
  • 文档说明 demo tier vs 正式 key 的行为差异

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions