theseus-kit
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@theseus-kit Read the current draft configuration"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| 获取机器人身份 + 三态(草稿/模板/线上)配置概览 |
|
| 在配置森林的任意层级列出子节点,支持游标分页和过滤 |
|
| 读取单个配置节点的有界、脱敏详情(默认 8 KiB,上限 32 KiB) |
|
| 按 ID 读取模板(支持仅元数据或完整详情两种模式) |
|
| 读取机器人运行时 |
|
变更工具
工具 | 说明 | 所需 Scope |
| 在指定 Scene 下用指定 Factory 创建新草稿节点 |
|
| 更新草稿配置项,支持 |
|
| 删除草稿节点(服务端自动级联清理其它草稿对它的引用) |
|
| 验证草稿配置是否满足上线条件(全量预检或指定节点),返回逐节点校验结果 |
|
| 将草稿子树保存为可复用模板 |
|
| 将所有草稿发布到线上,要求 |
|
工具协作流程
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 | 说明 |
工作流总纲 |
| 调度画像 → 计划 → 落地三阶段工作流 |
画像优化 |
| 增量采访并同步画像正文与变更记录 |
配置计划 |
| 生成结构化工件、技术选型和可续接的配置修改计划 |
落地计划 |
| 逐条落实计划到 Draft 并回写进度 |
反馈改进 |
| 提交脱敏的问题与改进建议 |
分析配置 |
| 确认目标 → 全局概览 → LLMTEXT 技术选型 → 优化大纲 |
管理拓扑 |
| 创建节点 → 删除节点 → 修改引用关系,结合 LLMTEXT 进行技术选型 |
调优配置 |
| 读取现状 → 理解字段约束 → 合理化修改 → 校验 → 冲突处理 |
保存模板 |
| 识别可复用节点 → 命名 → 保存 → 验证 |
发布配置 |
| 预检 → 审批 → 发布 → 验证,全局不可逆操作 |
用户画像采访 |
| 采访需求方获取画像:职业领域 / 专业技能 / 日常工作 / 知识结构三张清单 / 能力草图候选 |
写 TFOnto |
| 知识结构 + 能力草图 → 平台可导入的 |
每个 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 | 说明 |
配置摘要 |
| 机器人身份 + 三态概览,每次变更后刷新 |
最近详情 |
| 最近打开的配置详情(用户最后一次访问打开的配置面板),无打开时返回空状态 |
配置拓扑 |
| 草稿配置引用图(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>>
关键模块
模块 | 职责 |
| FastMCP 组合根,工具/资源注册,OAuth PRM 路由 |
|
|
|
|
|
|
|
|
|
|
|
|
| 类型化异常层级 + |
| 令牌脱敏最后防线(PAT / JWT / OAuth token / code / state) |
|
|
|
|
|
|
|
|
开发
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— 发布流程
协议参考
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…
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for Product Management
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server providing token-efficient access to OpenAPI/Swagger specs via MCP Resources for client-side exploration.582 npm76MIT
- FlicenseBqualityDmaintenanceA 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-
- AlicenseNot gradedqualityDmaintenanceMCP server that distributes tool specifications from GitLab repositories to IDEs, dynamically generating MCP tools and serving files via aimcp:// URIs.25 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for interacting with QUADS infrastructure systems via API, enabling resource management and automation through LLM applications.MIT