theseus-kit 0.1.0__tar.gz

theseus_kit-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.env
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+htmlcov/
+.coverage
+coverage.xml
+.idea

theseus_kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+本项目的显著变更都会记录在此文件中。
+
+格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [PEP 440](https://peps.python.org/pep-0440/) 与语义化版本意图。
+
+## [0.1.0] — 2026-08-12
+
+### Added
+
+- MCP Server 骨架，基于 FastMCP，支持 stdio 传输
+- TFRobot 认证与路由层：X-TF-* 头部强制校验、user_pat token-exchange 换发、AsyncCachingTokenSource
+- 渐进披露契约（方案 A）：无状态索引 + 结构化选择器，4 个 MCP 只读工具（get_config_summary → list_config_nodes → get_config_detail → get_config_value）
+- 配置变更工具：update_draft（content-hash 冲突保护）、validate_draft、create_draft、save_template、publish_config
+- A2C-SMCP 兼容层：window:// 和 skill:// 资源投影
+- OAuth 认证路径：TokenVerifier 适配器、RS PRM + Bearer 校验、StaticTokenSource
+- GitHub Actions CI/CD：质量门禁（format/lint/typecheck/tests）+ OIDC Trusted Publishing
+- Python 3.11-3.13 支持
+- Redaction 安全最后防线：PAT/JWT/OAuth token 泄漏防护
+

theseus_kit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Development targets the `develop` branch. Keep each change tied to a GitHub
+issue in the active milestone.
+
+Before opening a pull request, run:
+
+```bash
+uv sync --locked --all-groups
+uv run poe ci
+uv run poe build
+uv run poe package-check
+```
+
+Protocol-facing changes must preserve standard MCP interoperability. A2C-SMCP
+metadata and URI schemes are additive extensions and must not be required for
+using the server from a generic MCP client.

theseus_kit-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 A2C-SMCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

theseus_kit-0.1.0/PKG-INFO

@@ -0,0 +1,392 @@
+Metadata-Version: 2.5
+Name: theseus-kit
+Version: 0.1.0
+Summary: MCP server for safely inspecting, editing, templating, and publishing TFRobot configurations
+Project-URL: Repository, https://github.com/A2C-SMCP/theseus-kit
+Project-URL: Issues, https://github.com/A2C-SMCP/theseus-kit/issues
+Author: A2C-SMCP contributors
+License: MIT
+License-File: LICENSE
+Keywords: a2c-smcp,agent,configuration,mcp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <4.0,>=3.11
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: mcp<2.0.0,>=1.15.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.10.0
+Requires-Dist: pydantic<3.0.0,>=2.11.0
+Requires-Dist: tfrs-auth[httpx]<1.0.0,>=0.2.1
+Description-Content-Type: text/markdown
+
+# theseus-kit
+
+`theseus-kit` 是一个 MCP 服务器，用于安全地检查、编辑、模板化和发布 TFRobot 配置。
+通过标准 MCP 协议运行，同时暴露可选的 A2C-SMCP 兼容 `window://` 和 `skill://` 资源。
+
+## 目录
+
+- [快速开始](#快速开始)
+- [MCP 工具](#mcp-工具)
+- [Skill 资源](#skill-资源)
+- [使用指南](#使用指南)
+  - [配置方式](#配置方式)
+  - [MCP Client 集成](#mcp-client-集成)
+- [工作原理](#工作原理)
+  - [架构分层](#架构分层)
+  - [认证体系](#认证体系)
+  - [数据流](#数据流)
+  - [安全模型](#安全模型)
+- [开发](#开发)
+
+## 快速开始
+
+**环境要求**：Python 3.11+，[uv](https://docs.astral.sh/uv/)。
+
+```bash
+# 安装
+uv sync --locked --all-groups
+
+# 启动 MCP 服务器（stdio 传输）
+uv run theseus-kit
+```
+
+### 最小配置
+
+通过环境变量或 `.env` 文件配置目标机器人和凭证：
+
+```bash
+# 机器人路由信息
+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"
+
+# 凭证（二选一）
+# 方式 1：用户个人令牌（推荐——theseus-kit 是人管配置的工具，非 A2A）
+export THESEUS_CREDENTIAL__KIND="user_pat"
+export THESEUS_CREDENTIAL__PAT="tfp_xxx"
+export THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID="myorg:000042"
+
+# 方式 2：OAuth 2.0（MCP Client 驱动授权）
+export THESEUS_CREDENTIAL__KIND="oauth"
+export THESEUS_CREDENTIAL__AUTHORIZATION_SERVER="https://manager.example.com"
+export THESEUS_CREDENTIAL__SCOPES="config:read config:write"
+```
+
+## MCP 工具
+
+theseus-kit 提供 **9 个 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 |
+|------|------|------------|
+| `update_draft` | 更新草稿配置项，支持 `expected_hash` 乐观并发控制 | `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://` 资源暴露 **3 个中文技能指南**，为 LLM 提供结构化的操作流程：
+
+| Skill | 资源 URI | 说明 |
+|-------|----------|------|
+| 查看配置 | `skill://com.a2c-smcp.theseus-kit/inspect-robot-config` | 标准探索流程：概览 → Schema → 列表 → 详情 → 模板，含脱敏和分页处理指南 |
+| 编辑草稿 | `skill://com.a2c-smcp.theseus-kit/edit-robot-draft` | 读取-检查-写入循环：Schema 优先、乐观并发控制、校验错误处理、模板保存 |
+| 发布配置 | `skill://com.a2c-smcp.theseus-kit/publish-robot-config` | 预检 → 审批边界 → 发布 → 验证，含显式 `acknowledge_publish` 机制和失败处理矩阵 |
+
+每个 Skill 定义了允许使用的工具、所需 Scope、标准操作流程和关键约束，
+确保 LLM 按「最佳实践」而非自由发挥来操作配置。
+
+### 实时状态窗口：`window://`
+
+2 个 `window://` 资源提供配置状态的实时快照，在每次变更操作后自动通知更新：
+
+| 资源 | URI | 说明 |
+|------|-----|------|
+| 配置摘要 | `window://com.a2c-smcp.theseus-kit/config/summary` | 机器人身份 + 三态概览，每次变更后刷新 |
+| 最近详情 | `window://com.a2c-smcp.theseus-kit/config/recent` | 最近打开的配置详情，无打开时返回空状态 |
+
+## 使用指南
+
+### 配置方式
+
+#### 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 模式
+
+无显式凭证时，走 MCP 标准 OAuth 授权：
+
+```
+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（无需换发）
+```
+
+适合**交互式使用**：用户在 MCP Client 中完成授权，无需手动管理令牌。
+
+> **凭证选择不变式**：显式凭证（user_pat）始终优先；OAuth 仅在无显式凭证时启用。
+> 配置错误不会静默降级，而是抛出明确的 `ConfigError`。
+
+### MCP Client 集成
+
+在 Claude Desktop 或任意兼容 MCP Client 的配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "theseus-kit": {
+      "command": "uv",
+      "args": ["run", "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"
+      }
+    }
+  }
+}
+```
+
+OAuth 模式下的配置：
+
+```json
+{
+  "mcpServers": {
+    "theseus-kit": {
+      "command": "uv",
+      "args": ["run", "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": "oauth",
+        "THESEUS_CREDENTIAL__AUTHORIZATION_SERVER": "https://manager.example.com",
+        "THESEUS_CREDENTIAL__SCOPES": "config:read config:write"
+      }
+    }
+  }
+}
+```
+
+## 工作原理
+
+### 架构分层
+
+```
+┌──────────────────────────────────────────┐
+│  MCP 表面层（server.py）                  │
+│  FastMCP · 9 工具 · 2 window:// 资源      │
+│  3 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
+```
+
+#### 两条路径对比
+
+| | 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, 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>>`
+
+### 关键模块
+
+| 模块 | 职责 |
+|------|------|
+| `server.py` | FastMCP 组合根，工具/资源注册，OAuth PRM 路由 |
+| `config.py` | `TheseusSettings`（pydantic-settings），三种凭证配置的判别联合 |
+| `transport.py` | `RobotClient` + `RobotAuth`（Bearer + X-TF-* 注入）+ `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` | `RequestContext` — X-TF-* 头部构建与校验 |
+| `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://` 静态中文指南 |
+
+## 开发
+
+```bash
+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 测试（需要真实机器人）
+
+```bash
+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
+```
+
+### 发布前准备
+
+```bash
+uv run poe ci && uv run poe build && uv run poe package-check
+```
+
+发布流程见 [发布文档](docs/releasing.md)：版本号由 `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](https://modelcontextprotocol.io/)
+- [A2C-SMCP protocol](https://github.com/A2C-SMCP/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