feat(selfhosted): add client-side MCP tools

[ark-hand]

Hand-written change from the internal SDK repository — not produced by make vendor.

• source subject: feat(selfhosted): add client-side MCP tools
• reason: No Ark-APIs provenance marker; treated as a hand-written source commit.

简述

为 Python self-hosted worker 增加 client-side MCP tools，并适配当前 Managed Agents Custom Tool 契约。core 保持 Python 3.8，可选官方 MCP extra 要求 Python 3.10+；同时修复同步、异步及 self-hosted 原始请求的 retry 行为。

改动

• core 增加协议无关 MCP Client Protocol、ToolDefinition、结果模型和 Custom Tool 转换。
• arkruntime[mcp] 接入官方 MCP Python SDK。
• 使用 AnyIO BlockingPortal 桥接 worker 线程，兼容 asyncio 与 Trio。
• 支持 text、image、embedded resource、PDF 与 structured content。
• type/properties/required 结构化传递，property 内本地引用内联，其余有效顶层约束以紧凑 JSON 写入 tool description。
• falsy 非对象 Schema 不再被静默当成默认 object，而是返回明确错误。
• MCP 凭证和连接仅保留在 worker 侧。

SDK retry 修复

• 默认最大重试次数保持 2 次，并修正文档中的默认值说明；首次等待改为 0.5 秒基数，之后指数增长并封顶 8 秒，每次减去 0–25% jitter。
• 优先读取 Retry-After-Ms，其次读取 Retry-After；支持小数数值以及 HTTP-date，完整保留亚秒精度。
• 同步与异步请求首次调用和后续重试分别携带 X-Stainless-Retry-Count: 0/1/2，调用方显式设置该 header 时保留调用方值。
• 修复单请求 max_retries=0 被错误回退为客户端默认值的问题。
• self-hosted 原始请求同步使用相同 retry-count、服务端等待提示、0–25% jitter、408/409/429/5xx 状态及 X-Should-Retry 控制；禁用 retry 的请求仍携带 retry-count=0。

其他行为修复

• 文本 content block 即使内容为空也保留 MA 契约必需的 text 字段。
• MCP 返回 isError=true 且没有内容时，生成 tool returned an error，避免空错误结果。
• embedded resource 转换失败时不再把 URI 写入 tool result，避免 signed URL 或查询凭证进入 MA、模型和日志。
• property 内已成功内联的 $defs/definitions 不再重复写入 description；仍被其他约束引用时继续保留。
• 不修改 MA 或 Agent Loop，仍适配现网 type/properties/required 三字段 Custom Tool 契约。

测试

• uv run ruff check src/ tests/
• uv run ruff format --check src/ tests/
• uv run pytest -q：83 passed
• retry 新增 server delay 优先级、小数秒/HTTP-date、退避序列、retry-count、自定义 header 与零重试配置测试。
• uv build
• 从新 virtualenv 安装构建出的 wheel 及 [mcp] extra，core/MCP import 成功。
• asyncio / Trio adapter tests 通过。
• 独立 STG harness 已验证同一 MA Custom Tool 事件契约全链路。

示例

• 新增 examples/self_hosted_mcp_worker，以最小粒度展示 tools/list -> Custom Tool 定义 -> MCP Tool 执行 -> EnvironmentWorker.run。
• 内置最小 stdio mcp_echo server；示例不负责创建 Agent、Session 或消费 SSE。
• 增加真实 stdio tools/list + tools/call 回归测试，并验证 MCP Python SDK 1.x/2.x 均可运行。

See merge request: !96

Sync-Source-Commit: 0feda8ade8873fc01df4e4df890cc9c85be929ae
Hand-Written-Reason: No Ark-APIs provenance marker; treated as a hand-written source commit.
Release-Version: 0.6.0

Created by ark-hand.