Skip to content

Latest commit

 

History

History
100 lines (75 loc) · 6.21 KB

File metadata and controls

100 lines (75 loc) · 6.21 KB

独立插件、远程业务与 MCP 接入

本轮补齐原 Phase 2 的一段闭环:独立安装的插件可以被检查和加载,已有 HTTP 业务可以 适配成 Capability,标准 MCP 客户端可以调用同一能力。Agent 不是必要依赖。 这不是整个 Phase 2,也不代表生产权限、沙箱、TypeScript 客户端或社区作者验证已完成。

1. 直接运行完整验证

在 Caploom 仓库根目录执行:

uv sync --all-extras --frozen
uv run --all-extras python scripts/verify_interop_install.py

脚本构建两个 wheel,在仓库外创建独立环境,使用锁定依赖,启动三个自有回环 HTTP 服务并分别执行 Python SDK、Caploom MCP 与原生 MCP 对照。标准 MCP 客户端通过 stdio 启动真正的独立进程。结束时回收子进程和临时环境,不修改已有运行服务或业务数据。

结果在 artifacts/phase2-interop/verification.json,包括通过的语义用例、依赖版本、 源码与 wheel 哈希。旧成功记录在新一轮运行前删除;失败不会保留本轮虚假的成功证明。 所有库存和预留记录都是虚构测试数据,不是企业客户资料;没有模型调用或模型凭据。

2. 独立插件如何接入

examples/independent_inventory/ 是一个可以单独构建的分发包,而不是框架内核模块。 其结构为:

pyproject.toml                 分发包和标准 Entry Point
src/independent_inventory/
  plugin.toml                  导入前可读取的身份、兼容版本和声明
  legacy.py                    不依赖 Caploom 的旧业务
  models.py                    不依赖 Agent 的输入输出模型
  provider.py                  外部薄适配
  http_app.py                  不导入 Caploom 的已有式 HTTP 服务
  remote.py                    显式 HTTP 端点映射
  mcp_app.py                   Caploom MCP 出口
  direct_mcp.py                不导入 Caploom 的原生 MCP 对照

安装包由正常 Python 工具负责,Caploom 不下载或执行任意网络插件。 安装完成后依次调用 discover_plugins()inspect_plugin(name, distribution=...), 前两步不导入插件 Python。代码审查后才调用 load_plugin(..., trusted=True)。 它返回普通 Plugin,仍需显式放入 Runtime 并启动。发现、批准、加载、启用不是一回事。

支持的是 manifest 被 wheel RECORD 记录的文件系统安装形式;不通过猜目录兼容所有 editable 布局。manifest 的 trusted 声明不是安全证明,显式批准也不是进程隔离。

3. HTTP 不是业务契约

HttpProvider 只包装明确选择的端点,不自动把 OpenAPI 中所有操作公开。 GET 将标量输入映射为查询参数,POST 发送经过验证的 JSON;复杂旧协议应写普通薄适配。 Schema、Capability ID、写操作分类和 Provider Binding 与原本 SDK 相同。

HTTP client 归插件运行实例所有。停用先关闭新调用,再等待已有调用,最后释放连接。 默认不跟随重定向、不读取代理环境、不自动重试。远程地址用 HTTPS,演示只用回环 HTTP。 这是配置与资源管理边界,不是防御任意不可信网络或插件的沙箱。

特别重要:请求超时不表示远端没有执行。 演示提供 /reserve-delayed,它先扣减库存, 再延迟返回。客户端收到 REMOTE_OUTCOME_UNKNOWN 后,用原幂等键查询状态,确认已经 预留,再重放同一请求获得原结果,库存不会再次扣减。不能换一个新键盲目重试。 调用者取消或外层 Capability 超时也可能发生在写入之后,业务必须保留结果核对能力。

4. MCP 是消费者入口,不是业务核心

MCPExport 使用官方 MCP Python SDK 的 Server 和传输。工具名称与 Capability 的映射 必须明确配置;输入输出 Schema 来自原契约,调用仍经过 SDK Client 和统一 Invoker。 本轮验收覆盖标准 stdio 和进程内客户端。公开网络部署还需要宿主认证、权限与运维配置。

写操作默认拒绝。可信宿主可以提供 approve_write 回调,接收规范化输入、能力名和 本次请求 nonce;批准结果必须与这一份输入的摘要和 nonce 精确一致。 模型不能靠传入 confirmed=true_meta 给自己授权。输入、nonce、摘要不是身份认证。 接入企业环境时,回调应从宿主的可信身份和审批系统获取决策,而不是一律返回允许。

示例 --approve-fixture 只允许固定的 SKU-001、两件、interop-approved-key 请求, 用于可重复测试,不是通用自动审批开关。全局调用记录依然不是持久化授权审计。

5. 对照实验看什么

原生 MCPServer + HTTPX 对照使用同样的模型、旧业务 HTTP 服务与批准范围,也有正常 连接生命周期和错误处理。两边都应通过普通业务调用、默认拒绝、批准写入、重复请求和 状态查询。不能把“原生 MCP 也能做到”写成我们的独有优势。

Caploom 额外检验独立插件声明、明确 Binding、提供方替换、资源退出、跨消费者复用和 语义一致性。它们主要减少应用自己编写的管理逻辑,而不是使 API 调用本身成为新发明。 这不是完整 FastMCP/LangGraph 产品评测,也没有证明性能或接入耗时领先。

本轮可复现证据如下:

检查项 原生 MCP 对照 Caploom 路径
普通业务、默认拒绝、批准、重放与状态 9 项共同用例通过 同样的 9 项通过
连接生命周期与正常错误处理 使用原生 SDK/HTTPX 管理 使用 SDK/Fiber 所有权管理
运行中更换绑定、等待旧调用结束 对照没有另写这组应用逻辑;不代表原生 SDK 做不到 框架入口和回归测试覆盖
独立插件导入前检查、语义一致性 不属于这份最小协议对照的交付范围 独立 wheel 与共享用例验证
人工首次接入时间、吞吐和内存优势 未测量 未测量,不据此声称领先

下一步仍应找真实旧项目和非作者开发者验证首次接入时间、维护成本和接口兼容性。 TypeScript 生成、广泛插件发现、MCP 输入适配、生产身份与持久化审批继续按原路线推进。