theseus-kit

theseus-kit 是一个 MCP 服务器，用于安全地检查、编辑、模板化和发布 TFRobot 配置。 通过标准 MCP 协议运行，同时暴露可选的 A2C-SMCP 兼容 window:// 和 skill:// 资源。

目录

• 快速开始
• MCP 工具
• Skill 资源
• 使用指南
  • 配置方式
  • MCP Client 集成
• 工作原理
  • 架构分层
  • 认证体系
  • 数据流
  • 安全模型
• 开发

快速开始

环境要求：Python 3.11+，uv。

# 安装正式发行包
uv tool install "theseus-kit==0.1.1"

# 完成下方配置后，启动 MCP 服务器（stdio 传输）
theseus-kit

最小配置

通过环境变量或 .env 文件配置目标机器人和凭证：

# 机器人路由信息
export THESEUS_ROBOT__ROBOT_ID="my-robot"
export THESEUS_ROBOT__NAMESPACE="default"
export THESEUS_ROBOT__ROBOT_TYPE="tfrobot"
export THESEUS_ROBOT__API_BASE_URL="https://api.example.com"
export THESEUS_ROBOT__MANAGER_BASE_URL="https://manager.example.com"

# 用户个人令牌（stdio 入口使用此方式）
export THESEUS_CREDENTIAL__KIND="user_pat"
export THESEUS_CREDENTIAL__PAT="tfp_xxx"
export THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID="myorg:000042"
# 可选：显式缩窄短 Token；不设置时默认申请以下三个配置 scope
export THESEUS_CREDENTIAL__SCOPES="config:read config:write config:publish"

0.1.1 的默认命令行入口通过 stdio 运行，支持用户 PAT 换发。无 PAT 的 stdio OAuth 外部回调登录尚未实现；HTTP OAuth 的服务端集成见 OAuth 运行手册。

MCP 工具

theseus-kit 提供 11 个 MCP 工具，覆盖配置的完整生命周期：

只读工具

变更工具

工具协作流程

get_config_summary        ← 入口：发现有哪些配置
    ↓
list_config_nodes         ← 导航：探索配置树
    ↓
get_config_detail         ← 读取：获取具体内容（含 content_hash）
    ↓
get_llms_doc              ← Schema：了解字段/校验规则
    ↓
update_draft              ← 修改：带冲突保护的写入
    ↓
validate_draft            ← 校验：发布前预检
    ↓
publish_config            ← 发布：显式确认 + root_hash 校验

Skill 资源

theseus-kit 通过 skill:// 资源暴露 12 个中文技能指南，为 LLM 提供结构化的操作流程：

每个 Skill 定义了允许使用的工具、所需 Scope、标准操作流程和关键约束， 确保 LLM 按「最佳实践」而非自由发挥来操作配置。旧版别名 （inspect-robot-config / edit-robot-draft / publish-robot-config）以 deprecated 标记保留。

实时状态窗口：window://

3 个 window:// 资源提供配置状态的实时快照，按 A2C-SMCP Desktop 协议参与桌面聚合：服务器声明 resources.subscribe 能力并支持资源订阅，变更操作（以及 get_config_detail 更新「最近详情」）后通过 notifications/resources/updated 自动通知订阅方。

使用指南

配置方式

1. 显式凭证模式（user_pat）

有明确配置的凭证时，theseus-kit 走「凭证换发」路径：用户的 PAT 作为 subject_token，Manager 通过 token-exchange（RFC 8693）换发目标机器人 scope 的短 JWT。这是人管配置的正确鉴权模型。

配置的凭证 → Manager 换发端点 → 短 JWT（aud=robot:{public_id}）
→ 注入 X-TF-* 路由头 → 调用 TFRobotServer

这是确定性最强的模式：凭证固定，无需浏览器交互，适合自动化 / CI / 后台场景。

2. OAuth 2.0 模式

服务端组合根提供 HTTP MCP 的 OAuth Protected Resource 支持，由 MCP Client 驱动授权：

MCP Client → TFRSManager AS（Authorization Code + PKCE）
→ OAuth AS token（aud={issuer}/robots/<id>, typ=at+jwt）
→ theseus-kit 校验（tfrs-auth RS256 + JWKS + scope）
→ 直传 TFRobotServer（无需换发）

HTTP 集成适合交互式使用。默认 theseus-kit 命令仅启动 stdio；其无 PAT OAuth 外部回调登录尚未实现，不能用下面的 stdio 客户端配置启用 HTTP OAuth。

凭证选择：THESEUS_CREDENTIAL__KIND 显式选择 user_pat 或 oauth。 配置错误不会静默降级，而是抛出明确的 ConfigError。

MCP Client 集成

在 Claude Desktop 或任意兼容 MCP Client 的配置中添加：

{
  "mcpServers": {
    "theseus-kit": {
      "command": "uvx",
      "args": ["--from", "theseus-kit==0.1.1", "theseus-kit"],
      "env": {
        "THESEUS_ROBOT__ROBOT_ID": "my-robot",
        "THESEUS_ROBOT__NAMESPACE": "default",
        "THESEUS_ROBOT__ROBOT_TYPE": "tfrobot",
        "THESEUS_ROBOT__API_BASE_URL": "https://api.example.com",
        "THESEUS_ROBOT__MANAGER_BASE_URL": "https://manager.example.com",
        "THESEUS_CREDENTIAL__KIND": "user_pat",
        "THESEUS_CREDENTIAL__PAT": "tfp_xxx",
        "THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID": "myorg:000042",
        "THESEUS_CREDENTIAL__SCOPES": "config:read config:write config:publish"
      }
    }
  }
}

HTTP OAuth 接入方式和当前限制见 OAuth 运行手册。

工作原理

架构分层

┌──────────────────────────────────────────┐
│  MCP 表面层（server.py）                  │
│  FastMCP · 11 工具 · 3 window:// 资源     │
│  12 类 skill:// 指南 · OAuth PRM 路由     │
├──────────────────────────────────────────┤
│  应用服务层（services/）                   │
│  ConfigReader · DraftEditor · Publisher   │
│  DraftValidator · TemplateSaver           │
│  LlmsDocReader                            │
├──────────────────────────────────────────┤
│  资源投影层（resources/ · skills/）        │
│  window:// 实时快照 · skill:// 中文指南    │
├──────────────────────────────────────────┤
│  TFRobot 客户端（transport.py）            │
│  RobotClient · RobotAuth · 令牌源双路径   │
├──────────────────────────────────────────┤
│  认证层（oauth.py · tokens.py ·           │
│         credentials.py）                  │
│  JwtVerifier 适配 · 令牌换发 · AS 发现    │
├──────────────────────────────────────────┤
│  模型层（models.py · config.py ·          │
│         routing.py · errors.py）          │
│  TFSResponse · 渐进披露模型 · 路由上下文  │
└──────────────────────────────────────────┘

认证体系

theseus-kit 支持两条凭证路径，在 RobotClient 层自然收敛：

路径 1：显式凭证（user_pat）

UserPatConfig
  → build_credential()           # 构造 tfrs-auth PatCredential
  → AsyncCachingTokenSource      # token-exchange + 缓存 + single-flight + 临期刷新 + 退避
  → RobotAuth                    # 注入 Authorization: Bearer <jwt> + X-TF-*
  → TFRobotServer

路径 2：OAuth 2.0

OAuthConfig
  → TheseusTokenVerifier         # tfrs-auth JwtVerifier → MCP SDK TokenVerifier
  → RFC 8414 AS 发现             # fetch_as_metadata() → jwks_uri + issuer
  → 校验: RS256 + scope + exp    # JwtVerifier.verify(required_scope=)
  → StaticTokenSource            # 静态持有已验 token，不换发
  → RobotAuth                    # 注入 Authorization: Bearer + X-TF-*
  → TFRobotServer                # 原生接受 aud={issuer}/robots/<id> + typ=at+jwt

两条路径对比

数据流

以读取配置详情为例，一次完整的请求经过以下路径：

1. MCP Client 调用 get_config_detail(locator="...")

2. server.py 工具处理函数
   → ConfigReader(robot_id=...).get_detail(client, locator, depth, max_bytes)

3. RobotClient.from_settings(settings)
   → RobotAuth(token_source, context).async_auth_flow()
     → token_source.token() 获取 Bearer（换发或静态）
     → context.routing_headers() 获取 X-TF-Namespace / X-TF-RobotId / X-TF-RobotType
   → httpx.AsyncClient 发送 GET 请求到 TFRobotServer

4. TFRobotServer 响应的 JSON 被反序列化为 TFSResponse[ConfigDetail]
   → code / message / data 信封解包
   → ConfigDetail 包含 content_hash / bytes_returned / truncated / redacted[] 等元数据

5. 结果返回给 MCP Client
   → 同时更新 window:// 资源的 last_locator（用于 recent 快照）

安全模型

• 令牌不出进程：所有凭证保留在 MCP 服务器进程中，绝不进入工具输出、资源、日志或 SKILL 内容
• SecretStr 保护：pydantic SecretStr 字段默认 repr 不暴露密钥
• redaction 最后防线：redaction.py 用正则清除 PAT（tfp_*）、JWT、OAuth token/auth-code/state 形式的令牌
• 显式发布确认：publish_config 要求 acknowledge_publish=true，防止意外发布
• 乐观并发控制：update_draft 的 expected_hash 和 publish_config 的 expected_root_hash 防止丢失更新
• 渐进披露：配置读取默认 8 KiB / 硬上限 32 KiB，敏感字段自动脱敏为 <<redacted>>

关键模块

开发

uv sync --locked --all-groups   # 安装全部依赖
uv run poe check                # 顺序执行 format-check → lint → typecheck
uv run poe ci                   # CI 完整流程：lock-check → check → test-cov
uv run poe test                 # 运行测试（pytest，asyncio 模式 auto）
uv run poe test-cov             # 测试覆盖率（需要 ≥80%）

E2E 测试（需要真实机器人）

THESEUS_E2E=1 \
THESEUS_ROBOT__ROBOT_ID=<rid> \
THESEUS_ROBOT__NAMESPACE=<ns> \
THESEUS_ROBOT__ROBOT_TYPE=tfrobot \
THESEUS_ROBOT__API_BASE_URL=https://api.<clusterDomain> \
THESEUS_ROBOT__MANAGER_BASE_URL=https://<manager-host> \
THESEUS_CREDENTIAL__KIND=user_pat \
THESEUS_CREDENTIAL__PAT=<tfp_...> \
THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID=<orgSlug>:<employeeNo> \
uv run pytest tests/test_e2e_robot.py -v -m e2e

发布前准备

uv run poe ci && uv run poe build && uv run poe package-check

发布流程见 发布文档：版本号由 bump-my-version 管理，通过 GitHub Release + OIDC Trusted Publishing 发布到 PyPI。

关键设计文档

• docs/architecture.md — 架构基线、分层、安全不变量
• docs/progressive-disclosure.md — 大配置渐进披露规格（已冻结）
• docs/auth-oauth-design.md — OAuth 2.0 授权登录技术设计
• docs/releasing.md — 发布流程

协议参考

• Model Context Protocol
• A2C-SMCP protocol
• RFC 8414 — OAuth 2.0 Authorization Server Metadata
• RFC 8693 — OAuth 2.0 Token Exchange
• RFC 8707 — Resource Indicators for OAuth 2.0
• RFC 9068 — JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
• RFC 9728 — OAuth 2.0 Protected Resource Metadata

License

MIT