1. 背景与能力概览
1.1 为什么需要文档MCP工具？
AI Agent 虽然能处理大量任务，但在深度对接云产品时往往力不从心。一个普遍的困境是：模型只能依赖训练时见过的文档，而阿里云产品迭代频繁，新功能、新 API、配置变更每天都在发生。
为了让用户更好的消费阿里云文档，继 LLMS.txt 之后，我们在阿里云 OpenAPI MCP 中也加入了文档相关工具。对于阿里云用户而言，文档工具的核心价值在于：让 AI Agent “基于实时官方文档回答”，在时效性、准确性、检索精度和链路完整性四个维度获得提升。
1.2 文档工具有哪些能力？
API MCP Server 是一个以阿里云 OpenAPI 操作为核心的 MCP Server。本次发布的文档工具集成在 API MCP Server Core 版本中，共包含 4 个工具：
| 能力 | 工具 | 典型用途 |
|---|---|---|
| 语义搜索 | SearchDocuments |
用关键词搜索全站帮助文档，定位目标文档 |
| 单篇精读 | GetDocument |
按 doc_id 读取文档完整正文 |
| 目录浏览 | GetDocumentTree |
按产品查看文档目录树，了解文档结构 |
| 全文命中 | GrepDocuments |
在指定产品文档中按关键词匹配，定位概念、报错、配置项 |
通过这 4 个工具，AI Agent可以完成“找到文档 → 读全文 → 浏览目录 → 精确定位”的完整检索链路，确保回答基于最新、最权威的阿里云官方内容。
1.3 安装方式
API MCP Server
安装 MCP 前需要先完成认证，API MCP Server 支持 OAuth 认证（交互认证）和 静态凭证认证，配置方法参考：选择认证方式
打开 API MCP Server 页面，查看 core 菜单下的配置信息，获取 MCP 服务端点（Endpoint）
在 Agent 中添加 MCP 信息，页面提供了一键配置至 Cherry Studio、Cursor、Claude Code等常见客户端的配置模板，可以直接使用。MCP 具有广泛的兼容性，其他支持该协议的客户端或程序也可参照实际情况自行配置。
更多详情请参考：OpenAPI MCP Server 使用指南
2. 使用场景示例
场景一：搜索国际站英文文档
用户原始请求：
"我想看看阿里云国际站上关于 OSS Bucket Policy 的英文文档，帮我找一下。"
Agent 分析： 用户需要国际站（intl）+ 英文（en）的文档，使用 SearchDocuments 进行语义搜索。
实际调用：
工具: mcp__openapi-mcp-core__AlibabaCloud___SearchDocuments
参数: {
"query": "Object Storage Service bucket policy",
"limit": 3,
"website": "intl",
"language": "en"
}
实际返回结果：
{
"results": [
{
"doc_id": 129733,
"title": "bucket-policy",
"url": "https://www.alibabacloud.com/help/en/oss/developer-reference/bucket-policy-3",
"product": "Object Storage Service",
"content": "Bucket policies are resource-based authorization policies that let bucket owners grant other users access to specific resources in Object Storage Service OSS.",
"website": "intl",
"language": "en"
},
{
"doc_id": 2841610,
"title": "put-bucket-policy",
"url": "https://www.alibabacloud.com/help/en/oss/developer-reference/put-bucket-policy",
"product": "Object Storage Service",
"content": "The put-bucket-policy command configures a bucket policy, granting access to resources in the bucket for the current Alibaba Cloud account or other Alibaba Cloud accounts, including RAM users and RAM roles.",
"website": "intl",
"language": "en"
},
{
"doc_id": 2983666,
"title": "Bucket Policy (Python SDK V2)",
"url": "https://www.alibabacloud.com/help/en/oss/developer-reference/put-bucket-policy-python-sdk-2-0",
"product": "Object Storage Service",
"content": "A bucket policy is an authorization policy for OSS buckets. It allows you to grant or restrict fine-grained access to specific OSS resources to principals.",
"website": "intl",
"language": "en"
}
],
"matched_filters": {
"product": "", "doc_type": null, "website": "intl", "language": "en" }
}
小结： 通过 website: "intl" 和 language: "en" 参数，精准命中了国际站的英文文档。返回的 doc_id 可直接传给 GetDocument 读取全文。
场景二：定位某篇文档在产品目录中的位置
用户原始请求：
"我之前看到一篇 ECS 的文档叫'创建实例'，doc_id 是 108442，想知道它在 ECS 文档目录里属于哪个章节下面。"
Agent 分析： 用户想了解文档的层级结构和上下文位置，使用 GetDocumentTree 并传入 doc_id。
实际调用：
工具: mcp__openapi-mcp-core__AlibabaCloud___GetDocumentTree
参数: {
"doc_id": 108442,
"depth": 3,
"language": "zh",
"website": "cn"
}
实际返回结果（节选关键路径）：
{
"product": "云服务器 ECS",
"website": "cn",
"language": "zh",
"children": [
{
"title": "用户指南",
"doc_id": 2399509,
"children": [
{
"title": "实例",
"doc_id": 108375,
"children": [
{
"title": "实例概述与选型", "doc_id": 2986096 },
{
"title": "创建实例", "selected": true, "doc_id": 108442 },
{
"title": "连接实例", "doc_id": 48428 },
{
"title": "管理与配置实例", "doc_id": 108403 },
{
"title": "升降配实例", "doc_id": 108404 },
{
"title": "释放实例", "doc_id": 25442 }
]
}
]
}
]
}
小结： 返回结果在命中节点上标记了 "selected": true，清晰展示出文档层级路径为：云服务器 ECS → 用户指南 → 实例 → 创建实例。
场景三：搜索 + 精读组合（函数计算冷启动优化）
用户原始请求：
"函数计算冷启动怎么优化？帮我找一下官方的最佳实践文档，要看完整内容。"
Agent 分析： 分两步：先 SearchDocuments 再 GetDocument。
第一步 — 搜索：
工具: mcp__openapi-mcp-core__AlibabaCloud___SearchDocuments
参数: {
"query": "函数计算 cold start 冷启动优化",
"limit": 3,
"website": "cn",
"language": "zh"
}
搜索返回结果：
{
"results": [
{
"doc_id": 2513659,
"title": "函数计算冷启动优化最佳实践",
"url": "https://help.aliyun.com/zh/functioncompute/fc/use-cases/best-practice-for-reducing-cold-start-latencies",
"product": "函数计算",
"content": "本文介绍如何通过设置函数计算的最小实例数优化弹性实例的冷启动问题..."
},
{
"doc_id": 2513553,
"title": "配置最小实例数弹性策略",
"url": "https://help.aliyun.com/zh/functioncompute/configure-launch-snapshot-and-auto-scaling-rules",
"product": "函数计算",
"content": "可以有效避免函数调用高峰期间因实例冷启动导致的请求延迟问题..."
},
{
"doc_id": 2513646,
"title": "请求级别指标日志",
"url": "https://help.aliyun.com/zh/functioncompute/fc/request-level-metric-logs",
"product": "函数计算",
"content": "冷启动。当请求抵达函数计算时，函数计算系统没有已经启动的函数实例执行请求..."
}
],
"matched_filters": {
"product": "", "doc_type": null, "website": "cn", "language": "zh" }
}
第二步 — 精读（取第一篇最相关的）：
工具: mcp__openapi-mcp-core__AlibabaCloud___GetDocument
参数: {
"doc_id": 2513659,
"language": "zh",
"website": "cn"
}
精读返回结果（节选）：
{
"doc_id": 2513659,
"url": "https://help.aliyun.com/functioncompute/fc/use-cases/best-practice-for-reducing-cold-start-latencies",
"title": "函数计算冷启动优化最佳实践",
"product": "functioncompute",
"content": "本文介绍如何通过设置函数计算的最小实例数优化弹性实例的冷启动问题，提高函数性能。\n\n## 什么是冷启动\n函数计算默认使用弹性实例，即按请求自动弹性，收到请求时系统自动创建实例处理请求，无请求后实例自动回收。冷启动是指在函数调用链路中的代码下载、启动函数实例容器、运行时初始化、代码初始化等环节。\n\n## 优化冷启动\n建议从以下几方面优化：\n* 精简代码包 — 去掉不必要的依赖，删除无用文件降低下载和解压时间\n* 选择合适的函数语言 — Python轻量语言可大幅降低长尾延迟\n* 选择合适的内存 — 内存越大，CPU资源越多，冷启动表现越优\n* 降低冷启动概率 — 使用 Initializer 回调、设置最小实例数"
}
小结： 两步组合是最典型的用法。搜索结果中的 doc_id 可直接传给 GetDocument，获取完整的 Markdown 正文用于回答用户。
场景四：浏览产品文档目录树（了解 OSS 有哪些文档章节）
用户原始请求：
"我想看看 OSS 对象存储的文档整体结构，有哪些大章节？"
Agent 分析： 使用 GetDocumentTree 并传入 product: "oss"。
实际调用：
工具: mcp__openapi-mcp-core__AlibabaCloud___GetDocumentTree
参数: {
"product": "oss",
"depth": 2,
"language": "zh",
"website": "cn"
}
实际返回结果（节选）：
{
"product": "对象存储",
"website": "cn",
"language": "zh",
"children": [
{
"title": "用户指南",
"doc_id": 31823,
"url": "https://help.aliyun.com/oss/user-guide",
"children": [
{
"title": "开始使用", "doc_id": 31816 },
{
"title": "访问域名与网络连接", "doc_id": 2977361 },
{
"title": "存储空间（Bucket）", "doc_id": 2977362 },
{
"title": "对象/文件（Object）", "doc_id": 2977363 },
{
"title": "OSS Vectors", "doc_id": 2980225 },
{
"title": "OSS Tables", "doc_id": 3029541 },
{
"title": "多模态数据生产与转化", "doc_id": 3043102 },
{
"title": "权限与访问控制", "doc_id": 2995527 },
{
"title": "安全合规", "doc_id": 2977367 },
{
"title": "成本优化", "doc_id": 2977364 },
{
"title": "数据保护", "doc_id": 2977370 },
{
"title": "数据处理", "doc_id": 2977372 },
{
"title": "数据迁移", "doc_id": 2977374 },
{
"title": "静态网站托管", "doc_id": 2977384 }
]
},
{
"title": "开发参考",
"doc_id": 2391490,
"children": [
{
"title": "API参考", "doc_id": 31946 },
{
"title": "SDK参考", "doc_id": 32006 },
{
"title": "常用工具", "doc_id": 32182 },
{
"title": "OSS与Amazon S3兼容", "doc_id": 357693 },
{
"title": "OSS签名机制指南", "doc_id": 2881163 }
]
},
{
"title": "产品计费",
"doc_id": 48259,
"children": [
{
"title": "了解计费", "doc_id": 2873729 },
{
"title": "账单与费用管理", "doc_id": 2987632 }
]
},
{
"title": "常见问题",
"doc_id": 2982296,
"children": [
{
"title": "开始使用", "doc_id": 131310 },
{
"title": "存储空间 (Bucket)", "doc_id": 456313 },
{
"title": "对象/文件（Object）", "doc_id": 456310 },
{
"title": "安全合规", "doc_id": 456364 }
]
},
{
"title": "动态与公告",
"doc_id": 384052,
"children": [
{
"title": "发布记录", "doc_id": 2845534 },
{
"title": "服务公告", "doc_id": 2922016 }
]
}
]
}
小结： 传入 product: "oss" 即可拿到 OSS 文档的完整顶层框架，共 5 个一级章节：用户指南、开发参考、产品计费、常见问题、动态与公告。用户可以根据章节标题和对应的 doc_id 进一步深入浏览，或直接把感兴趣章节的 doc_id 传给 GetDocument 读取正文。
场景五：在指定产品文档内按关键词精确查找（ECS 安全组）
用户原始请求：
"我要在 ECS 的文档里找所有跟'安全组'相关的文档，帮我列几篇出来。"
分析： 用户已经锁定了产品（ECS）和关键词（安全组），属于产品内精确查找场景，使用 GrepDocuments。
实际调用：
工具: mcp__openapi-mcp-core__AlibabaCloud___GrepDocuments
参数: {
"product": "ecs",
"pattern": "安全组",
"limit": 5,
"website": "cn",
"language": "zh"
}
实际返回结果：
{
"product_code": "ecs",
"pattern": "安全组",
"matches": [
{
"title": "5分钟学会安全组配置",
"url": "https://help.aliyun.com/ecs/user-guide/5-minute-guide-to-security-groups-secure-and-precise-network-access-control",
"matched_text": "如何登录ECS？5种方式全面解析\n5分钟学会安全组配置\n使用限制",
"line_no": 21
},
{
"title": "安全组",
"url": "https://help.aliyun.com/ecs/user-guide/security-groups-1",
"matched_text": "路径MTU发现机制（PMTUD）\n安全组\n安全组概述",
"line_no": 418
},
{
"title": "安全组概述",
"url": "https://help.aliyun.com/ecs/user-guide/overview-44",
"matched_text": "安全组\n安全组概述\n安全组规则",
"line_no": 419
},
{
"title": "安全组规则",
"url": "https://help.aliyun.com/ecs/user-guide/security-group-rules",
"matched_text": "安全组概述\n安全组规则\n使用安全组",
"line_no": 420
},
{
"title": "使用安全组",
"url": "https://help.aliyun.com/ecs/user-guide/start-using-security-groups",
"matched_text": "安全组规则\n使用安全组\n普通安全组与企业级安全组",
"line_no": 421
}
],
"total": 29,
"truncated": true,
"llms_txt_url": "https://help.aliyun.com/zh/ecs/llms.txt"
}
小结： GrepDocuments 在 ECS 全量文档中命中了 29 篇含"安全组"的文档（limit: 5 只返回前 5 条，truncated: true 表示已截断）。每条结果包含标题、URL、命中片段和行号，用户可以直接点开 URL 或用 GetDocument 读取全文。其中"5分钟学会安全组配置"和"安全组概述"是最贴合需求的专项文档。返回的 llms_txt_url 还可进一步拉取该产品的 llms.txt 全文索引。
3. 更多工具介绍
了解更多 API MCP Server 相关工具使用方法，请参考 OpenAPI MCP Server Core 工具使用指南 。
