讨论：将 MCP 和外部 API 能力保持在 bash-agent 核心之外

[lloydzhou]

背景

我希望 bash-agent 的核心保持简洁，专注于当前已经明确的职责：

• agent loop
• LLM 请求与响应处理
• 内置 tool 调用与结果回传
• session、compact 以及相关的生命周期管理

因此不建议直接在 bash-agent 内置完整的 MCP 客户端或其他复杂的外部扩展协议。

为什么不直接集成 MCP

MCP 集成并不只是增加几个 tool 定义，还需要在 agent 内维护一整套额外的生命周期和状态，例如：

• MCP session 和协议版本协商
• Streamable HTTP、stdio 等不同 transport
• 长连接以及断线、重连处理
• MCP server 子进程的启动、保活、退出和清理
• daemon、pid、socket 和锁等进程状态
• tools/list、tools/call 等协议请求的缓存和错误处理
• 凭据、超时、并发以及安全边界

这些能力只有部分用户会使用，但会直接增加核心程序的体积、内存占用、实现复杂度和长期维护成本，也会让核心 agent loop 和外部服务生命周期发生不必要的耦合。

bash-agent 更适合作为一个精简、稳定的 agent runtime，而不是同时承担 MCP runtime、连接管理器和外部服务编排器。

建议的架构边界

建议将外部扩展能力拆分为独立工具：

• mcpc：独立的 MCP CLI，负责 MCP server 连接、session、daemon、stdio 子进程和 Streamable HTTP 等状态。
• oapi：独立的 OpenAPI CLI，负责外部 HTTP API 的 spec、operation 和请求参数映射。
• bash-agent：只通过 CLI 调用这些外部工具，不在自身内部维护 MCP 的 state、进程和连接状态。

数据流与职责边界

1. 核心 agent loop 与外部扩展

flowchart LR
    U[用户] --> A[bash-agent]
    A --> L[LLM]
    L -->|工具调用与参数| A
    A -->|内置工具调用| T[内置工具]
    A -->|外部 CLI 调用| X[mcpc / oapi]
    T -->|工具结果| A
    X -->|结构化结果| A
    X --> M[MCP Server]
    X --> O[OpenAPI 服务]
    M -->|MCP 工具结果| X
    O -->|API 响应| X
    A -->|下一轮上下文或最终结果| L
    A --> R[用户]

Loading

bash-agent 只负责 agent loop、LLM 交互和工具结果回传；mcpc 与 oapi 负责各自的外部协议和连接细节。

2. 状态归属与调用边界

flowchart TB
    subgraph 核心运行时
        A[bash-agent]
        S[session / compact / loop 状态]
        A --- S
    end

    subgraph 外部扩展层
        C[mcpc]
        CS[MCP session / daemon / 连接状态]
        O[oapi]
        OS[OpenAPI spec / 请求映射]
        C --- CS
        O --- OS
    end

    A -->|CLI 参数或 JSON 输入| C
    C -->|CLI 输出或 JSON 结果| A
    A -->|CLI 参数或 JSON 输入| O
    O -->|CLI 输出或 JSON 结果| A
    C --> MCP[MCP Server]
    O --> API[外部 HTTP API]

Loading

核心运行时不持有 MCP 的 session、daemon、连接或外部 API 的 spec 状态；这些状态由独立工具自行维护，双方通过稳定的 CLI/JSON 契约通信。

这样可以达到：

1. 不需要外部扩展能力时，bash-agent 保持最小体积和较低内存占用。
2. 需要 MCP 或 OpenAPI 时，可以单独安装、升级和维护对应工具。
3. MCP server 崩溃、重连或协议升级不会把复杂状态带入核心 agent loop。
4. 外部工具可以独立演进，不必让所有 runtime 同步引入同一套复杂实现。
5. 需要单文件分发时，仍可以通过 BusyBox/applet 方式把这些工具组合到同一个发行物中，但逻辑上仍保持独立边界。

参考实现

这个方向可以参考 busyagent 的实现：

lloydzhou/busyagent#4

该 PR 在 BusyBox 风格的 agentutils 中加入了 mcpc、oapi（以及轻量的 jq），并抽出共享的 agent_common 层。这样 busyagent（可理解为嵌入 BusyBox 的 bash-agent）可以和这些独立 applet 配合使用，同时不需要把 MCP 的完整生命周期塞进 agent 本身。

其中 mcpc 负责 daemon 和 MCP session，oapi 负责 OpenAPI API 调用；agent 侧只需要把它们当作外部 CLI 能力使用。

希望讨论的问题

1. 是否认同将 MCP、OpenAPI 等外部扩展能力放在 bash-agent 核心之外？
2. bash-agent 侧是否只需要提供文档和稳定的 CLI 调用方式，而不增加 MCP 专用的内部状态管理？
3. 是否应约定 mcpc、oapi 与 bash-agent 之间的最小 CLI/JSON 输出契约？
4. 这些独立工具是否应继续作为单独项目维护，并在 Homebrew、APT、AUR 等渠道独立打包？
5. 是否需要在 bash-agent 中增加一个非常薄的“外部 CLI 工具”入口，还是直接复用现有的 Bash/tool 调用能力即可？

非目标

这个 issue 不提议在 bash-agent 中实现完整 MCP 协议栈、MCP daemon、长连接管理或外部 API 编排；重点是确认核心边界，以及 mcpc + oapi 与 agent 之间的组合方式。

[lloydzhou]

MCP / OpenAPI 能力已按 #88 的思路拆分为两个独立的 Rust CLI 项目并发布 v0.1.0：

mcpc — https://github.com/lloydzhou/mcpc

• MCP 客户端 CLI：connect（Streamable HTTP + stdio）、tools-list / tools-get / tools-call / ping、ls / close / grep、daemon stop
• 常驻 daemon 持有会话（Mcp-Session-Id 跨调用保持），socket 死后隐式拉起；会话元数据镜像到 servers/*.json 离线可用
• CLI 契约与 busyagent PR Summary 调用的缓存复用 #4 的 mcpc applet 逐条对齐

oapi — https://github.com/lloydzhou/oapi

• OpenAPI CLI：connect / sync / ls / rm / schema / api + oapi NAME OPERATION 调用（operationId kebab-case 化、path 参数位置化、query/header 参数 flag 化、-F 类型推断、--jq、-o text、--dry-run 敏感头掩码）
• CLI 契约与 busyagent PR Summary 调用的缓存复用 #4 的 oapi applet 逐条对齐

两项目各自单二进制、零共享代码、e2e 各 26 项全绿（对齐 C 版 testsuite 语义），GitHub Actions 覆盖 darwin/arm64、darwin/amd64（交叉编译）、linux/amd64、linux/arm64 四平台发布。

安装：

brew install lloydzhou/tap/mcpc
brew install lloydzhou/tap/oapi

bash-agent 核心保持零 MCP/OpenAPI 依赖，agent 通过这两个工具的 stdout JSON 契约组合能力。