mcp-for-beginners 实战：从客户端连接 Microsoft Learn Docs MCP 服务器，把官方文档直接接入你的工具链

• 教程
• 文档
• 人工智能

导读

你是否经常在文档站点、Stack Overflow 和搜索引擎标签页之间来回切换，只为了在写代码时找到一条准确的 API 说明？本篇文章基于开源课程 mcp-for-beginners 中的案例研究 09-CaseStudy/docs-mcp，完整演示如何从你自己的客户端应用连接Microsoft Learn Docs MCP 服务器，把官方文档检索直接嵌入控制台、Web 应用乃至 VS Code 编辑器。读完本文，你将掌握基于官方 MCP SDK + streamable HTTP 的客户端连接方法、microsoft_docs_search工具的调用与流式响应解析，以及一套「文档即服务」的三层落地范式：命令行检索 → 对话式 Web 应用 → 编辑器内 AI 协同。

案例背景：为什么要把文档带进开发工作流

现代开发早已不只是「写代码」本身，更关键的是在对的时间找到对的信息。文档无处不在，却很少出现在最需要它的地方——你的工具与工作流内部。本案例的核心理念是：将文档检索能力以 MCP（Model Context Protocol）的形式直接集成进应用，从而：

• 消除「代码 ↔ 文档」之间的上下文切换（context switching）；
• 实时获取最新、且对上下文敏感的 Microsoft Learn 官方内容；
• 为构建聊天机器人、IDE 扩展、Web 仪表盘等更高级的集成打下基础。

本案例共包含三个递进场景：场景一实现一个交互式控制台客户端，实时调用 Docs MCP 并解析流式响应；场景二把 Docs MCP 接入 Chainlit 对话式 Web 应用，自动生成按周拆解的学习计划；场景三则在 VS Code 内通过.vscode/mcp.json配置 MCP 服务器，配合 GitHub Copilot 实现不离开编辑器的文档检索与引用插入。

学习目标

完成本案例后，你将掌握：

• MCP 服务器-客户端通信的基础（针对文档检索场景）；
• 实现一个控制台或 Web 应用来连接 Microsoft Learn Docs MCP 服务器；
• 使用流式 HTTP 客户端进行实时文档检索；
• 在应用中正确记录（logging）并解读文档响应；
• 把 Docs MCP 与 GitHub Copilot 组合成 AI 驱动的文档工作流。

MCP 客户端通信基础：streamable HTTP 连接范式

三个场景虽然形态不同，但底层都复用同一套官方 MCP Python SDK 的客户端连接范式，核心调用链高度一致。从 scenario1.py 和 scenario2.py 的源码可以看到，连接过程由四个固定环节组成：

from mcp.client.streamable_http import streamablehttp_client from mcp import ClientSession # 1. 建立 streamable HTTP 传输层 async with streamablehttp_client("https://learn.microsoft.com/api/mcp") as (read_stream, write_stream, _): # 2. 在双向流之上创建客户端会话 async with ClientSession(read_stream, write_stream) as session: # 3. 初始化握手 await session.initialize() # 4. 调用工具并取回结果 result = await session.call_tool("microsoft_docs_search", {"question": "..."})

关键点说明：

• 端点固定为https://learn.microsoft.com/api/mcp，无需本地起服务，直接连接微软托管的 Docs MCP 服务器即可；
• streamablehttp_client返回的(read_stream, write_stream, _)三元组是 JSON-RPC 双向消息流，ClientSession负责协议级会话管理；
• session.initialize()完成能力协商握手，之后才能调用工具；
• 工具名是microsoft_docs_search，参数键在不同实现中有差异（详见下文场景一），务必与服务器端 schema 对齐。

场景一：实时文档检索的控制台客户端

场景一的目标是写一个应用：连接 Docs MCP 服务器，调用microsoft_docs_search工具，并把流式响应记录到控制台。官方给出的最小可运行示例（Python）如下：

import asyncio from mcp.client.streamable_http import streamablehttp_client from mcp import ClientSession async def main(): async with streamablehttp_client("https://learn.microsoft.com/api/mcp") as (read_stream, write_stream, _): async with ClientSession(read_stream, write_stream) as session: await session.initialize() result = await session.call_tool("microsoft_docs_search", {"query": "Azure Functions best practices"}) print(result.content) if __name__ == "__main__": asyncio.run(main())

从最小示例到生产级客户端：scenario1.py 的完整实现

仓库中的完整实现位于 scenario1.py，它在最小示例之上补齐了实战必备的四块能力：

1. 结构化日志（logging）

logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S' ) logger = logging.getLogger('mcp_client')

连接、会话初始化、每次查询执行都通过logger.info(...)记录，便于定位问题。

2. 交互式多轮查询循环

while True: user_query = prompt_user() if not user_query: print("Query cannot be empty. Please try again.") continue if user_query.lower() in ("exit", "quit"): print("Exiting client. Goodbye!") break result = await session.call_tool("microsoft_docs_search", {"question": user_query})

prompt_user()用input("> ")读取用户输入，并捕获KeyboardInterrupt/EOFError优雅退出——这对应了原文档要求的「允许用户输入多条搜索查询」的交互式控制台界面。

3. 结果解析

一个值得注意的实现细节：此处调用参数键是{"question": user_query}（与最小示例中的{"query": ...}不同，属于服务器 schema 允许的参数别名）。而响应内容的解析方式可以从源码中明确看到：

if hasattr(result, 'content'): for item in result.content: my_list = json.loads(item.text) # 每条文本内容是 JSON 数组 for doc in my_list: print(f"[Title]: {doc.get('title', 'No title')}") print(f"[Content]: {doc.get('content', 'No content')}")

即result.content中每一项的text字段本身是一段 JSON，反序列化后得到文档对象列表，每个对象含title与content字段。这印证了 Docs MCP 返回「结构化文档列表」而非纯文本的设计。

4. 错误处理

查询级异常被捕获并提示重试；连接级异常（网络不通、握手失败）会记录Connection error并以退出码 1 终止进程。运行效果与文档预期一致：

Prompt> What is Azure Key Vault? Answer> Azure Key Vault is a cloud service for securely storing and accessing secrets. ...

运行方式

pip install -r requirements.txt # 依赖见 09-CaseStudy/docs-mcp/solution/python/requirements.txt python scenario1.py

依赖清单（requirements.txt）包括mcp（官方 SDK）、chainlit、semantic-kernel，并额外固定werkzeug>=3.1.6以规避其安全公告（CVE-2025-66221 / CVE-2026-21860 / CVE-2026-27199）——这是仓库对供应链安全加固的一个实例。

场景二：基于 Chainlit 的交互式学习计划生成器

场景二把 Docs MCP 集成进 Web 开发项目：用户在浏览器聊天窗口输入「我要学 AI-102，请基于 Learn 给我 6 周学习路线」，应用就能返回按周拆解、带官方学习路径的详细计划。原文档中给出的最小示例基于 Chainlit + requests 直接 POST：

import chainlit as cl import requests MCP_URL = "https://learn.microsoft.com/api/mcp" @cl.on_message def handle_message(message): query = {"question": message} response = requests.post(MCP_URL, json=query) if response.ok: result = response.json() cl.Message(content=result.get("answer", "No answer found.")).send() else: cl.Message(content="Error: " + response.text).send()

生产级实现：MCP 作为 Semantic Kernel 插件

仓库中的完整实现 scenario2.py 展示了更有工程价值的模式——把 MCP 文档检索封装为 Semantic Kernel 插件，由 AI Agent 自主决定何时调用：

class MCPDocsPlugin: def __init__(self, mcp_server_url): self.mcp_server_url = mcp_server_url @kernel_function(name="search_docs", description="Search Microsoft Docs using MCP") async def search_docs(self, question: str) -> str: async with streamablehttp_client(self.mcp_server_url) as (read_stream, write_stream, _): async with ClientSession(read_stream, write_stream) as session: await session.initialize() result = await session.call_tool("microsoft_docs_search", {"question": question}) output = [] if hasattr(result, 'content'): for item in result.content: try: my_list = json.loads(item.text) for doc in my_list: output.append(f"**{doc.get('title')}**\n{doc.get('content')}") except Exception: output.append(item.text) return "\n".join(output) if output else "No content returned from the search."

随后的 Agent 编排逻辑（源码可见）包括：

• 在@cl.on_chat_start中构建Kernel，注册AzureChatCompletion服务；
• 设置FunctionChoiceBehavior.Auto()，让模型在需要文档时自动调用search_docs函数；
• 创建ChatCompletionAgent（名为DocsAgent），其指令明确要求「使用 MCPDocs 插件回答 Microsoft Docs 问题，并清晰排版答案」；
• @cl.on_message中通过async for content in agent.invoke(user_query)流式输出 token，实现打字机式的实时回答。

这意味着整个链路是：用户提问 → 模型规划 → 自动调用 Docs MCP 检索 → 模型基于检索结果组织回答 → 流式渲染到 Web 界面。

运行与必需的环境变量

chainlit run scenario2.py # 默认地址 http://localhost:8000

⚠️ 完整版依赖 Azure OpenAI，必须在python目录下的.env文件中配置（字段以仓库 solution/python/README.md 为准）：

AZURE_OPENAI_CHAT_DEPLOYMENT_NAME= AZURE_OPENAI_API_KEY= AZURE_OPENAI_ENDPOINT= AZURE_OPENAI_API_VERSION=

填充你的 Azure OpenAI 资源信息后再启动。仓库文档还提示，可通过 Microsoft Foundry（ai.azure.com）快速部署自己的模型。

可直接试用的示例查询

在聊天窗口输入以下任意一条，即可验证应用对不同学习目标与时长的适配能力：

• AI-900 certification, 8 weeks
• Learn Azure Functions, 4 weeks
• Azure DevOps, 6 weeks
• Data engineering on Azure, 10 weeks
• Microsoft security fundamentals, 5 weeks
• Power Platform, 7 weeks
• Azure AI services, 12 weeks
• Cloud architecture, 9 weeks

应用会解析主题与周数，查询 Docs MCP 获取相关学习资源，再组织成按周推进的结构化计划。

场景三：在 VS Code 编辑器内使用 Docs MCP

如果你只想把 Microsoft Learn 文档带进 VS Code，而不想写任何代码，可以直接在编辑器内配置 MCP 服务器。它让你能够：

• 不离开编码环境即可搜索、阅读官方文档；
• 在写 README 或课程文件时直接引用文档并插入链接；
• 让 GitHub Copilot 与 MCP 协同工作，形成 AI 驱动的文档工作流。

第一步：添加.vscode/mcp.json

在工作区根目录创建.vscode/mcp.json，写入以下配置（完整文件见 mcp.json）：

{ "servers": { "LearnDocsMCP": { "url": "https://learn.microsoft.com/api/mcp" } } }

该配置告诉 VS Code 如何连接到 Microsoft Learn Docs MCP 服务器。

第二步至第五步：与 GitHub Copilot 协同

仓库的 scenario3/README.md 提供了带截图的逐步指南，流程如下：

1. 安装并打开 Copilot Chat：在扩展市场安装 GitHub Copilot 扩展，从侧边栏打开 Copilot Chat 面板；
2. 启用 agent 模式并验证工具：在 Copilot Chat 中启用 agent 模式，随后确认LearnDocsMCP已出现在可用工具列表中——只有这一步通过，Copilot Agent 才能真正访问文档服务器；
3. 发起提问：在新聊天中向 agent 提问，例如「I'm trying to write a study plan for topic X. I'm going to study it for 8 weeks, for each week, suggest content I should take.」，agent 会通过 MCP 拉取相关文档并直接在编辑器中呈现；
4. 使用真实问题做活体验证：案例中还用了一个来自社区的真实问题（如何在 Azure AI Foundry 上部署多智能体解决方案），验证了面对复杂、开放式的工程问题时，agent 依然能检索并返回相关文档与要点。

可直接尝试的示例查询

• "Show me how to use Azure Functions triggers."
• "Insert a link to the official documentation for Azure Key Vault."
• "What are the best practices for securing Azure resources?"
• "Find a quickstart for Azure AI services."

这类工作流尤其适合技术课程作者、文档编写者，以及开发中高频查资料的工程师。

关键要点

把文档直接集成进工具，不只是便利性问题，更是生产力的质变。通过从自己的客户端连接 Microsoft Learn Docs MCP 服务器，你可以：

• 消除代码与文档之间的上下文切换；
• 实时获取最新、且感知上下文的官方文档；
• 构建更智能、更具交互性的开发者工具。

三个场景共同勾勒出一条清晰的进阶路径：控制台客户端（验证协议与解析）→ 对话式 Web 应用（叠加 Agent 编排）→ 编辑器内集成（零代码接入 + AI 协同），而底层始终是同一套 MCP streamable HTTP 客户端通信机制。

延伸阅读

• 案例完整代码与多运行时的解决方案索引：09-CaseStudy/docs-mcp/solution
• 场景一/二详细安装与使用说明：solution/python/README.md
• 场景三编辑器内集成逐步指南：solution/scenario3/README.md
• 原文档的「Additional Resources」一节（含 Microsoft Learn Docs MCP 官方仓库、Azure MCP Server 入门、MCP 协议介绍等外部资源）请查看 09-CaseStudy/docs-mcp/README.md
• 继续学习 MCP 全栈技能：10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/README.md

• 教程
• 文档
• 人工智能