Skip to main content
Glama
theseus-kit

theseus-kit

by A2C-SMCP

theseus-kit

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

目录

Related MCP server: FastMCP Server Template

快速开始

环境要求:Python 3.11+,uv。

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

# 完成下方配置后,启动 MCP 服务器(stdio 传输)
theseus-kit

最小配置

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

# 机器人权威入口(从 Manager connection-info 的 accessURL 复制)
export THESEUS_ROBOT__ACCESS_URL="https://acme.test.turingfocus.cn/c/tfrobot/robot-1/"
export THESEUS_ROBOT__ROBOT_ID="robot-1"
export THESEUS_ROBOT__ROBOT_TYPE="tfrobot"
export THESEUS_ROBOT__MANAGER_API_BASE_URL="https://rest.test.turingfocus.cn"

# 用户个人令牌(stdio 入口使用此方式)
export THESEUS_CREDENTIAL__KIND="user_pat"
export THESEUS_CREDENTIAL__PAT="tfp_xxx"
export THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID="turingfocus:EMP010-R"
# 可选:显式缩窄短 Token;不设置时默认申请以下三个配置 scope
export THESEUS_CREDENTIAL__SCOPES="config:read config:write config:publish"

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

MCP 工具

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

只读工具

工具

说明

所需 Scope

get_config_summary

获取机器人身份 + 三态(草稿/模板/线上)配置概览

config:read

list_config_nodes

在配置森林的任意层级列出子节点,支持游标分页和过滤

config:read

get_config_detail

读取单个配置节点的有界、脱敏详情(默认 8 KiB,上限 32 KiB)

config:read

get_template

按 ID 读取模板(支持仅元数据或完整详情两种模式)

config:read

get_llms_doc

读取机器人运行时 llms.txt Schema 文档(索引 + 具体页面)

config:read

变更工具

工具

说明

所需 Scope

create_draft

在指定 Scene 下用指定 Factory 创建新草稿节点

config:write

update_draft

更新草稿配置项,支持 expected_hash 乐观并发控制

config:write

delete_draft

删除草稿节点(服务端自动级联清理其它草稿对它的引用)

config:write

validate_draft

验证草稿配置是否满足上线条件(全量预检或指定节点),返回逐节点校验结果

config:write

save_template

将草稿子树保存为可复用模板

config:write

publish_config

将所有草稿发布到线上,要求 acknowledge_publish=true 显式确认

config:publish

工具协作流程

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

资源 URI

说明

工作流总纲

skill://com.a2c-smcp.theseus-kit/theseus

调度画像 → 计划 → 落地三阶段工作流

画像优化

skill://com.a2c-smcp.theseus-kit/persona-optimize

增量采访并同步画像正文与变更记录

配置计划

skill://com.a2c-smcp.theseus-kit/plan-config

生成结构化工件、技术选型和可续接的配置修改计划

落地计划

skill://com.a2c-smcp.theseus-kit/apply-config-plan

逐条落实计划到 Draft 并回写进度

反馈改进

skill://com.a2c-smcp.theseus-kit/enhance

提交脱敏的问题与改进建议

分析配置

skill://com.a2c-smcp.theseus-kit/analyze-config

确认目标 → 全局概览 → LLMTEXT 技术选型 → 优化大纲

管理拓扑

skill://com.a2c-smcp.theseus-kit/manage-topology

创建节点 → 删除节点 → 修改引用关系,结合 LLMTEXT 进行技术选型

调优配置

skill://com.a2c-smcp.theseus-kit/tune-config

读取现状 → 理解字段约束 → 合理化修改 → 校验 → 冲突处理

保存模板

skill://com.a2c-smcp.theseus-kit/save-template

识别可复用节点 → 命名 → 保存 → 验证

发布配置

skill://com.a2c-smcp.theseus-kit/publish-config

预检 → 审批 → 发布 → 验证,全局不可逆操作

用户画像采访

skill://com.a2c-smcp.theseus-kit/persona-interview

采访需求方获取画像:职业领域 / 专业技能 / 日常工作 / 知识结构三张清单 / 能力草图候选

写 TFOnto

skill://com.a2c-smcp.theseus-kit/write-tfonto

知识结构 + 能力草图 → 平台可导入的 .tfo(概念/属性/关系 → Def,能力 → Function/Action),附带独立校验器 scripts/validate_tfonto.py 与完整范例

每个 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 自动通知订阅方。

资源

URI

说明

配置摘要

window://com.a2c-smcp.theseus-kit/config/summary

机器人身份 + 三态概览,每次变更后刷新

最近详情

window://com.a2c-smcp.theseus-kit/config/recent

最近打开的配置详情(用户最后一次访问打开的配置面板),无打开时返回空状态

配置拓扑

window://com.a2c-smcp.theseus-kit/config/topology

草稿配置引用图(roots / orphans / 邻接表节点),即当前 Ontology 结构

使用指南

配置方式

1. 显式凭证模式(user_pat)

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

配置的凭证 → Manager 换发端点 → 短 JWT(aud=robot:{public_id})
→ Bearer + 权威 accessURL(Host + /c/tfrobot/{rid})→ 调用 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/{public_id}, typ=at+jwt)
→ theseus-kit 校验(tfrs-auth RS256 + JWKS + scope)
→ 直传 TFRobotServer(无需换发)

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

OAuth 验收状态:TFRM-760 已修复 Authorization Code 的 audience/typ;但 MCP SDK Topology A 的 PRM resource 与 Manager robot resource 的兼容性仍需真实 test 环境验收。 验收前 0.2.0 只保证 user_pat;不要把 OAuth 作为生产可用能力。

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

MCP Client 集成

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

{
  "mcpServers": {
    "theseus-kit": {
      "command": "uvx",
      "args": ["--from", "theseus-kit==0.2.0", "theseus-kit"],
      "env": {
        "THESEUS_ROBOT__ACCESS_URL": "https://acme.test.turingfocus.cn/c/tfrobot/robot-1/",
        "THESEUS_ROBOT__ROBOT_ID": "robot-1",
        "THESEUS_ROBOT__ROBOT_TYPE": "tfrobot",
        "THESEUS_ROBOT__MANAGER_API_BASE_URL": "https://rest.test.turingfocus.cn",
        "THESEUS_CREDENTIAL__KIND": "user_pat",
        "THESEUS_CREDENTIAL__PAT": "tfp_xxx",
        "THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID": "turingfocus:EMP010-R",
        "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>
  → 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
  → TFRobotServer                # 原生接受 aud={issuer}/robots/{public_id} + typ=at+jwt

两条路径对比

user_pat

OAuth 2.0

令牌来源

Manager 换发(RFC 8693 token-exchange)

MCP Client 授权后直传

换发

是

否

缓存/刷新

AsyncCachingTokenSource 内置

MCP Client 侧负责

适用场景

人管配置(自动化 / CI / 后台)

交互式使用

数据流

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

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).async_auth_flow()
     → token_source.token() 获取 Bearer(换发或静态)
     → 只注入 Authorization: Bearer
   → httpx.AsyncClient(base_url=access_url) 发送 GET 到网关
   → Operator 按 Host 定 namespace、按 /c/tfrobot/{rid} 定 robot,剥前缀后投给 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>>

关键模块

模块

职责

server.py

FastMCP 组合根,工具/资源注册,OAuth PRM 路由

config.py

TheseusSettings(pydantic-settings),两种凭证配置的判别联合

transport.py

RobotClient + RobotAuth(Bearer-only)+ StaticTokenSource

oauth.py

TheseusTokenVerifier(tfrs-auth → MCP SDK 适配)+ RFC 8414 发现

tokens.py

build_token_source() — AsyncCachingTokenSource 组装

credentials.py

build_credential() — user_pat → tfrs-auth PatCredential

routing.py

RobotAddress — 权威 accessURL(/c/{type}/{id})校验

errors.py

类型化异常层级 + map_exchange_error()

redaction.py

令牌脱敏最后防线(PAT / JWT / OAuth token / code / state)

models.py

TFSResponse[T] 信封 + 渐进披露数据模型

services/

ConfigReader、DraftEditor、DraftValidator、Publisher、TemplateSaver、LlmsDocReader

resources/

window:// 实时快照构建

skills/

skill:// 静态中文指南

开发

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__ACCESS_URL=https://<alias>/c/tfrobot/<rid>/ \
THESEUS_ROBOT__ROBOT_ID=<rid> \
THESEUS_ROBOT__ROBOT_TYPE=tfrobot \
THESEUS_ROBOT__MANAGER_API_BASE_URL=https://<manager-machine-api-origin> \
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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server providing token-efficient access to OpenAPI/Swagger specs via MCP Resources for client-side exploration.
      582 npm
      76
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A production-ready MCP server template that enables developers to quickly build and deploy MCP servers with dynamic tool/resource loading, YAML-based prompts, and seamless OpenShift deployment. Supports both local development with hot-reload and production HTTP deployment with optional JWT authentication.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that distributes tool specifications from GitLab repositories to IDEs, dynamically generating MCP tools and serving files via aimcp:// URIs.
      25 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for interacting with QUADS infrastructure systems via API, enabling resource management and automation through LLM applications.
      MIT