我们如何构建 Microsoft Learn MCP Server - Engineering@Microsoft
我们如何构建 Microsoft Learn MCP Server - Engineering@Microsoft
自 2025 年 6 月发布 Microsoft Learn 模型上下文协议（MCP）Server 以来，我们的目标很简单：让 AI 代理（AI Agent）能够轻松使用可信、最新的 Microsoft Learn 文档。GitHub Copilot 和其他代理越来越普遍，它们需要像人类使用浏览器那样，能够基于事实进行回答。Learn MCP Server 是一个远程服务器，通过 Streamable HTTP Transport 暴露代理友好的工具，其底层由 《我们如何构建“Ask Learn”》 中描述的同一 Learn 知识服务提供支持。
为什么是 MCP 和 Learn MCP Server？
现代 AI 代理可以通过 模型上下文协议 动态发现和使用工具，这是一种标准，允许代理在运行时协商能力、流式传输结果，并随着工具的演进进行适配。无需手动搜索、抓取页面或维护嵌入（Embedding），客户端只需连接到 Learn MCP Server，请求可用工具列表，并按代理的决策调用工具。VS Code 的 GitHub Copilot 以及其他 MCP 客户端可以为 Microsoft 技术提供准确的指导，而用户则能从基于官方 Learn 内容的答案中受益。
该服务器提供三种工具：
- microsoft_docs_search：返回标题、内容段落以及指向源文章的 URL。
- microsoft_docs_fetch：获取整页文章内容以获取更多上下文。
- microsoft_code_sample_search：专为在 Learn 文档中查找代码片段和示例而优化，使代理能够快速获取针对特定编程语言的示例，用于编码任务。
为什么是服务器，而不是另一个 API？
传统的 API 要求每个客户端进行集成开发，包括阅读文档、管理身份验证、格式化请求、处理错误以及随变化保持兼容性。在拥有数十个 AI 代理（每个代理能力各异）都需要可靠访问相同基础数据的环境中，这种模式难以扩展。MCP 从根本上采用了不同的方法。它没有采用自定义 REST 调用，而是提供了一种标准的、代理原生（agent-native）的方式，让工具在运行时被发现。任何兼容 MCP 的代理都可以连接到我们的远程端点，检查可用工具，自动理解它们的架构（Schema），并无需自定义编码即可开始使用。这种即插即用模式让代理能够适应合同变更，减少故障，避免硬编码集成，并且只需指向 Learn MCP Server 就能提供相关内容。
架构简述
我们在 Learn 知识服务之前托管了一个远程 MCP 服务器。MCP 客户端通过 Streamable HTTP Transport 进行连接。我们使用官方的 MCP C# SDK 来实现传输和会话处理，并将其托管在 Azure App Service 上。Learn MCP Server 由内容向量存储（Content Vector Store）提供支持，该服务与 Ask Learn 使用的知识服务相同。这意味着代理享有与微软用于基于 RAG 的体验相同的新鲜度保证、相关性排名和索引覆盖范围。如果说 Ask Learn 直接服务于终端用户的聊天，那么 Learn MCP Server 则将知识检索能力封装在标准协议中，使其可被任何兼容 MCP 的代理发现和使用。
以下经验教训阐述了 Learn 团队在设计、发布以及目前运营 Microsoft Learn MCP Server 过程中发现的关键点。这些教训涉及大规模构建面向代理系统的现实问题，而不仅仅是实现细节。我们分享的不仅是构建了什么，还有为什么我们做出的决策很重要，以及在这个过程中让我们感到惊讶的地方。这些教训反映了这段经历，塑造了我们在工具设计、检索集成以及协议驱动型产品体验方面的思路。
经验教训 1——“你的 API 不是 MCP 工具”
一个关键原则：为代理工作流设计工具，而不是镜像内部 API。Learn 知识服务暴露了许多参数，包括 topK、索引选择、阈值、OData 过滤器以及向量搜索 vs. 混合搜索。我们的工具将这些压缩为两个直观的操作（搜索、获取），匹配 LLM（大语言模型）代理自然遵循的“搜索-阅读”模式。我们明确记录了这种分离，以便未来的工具添加不会将底层检索选择泄露到代理合同中。
经验教训 2——远程服务器的行为类似于分布式系统
托管一个公共 MCP 服务器意味着要处理跨区域部署、动态缩放、CORS、会话亲和性、无状态性以及数据保护问题。尽管 MCP 只是“基于 JSONRPC 的工具”，但其运维现实与任何无状态、多区域服务类似。我们与 MCP C# SDK 维护者合作，确保遵循最佳实践，并实现我们自身的业务目标。
经验教训 3——工具描述就是你的代理体验
我们了解到，工具和参数描述对于代理和语言模型来说就像用户手册。微小的措辞变化就能显著影响工具的激活率。我们构建了一个自动评估工具，根据观察到的代理行为和成功指标来迭代描述——然后在会话刷新时部署客户端会发现更新后的描述。
经验教训 4——组合工具以获得更好效果
搜索和获取协同工作效果更佳。例如，客户端可以先找到最佳匹配，然后利用整页 Markdown 来锚定答案。我们调整了描述，明确教导这种后续使用方式，从而改善了下游代理的基于事实的准确性和引用质量。
经验教训 5——预期（并防御）硬编码的调用者
即使有了 MCP 动态工具发现，一些客户端仍然将工具架构视为固定 API 进行硬编码。当我们将参数从 question 重命名为 query 时，有 2–5% 的请求中断，直到我们在弃用窗口期同时支持了这两个名称（作为可选）。防御性演进是运营公共服务的一部分。为了帮助社区避免此类陷阱，Microsoft Research 引入了关于工具空间干扰的指南，并发布了 MCP Interviewer，可以在代理被干扰之前标记出架构和行为问题。我们在优化工具合同时使用了这些经验。
经验教训 6——让数据驱动迭代
汇总的使用模式表明，大多数请求与编码任务、解释和故障排除相关。我们优先针对这些观察到的意图调整描述和检索策略，以最大化影响。同时，产品文档 中包含代理指令，提示在涉及 Microsoft 技术时使用这些工具——这是另一个数据驱动的改进，旨在提高基于事实的准确性。
这将带来什么
以前，在开发环境中工作的工程师必须打开浏览器窗口，输入搜索查询，浏览搜索结果，打开一个或多个链接，阅读页面找到答案，然后复制回开发环境。现在，您可以将 Learn MCP Server 添加到您喜爱的代理中，让它直接从来源应用 Learn 内容，精准适用于您的情况。
请通过 Learn MCP Server 仓库 与我们联系，配置您的代理并获取更多信息。