[Epic] PaperBot MCP Bridge Runtime — 常驻会话代理桥、Deferred Discovery 与统一 Broker

## Parent Epic
- #197 Skill-Driven Architecture

## Related Issues
- Builds on: #210 `paperbot-mcp server — paper-specific tools for external agents`
- Unblocks / operationalizes: #202 `Claude Code Integration`, #203 `Studio Execution API`

## Summary

构建 **PaperBot MCP Bridge Runtime**：一个常驻后端的 **MCP 会话代理桥 / broker / control-plane**，统一负责 MCP session lifecycle、deferred discovery、tool/resource/prompt broker、auth/audit/isolation，以及 Web / CLI / host agents 的接入路径。

这不是自建 AgentSwarm runtime，也不是为某个 host 单独做 adapter。它的职责是把 `paperbot-mcp server` 从“可被连接的能力表面”升级为“可被稳定消费的运行时桥接层”。

核心方向：
- **backend-owned sessions**，而不是 browser-owned MCP connections
- **deferred discovery**，而不是把全量 tool schema eager 暴露给 UI / host / model
- **one broker surface** for tools/resources/prompts，而不是每个 client 各自实现一套 MCP client logic

---

## Problem

当前 MCP 路线已经具备了 capability surface，但消费层仍然偏“直连”和“薄封装”：

- 前端直接持有 MCP SDK client / transport，session ownership 在 UI 侧
- 工具发现与工具执行耦合在 client 侧，不利于 agent orchestration 与审计
- `inputSchema` 容易被 eager 拉取并在模型侧形成高 token 开销
- resources / prompts / future auth flows 缺少统一 broker
- CLI、Web、外部 host agent 的接入路径没有共享一套 session / catalog / error model
- 无法稳定支持会话复用、catalog cache、timeout policy、retry / reconnect、tenant isolation

这会使 `#210` 只停留在“server exists”，但无法演进到稳定、低耦合、低 token 成本的 host integration。

---

## Architectural Intent

PaperBot 需要的是 **MCP Bridge / Control Plane**，不是新的 agent runtime：

1. **Own MCP sessions, not agent orchestration**
   - PaperBot 持有 MCP connections、catalog cache、call routing、auth/audit。
   - Host agent 仍然负责 planning / reasoning / tool choice。

2. **Expose a thin broker surface**
   - 列目录、取帮助、执行 tool、读 resource、取 prompt 都通过统一 bridge API。
   - Web / CLI / host agents 不再各自管理 raw MCP session。

3. **Prefer deferred schema loading**
   - 默认只暴露 catalog summary（name / description / shape summary / schema hash）。
   - 详细 schema / help 按需获取。

4. **Keep domain logic in existing services/stores**
   - Bridge 不复制业务逻辑。
   - MCP tools/resources/prompts 继续复用现有 application / infrastructure 层。

---

## Scope

### 1. Persistent Session Manager
- 按 `user_id + workspace/run/conversation + server_name` 维护长生命周期 MCP session
- session TTL / heartbeat / idle eviction / reconnect policy
- stdio / streamable HTTP / SSE transport 抽象
- 支持显式 open / close / inspect

### 2. Catalog + Deferred Discovery
- 维护 tools / resources / prompts catalog cache
- 默认返回 compact catalog summary，而不是完整 schema
- 支持按需获取：
  - tool help / full schema
  - resource list / templates / read
  - prompt list / prompt get
- schema hash / cache invalidation / refresh 机制

### 3. Unified Broker API
- 统一 broker surface：
  - `list_catalog`
  - `get_tool_help`
  - `call_tool`
  - `list_resources`
  - `read_resource`
  - `list_prompts`
  - `get_prompt`
- 参数校验、错误归一化、timeout/cancellation model
- 工具调用 trace / audit / correlation IDs

### 4. Auth, Isolation, Safety
- user/workspace/session 级隔离
- higher-risk write / execute actions 的 gating policy
- 为未来 OAuth / credential pass-through / secret resolution 预留边界
- 避免 browser 直接持有高权限 MCP connection

### 5. Web / CLI / Host Integration Migration
- Web 不再直接管理 raw MCP SDK session
- CLI 不再分散实现 MCP consumption 逻辑
- Claude Code / Codex / OpenCode 走同一 bridge / helper path，而不是 per-host bespoke adapter
- Studio 通过 bridge/control-plane 读取 catalog、session、events、artifacts

### 6. Docs and Developer Experience
- 明确 host integration guidance
- 明确 bridge vs server vs domain tool 的边界
- 本地开发启动方式、调试方式、故障排查说明

---

## Explicit Non-Goals

- 不实现新的 custom agent router / multi-agent bus / orchestration runtime
- 不把 PaperBot 变成 host-specific adapter framework
- 不在 MCP bridge 之外复制 paper/domain services
- 不让浏览器长期承担 MCP session ownership
- 不为了“兼容一切 host”而引入厚重抽象层

---

## Deliverables

- 一个稳定的 **backend-owned MCP bridge runtime**
- 一套统一的 **broker API**，覆盖 tools / resources / prompts
- 一套 **compact discovery -> detailed help -> execution** 的消费路径
- 一套可审计、可隔离、可复用的 session lifecycle 管理能力
- Web / CLI 从 raw MCP client 迁移到 bridge surface
- 与 `#202` / `#203` 对齐的 host + Studio control-plane 集成说明

---

## Proposed Work Breakdown

### Phase A — Bridge Foundations
- [ ] 定义 application port：`MCPBridgePort`
- [ ] 建立 infrastructure 实现：transport factory / session manager / catalog cache
- [ ] 定义统一 response / error / trace model
- [ ] 支持 tools list + call 的最小桥接闭环

### Phase B — Resources / Prompts / Policy
- [ ] bridge 支持 resources list/read + templates
- [ ] bridge 支持 prompts list/get
- [ ] 接入 auth / permission / safety gating
- [ ] catalog refresh / invalidation / session inspection 能力

### Phase C — API & Control Plane
- [ ] 新增后端 MCP bridge API routes
- [ ] 支持 session create/read/close + broker call endpoints
- [ ] 对接 event log / execution traces
- [ ] 与 `#203` Studio execution/control-plane API 对齐

### Phase D — Client Migration
- [ ] Web 迁移到 bridge API，不再直接持有 raw MCP session
- [ ] CLI 迁移到 bridge helper / API surface
- [ ] host integration 文档更新，服务 `#202`
- [ ] 删除或降级旧的直连 MCP client 路径

### Phase E — Hardening
- [ ] timeout / retry / reconnect policy
- [ ] session eviction / cleanup / observability
- [ ] end-to-end tests for persistent sessions and brokered execution
- [ ] token / payload efficiency validation for deferred discovery path

---

## Acceptance Criteria

- [ ] PaperBot 后端拥有 MCP session lifecycle；Web 不再直接拥有长期 MCP session
- [ ] tool/resource/prompt 都能通过统一 broker surface 被消费
- [ ] 默认 discovery 返回 compact catalog summary，而不是完整 schema eager load
- [ ] 支持按需获取单个 tool 的详细 schema/help 并执行调用
- [ ] 所有 brokered MCP calls 都有 trace / audit / timeout / normalized error behavior
- [ ] 至少一条 Studio flow 与一条 host-agent flow 通过 bridge 跑通
- [ ] 现有 MCP domain tools 继续复用现有 services/stores，而不是平行实现
- [ ] 有明确迁移说明，解释 bridge 与 `paperbot-mcp server` 的职责边界

---

## Design Constraints

- 必须与 `#197` 保持一致：这是 **skill-driven architecture 的 consumption/control plane**，不是 AgentSwarm 回潮
- 必须建立在 `#210` 的 MCP capability surface 之上，而不是绕开它另造接口
- 不应要求模型直接背诵全量 PaperBot tool schemas
- 优先让 session / catalog / policy 聚合在后端，而不是散落在 Web/CLI/client SDK

---

## Risks / Open Questions

- session key 的边界应是 `user + workspace`、`user + run` 还是 `user + conversation`
- self-hosted `paperbot-mcp server` 与 external MCP servers 是否共用同一 bridge runtime
- bridge API 是作为 `#203` 的子集，还是独立 route namespace 更清晰
- 对 host agents 来说，最佳消费形态是 REST broker、thin CLI helper，还是两者并存

---

## Why This Is an Epic

这不是一个单点功能 issue，而是一层新的 **runtime consumption architecture**：

- 它横跨 MCP server、session lifecycle、client migration、Studio control plane、host integration、safety/audit
- 它会拆出多个 implementation issue
- 它决定 PaperBot 后续如何把 MCP 从“能力暴露”落到“稳定消费”



Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Epic] PaperBot MCP Bridge Runtime — 常驻会话代理桥、Deferred Discovery 与统一 Broker #393

Parent Epic

Related Issues

Summary

Problem

Architectural Intent

Scope

1. Persistent Session Manager

2. Catalog + Deferred Discovery

3. Unified Broker API

4. Auth, Isolation, Safety

5. Web / CLI / Host Integration Migration

6. Docs and Developer Experience

Explicit Non-Goals

Deliverables

Proposed Work Breakdown

Phase A — Bridge Foundations

Phase B — Resources / Prompts / Policy

Phase C — API & Control Plane

Phase D — Client Migration

Phase E — Hardening

Acceptance Criteria

Design Constraints

Risks / Open Questions

Why This Is an Epic

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

[Epic] PaperBot MCP Bridge Runtime — 常驻会话代理桥、Deferred Discovery 与统一 Broker #393

Description

Parent Epic

Related Issues

Summary

Problem

Architectural Intent

Scope

1. Persistent Session Manager

2. Catalog + Deferred Discovery

3. Unified Broker API

4. Auth, Isolation, Safety

5. Web / CLI / Host Integration Migration

6. Docs and Developer Experience

Explicit Non-Goals

Deliverables

Proposed Work Breakdown

Phase A — Bridge Foundations

Phase B — Resources / Prompts / Policy

Phase C — API & Control Plane

Phase D — Client Migration

Phase E — Hardening

Acceptance Criteria

Design Constraints

Risks / Open Questions

Why This Is an Epic

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions