aardio 文档

autos.mcp

独立、按需的 MCP 工具客户端,版本 0.3.3。支持 stdio 与 Streamable HTTP,明确支持 2025-06-18、2025-11-25 和 2026-07-28 三个修订,不等于全部 MCP 规范。省略 protocolVersion 时自动协商;未调用时不启动服务或建立连接,不改 Autos 工具框架。

AI 最小索引与按需导航

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

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

最小简化客户端 #

autos.mcp.simpleClient 适合无认证、复用等需求的简单 MCP 服务端。

示例:

import autos.mcp;

//构造函数永不失败,勿检查返回值
var mcp = autos.mcp.simpleClient(url="https://learn.microsoft.com/api/mcp") 

/*
- 所有方法不抛异常
- 总是返回单个表对象,本地错误则有 error,远端工具级错误刚看 isError 字段
- 参数 @1 必须是表对象(按惯例)
*/
var result = mcp.microsoft_docs_search( query="System.ValueTuple" )
print(result); 

var result = mcp.microsoft_docs_fetch( url="https://learn.microsoft.com/en-us/training/support/mcp" )
print(result); 

var result = mcp.microsoft_code_sample_search( query="System.ValueTuple C#");
print(result); 

mcp.close();

autos.mcp.simpleClient 的用法与 autos.mcp 命名空间其他对象完全不同, 它的方法不会返回多个返回值,参数 1 永远是表对象,返回值永远是单个 result 。 它返回的 result 是直接给 AI 看的(不需要其他额外处理),error/isError 字段遵守 MCP 规则。

其他工具函数的参数与

Autos 默认 CIMD 候选

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 抓取验收。

快速上手

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;

多步工作流

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。示例公开测试服务:

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;损坏配置仍报错。

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 省略时为 auto,也可指定 2025-06-18、2025-11-25 或 2026-07-28。请求头不允许覆盖 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 转本地附件。

区分两类认证:

授权 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 双代选择与边界

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();

// 调用工具
// var result,err,detail=client.callTool(name,arguments,options);

client.close();
return tools,err,detail;

0.2.1 发行收敛

后续扩展约束

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

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

Markdown 格式