# autos.mcp

独立、按需的 MCP 工具客户端，版本 `0.3.1`。支持 stdio 与 Streamable HTTP，明确支持 `2025-11-25` 和 `2026-07-28` 两个修订，不等于全部 MCP 规范。默认仍使用 2025；未调用时不启动服务或建立连接，不改 Autos 工具框架。

## AI 最小索引与按需导航

只需把 `autos.mcp` 作为最小库索引，按需读取本库参考中的“说明”与本指南，不必在全局提示词塞入所有子库说明。

- 直接连接和调用：`connect` / `withClient` / `callTool`；客户端方法查 `autos.mcp.client`。
- Autos HTTP 授权：`createOAuth`；通用授权及方法查 `autos.mcp.oauth`，可选登录窗口查 `autos.mcp.oauth.login`。
- 复用、配置、附件：`autos.mcp.session` / `autos.mcp.settings` / `autos.mcp.content`。
- 将 MCP 整理为长期工作流：加载 `autos.skills.skillCreator`，查询 `autos.skills.skillCreator.mcp` 的 `inspect` / `build` / `create` / `importServer`。直接调用不替代技能包；生成后仍需整理步骤、工具选择和验收条件。

此索引不代表未实现的 MCP 能力已经可用。导入库不会自动把 MCP 工具加入 Autos 的全局工具列表，也不启动服务或授权。

## Autos 默认 CIMD 候选

```aardio
import autos.mcp;
var auth,err,detail=autos.mcp.createOAuth({
    url="https://example.com/mcp"; // 替换为已信任的实际 endpoint
});
if(!auth) return null,err,detail;
// 构造不联网；按需显示 autos.mcp.oauth.login 窗口，由用户开始授权。
auth.close();
```

`createOAuth(config[,storeName])` 是 Autos 身份的便捷入口。仅在未指定 `clientId` 和 `clientMetadataUrl` 时提供 `https://aau.cn/oauth/mcp/client-metadata.json`，不将它强设为预注册 ID；授权服务器声明支持 CIMD 时才使用该候选。已有预注册配置或自定义 CIMD 不变，`clientMetadataUrl=false` 可禁用默认候选。`storeName` 仍为可选 DPAPI 存储名；不提供则只用内存。

其他应用直接 `import autos.mcp.oauth` 并调用 `autos.mcp.oauth(config,storeName)`，该中立构造函数没有 Autos 默认身份。回调仍默认 `redirectPort=0`，系统分配端口；DCR 仍须显式启用，不自动重试或重放业务请求。公开静态文档已托管，不等于完成外部授权服务器的 CIMD 抓取验收。

## 快速上手

```aardio
import autos.mcp;

var config = {
    command = "python";
    args = ["-u", "-m", "some_mcp_server"];
    timeoutMs = 30000;
};

var result,err,detail = autos.mcp.callTool(config,"tool_name",{});
if(!result){
    return {error=err;detail=detail};
}
return result;
```

## 多步工作流

```aardio
import autos.mcp;

var result,err,detail = autos.mcp.withClient(config,function(client){
    var tools,err = client.listTools();
    if(!tools) return null,err;
    return client.callTool("tool_name",{});
});
```

`withClient` 回调结束后会关闭客户端与它创建的 MCP 服务进程。单个请求超时或停止后不会自动重试；`detail.delivery="unknown"` 表示副作用可能已经发生，应先检查目标应用。

## HTTP 与惰性连接

HTTP URL 必须是真实 MCP endpoint，不是介绍网页。远程要求 HTTPS，本机回环可用 HTTP。示例公开测试服务：

```aardio
import autos.mcp.session;
var mcp = autos.mcp.session({
    url = "https://mcpplaygroundonline.com/mcp-complex-server?rev=2025-11-25";
    timeoutMs = 10000;
});
var tools,err,detail = mcp.listTools(); // 自动初始化
// 后续 mcp.callTool(...) 在本实例中复用连接。
mcp.close();
return {tools=tools;error=err;detail=detail};
```

`autos.mcp.session(defaultBackend[,configName])` 的默认值可为配置表，也可为已信任的本机解析函数 `function(options){return config;}`，供具体技能做自动发现或后续授权。配置名对应 `autos.mcp.settings` 的本机覆盖，不存在覆盖文件时使用默认 backend；损坏配置仍报错。

- `open/listTools/callTool/close`：同一 aardio 上下文的实例内复用，配置指纹变化则关闭旧连接；不同实例不共享。
- `configure`：保存本机覆盖、关闭旧连接；顶层字段替换，args/env/headers 不深层拼接。
- `options.backend`：完整临时替代，不继承已保存凭据，持续到 close。
- `withClient`：独立临时连接，回调结束自动关闭，不干扰惰性连接。
- 传输/协议故障后拒绝自动重连。显式 open 或 close 可解除失效，但绝不自动重放上一请求。
- 不跨 execute_code 隔离线程传递客户端；本库没有全局常驻 worker。需要连续有状态调用的工作流应放在同一上下文。显式 close 为首选；上下文退出也会释放所拥有的本地进程。

HTTP 每次 POST 支持 JSON 或请求范围 SSE，匹配最终结果后即停止读取。2025 保留 initialize/initialized、会话头、反向 ping、通知和关闭 DELETE；2026 使用 server/discover、逐请求元数据及镜像头，不发送会话头、DELETE 或 HTTP 取消通知。两代均不自动重连或重放业务调用。

## 配置与结果

stdio 的 `command` 与 `args` 分开，不经过 shell；可选 cwd、env、envFrom。HTTP 使用 url、headers、authToken（Bearer）。共同配置 timeoutMs、maxMessageBytes；protocolVersion 为 2025-11-25（默认）、2026-07-28 或 auto。请求头不允许覆盖 MCP 管理的 session/version/Mcp-Method/Mcp-Name/Mcp-Param-*/Content-Type/Accept 等字段；不跟随重定向、不使用全局 Cookie/自动登录，启用正常证书验证。

`autos.mcp.settings` 使用 Windows 用户 DPAPI 保存完整或部分本机配置，不要求 stdio command；`load(name,true)` 允许缺省文件，envFrom 在连接前解析。凭据不可放技能资源、URL、提示词或日志。图像使用 `autos.mcp.content.prepare` 转本地附件。

**区分两类认证：**

- stdio 服务自带的登录由服务/provider 负责；如官方 GitHub 本地服务可自己处理浏览器 OAuth。MCP 核心仅保持该服务连接，不读写它的令牌，不声明未实现的 elicitation 能力。授权与同一会话的后续调用应留在同一 aardio 上下文；不要用每次关闭进程的 callTool(config,...) 等待跨调用登录。
- 新增独立 [Remote HTTP OAuth 初版](oauth/index.html)：`import autos.mcp.oauth`，支持标准公共客户端发现、PKCE/loopback、DPAPI 与刷新；可选 `autos.mcp.oauth.login` 提供登录窗口。OAuth模块保持独立，HTTP错误保留httpStatus、wwwAuthenticate；其真实授权验收与双代传输回归分开。已完成受控 HTTP/刷新/界面测试，以及 Linear 真实浏览器授权、4 轮只读身份验收和 1 次显式刷新后的复测。真实服务使用 DCR；CIMD 的外部授权服务器抓取仍待独立验收，不宣称全部 OAuth 扩展合规。不自动重放上一调用。

授权 URL、验证码、原始 stderr 或服务端错误数据可能含敏感信息，不应整包写进日志或模型上下文。授权由用户在浏览器完成；不能把 Schema 列举成功算作 OAuth 验收通过。

工具结果中的 `isError=true` 是合法的业务结果，不等同于传输错误。对执行外部应用的服务还应检查业务后置条件，因为上游服务可能把异常文本放入正常 JSON-RPC result。

## 当前范围

已覆盖两个明确修订的发现/初始化、工具分页/调用、stdio 分帧/取消/进程清理、HTTP JSON/SSE/认证错误与版本化生命周期、技能实例惰性连接和附件转换。2026 MRTR仅识别并返回未完成；不声明 sampling/elicitation/roots 能力，不自动执行输入请求。Schema仅做必要结构及有界头注解检查，不是完整 JSON Schema 验证器，不校验所有输入/输出约束、不访问远程 $ref。

未实现其他协议修订、OAuth全部扩展、旧HTTP+SSE、订阅/恢复、自动重连/重发和并发调度。HTTP/stdio双代与集成已做本机真实传输测试；这不等于所有外部2026服务均已互通。CIMD外部AS抓取仍待后续独立验收。

## 0.3.0 双代选择与边界

```aardio
import autos.mcp;
var client,err,detail=autos.mcp.connect({
    url="https://example.com/mcp"; // 替换为你已信任的实际 endpoint
    protocolVersion="2026-07-28"; // 或 auto；省略则2025-11-25
    timeoutMs=30000;
});
if(!client) return null,err,detail;
var tools,err,detail=client.listTools();
client.close();
return tools,err,detail;
```

- `auto`只用连接阶段的server/discover探测，不使用工具调用探测。HTTP仅凭受控400/404/405旧代证据回退；已识别现代RPC错误、认证、429/5xx、网络故障或用户取消不回退。没有共同现代版本时直接报错，不自动尝试未实现的修订。
- stdio探针等待上限为1秒且不超过连接timeoutMs的1/3；静默或非现代RPC错误后在同一进程initialize，迟到响应按ID隔离。应为进程启动预留充足的timeoutMs；慢启动的纯2026服务宜显式指定版本，避免短探针误判。总体连接有界，不重启服务来探测。
- 每个2026请求都注入协议、空的已实现客户端能力和客户端身份，不修改调用方_meta。发现身份可省略，仅作展示，不用于权限判断。
- HTTP从实时目录获取x-mcp-header映射。callTool与request("tools/call")都使用同一路径；非法工具从目录排除并记录有界toolWarnings，不能直接绕过调用。Unicode、控制字符、首尾空白、sentinel字面值安全编码；0/false保留，null省略。仅对镜像整数要求JS安全范围。
- `detail.kind="input_required"`、`completed=false`表示尚未完成；原始数据位于detail.result。调用方必须单独处理，不能将其当成功或自动重放。完整MRTR交互暂未实现。
- structuredContent支持对象、数组、字符串、数值、false、0和显式null。为避免传输中的安全整数被舍入，JSON库仅对安全整数增加精确十进制输出；其他数值仍使用原序列化路径。

## 0.2.1 发行收敛

- 拒绝畸形 JSON-RPC error、请求/响应混合信封、非法反向请求 ID 与初始化信息；合法 RPC 错误与 isError 工具结果仍保留。
- stdio 在写入前检查取消和截止时间；明确未发送的失败返回 delivery=not_sent，开始发送后无法确认的失败仍为 unknown。
- skillCreator.mcp 生成技能的工具快照与公开默认 backend 使用 `$` 编译嵌入，发布 EXE 不依赖 IDE 库目录。本机配置、凭据与目标服务仍是外部环境，绝不嵌入。
- 不修改 Autos 主入口、全局工具框架、共享 RPC 或 Blender 原生库。

## 后续扩展约束

保持 client / transport / session / settings / content 的职责边界。OAuth 位于独立的 autos.mcp.oauth，不向 stdio 硬编码 GitHub。新协议代际须按整套生命周期/头部规则另做实测，不能只改版本字符串。

能力协商只声明已实现部分；资源/提示词可先用原生 request 试验，不预建全局调度器。采集到的工具描述、annotations 和 instructions 都是数据，不自动提升为系统指令。支持 AI 通过 aardio 代码直接调用，以及将 MCP 整理为普通工作流技能包；当前不增设全局 MCP 工具。可选的勾选接入与配置界面留待后续设计，本库不预先接管 Autos 配置。