mcp-for-beginners 学习指南:MCP 课程体系、仓库导航与实践路线图

原创2026-10-08 18:56:291,959 阅读
文章标签:教程示例工程MCP 服务MCP Clients人工智能

mcp-for-beginners 学习指南:MCP 课程体系、仓库导航与实践路线图

本指南面向希望系统学习 Model Context Protocol(MCP)的 AI 开发者、系统架构师与软件工程师,全面梳理 mcp-for-beginners 开源课程(仓库名 GitHub_Trending/mc/mcp-for-beginners)的十二大模块结构、视觉课程地图、多语言示例代码与进阶主题。读完本文,你将掌握该课程仓库的高效导航方法、语言导向的学习路径,以及从 MCP 基础到安全加固、数据库集成和生产级部署的完整实践路线图。

MCP 与课程仓库概览

Model Context Protocol(MCP)是 AI 模型与客户端应用之间交互的标准化框架。它最初由 Anthropic 创建,如今由官方 GitHub 组织下的更广泛 MCP 社区共同维护。MCP 解决了 AI 应用中"每个模型与每个工具都需要定制化连接"的碎片化问题,通过一套统一的协议约定,让开发者只需构建一次工具即可接入多种 AI 系统。

mcp-for-beginners 课程仓库正是围绕这一协议设计的系统性入门课程,提供 C#、Java、JavaScript、Python、TypeScript(以及仓库中的 Rust 示例)等多语言动手代码示例,目标受众包括 AI 开发者、系统架构师与软件工程师。仓库配套的 study_guide.md 与多语言译本(如 孟加拉语版)为学习者提供了结构化的导航入口。

协议版本说明:本课程遵循 MCP Specification 2026-07-28(当前协议修订版),该版本引入无状态协议核心、Extensions 扩展框架,并废弃了 Roots、Sampling 与 Logging。部分动手示例因 SDK 尚未完全采用新 API 而仍标注为 2025-11-25 版本,详见 01-CoreConcepts/mcp-2026-07-28.md 的迁移说明。

视觉课程地图:十二大模块全景

课程仓库以 mermaid mindmap 形式呈现完整的知识拓扑,从入门到进阶共十二个主分支,每个分支下挂载该阶段的核心知识点:

模块 主题 关键知识点
00-Introduction 协议入门 协议概述、标准化价值、真实用例、AI 集成基础
01-CoreConcepts 核心概念 客户端-服务器架构、协议组件、消息模式、传输机制、实验性 Tasks、工具注解
02-Security 安全 AI 特有威胁、2025 最佳实践、Azure Content Safety、认证与授权、Microsoft Prompt Shields、OWASP MCP Top 10、Sherpa 安全工作坊
03-GettingStarted 动手入门 首个服务器实现、客户端开发、LLM 客户端集成、VS Code 扩展、SSE 服务器、HTTP Streaming、AI Toolkit 集成、测试框架、高级服务器用法、简单认证、部署策略、MCP Hosts、MCP Inspector
04-PracticalImplementation 实战落地 多语言 SDK、测试与调试、提示词模板、示例项目、生产模式、分页策略
05-AdvancedTopics 进阶主题 上下文工程、Foundry Agent 集成、多模态工作流、OAuth2、实时搜索、流式协议、Root Contexts、路由策略、采样技术、扩展方案、安全加固、Entra ID、Web Search MCP、协议特性深潜、对抗式多智能体推理
06-CommunityContributions 社区贡献 代码贡献、文档、MCP 客户端生态、MCP 服务器注册表、图像生成工具、GitHub 协作
07-LessonsfromEarlyAdoption 早期采用经验 生产部署、Microsoft MCP 服务器、Azure MCP 服务、企业案例、未来路线图
08-BestPractices 最佳实践 性能优化、容错、系统韧性、监控与可观测性
09-CaseStudy 案例研究 Azure API Management、AI 旅行代理、Azure DevOps 集成、文档 MCP、GitHub MCP Registry、VS Code 集成、真实实现
10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit 动手工作坊 MCP 服务器基础、进阶开发、AI Toolkit 集成、生产部署、4-Lab 结构
11-MCPServerHandsOnLabs 数据库集成实验室 PostgreSQL 集成、零售分析用例、行级安全、语义搜索、生产部署、13-Lab 结构
12-tooling 工具链 Copilot 应用中的 MCP

仓库结构与十二大模块详解

仓库按编号组织的十二个主目录构成完整学习闭环,每个目录聚焦 MCP 的一个侧面。

模块 0-1:入门与核心概念

00-Introduction/README.md 提供协议概述、AI 流水线中标准化的重要性,以及实用用例与收益。它用"通用翻译器"与"USB-C"类比帮助初学者建立心智模型——就像 USB 端口让任何设备都能连接电脑,MCP 让 AI 模型以标准化方式连接任何工具或服务。

01-CoreConcepts/README.md 深入讲解客户端-服务器架构、协议主要组件、MCP 消息模式与传输机制。配套的 mcp-2026-07-28.md 是理解当前协议的关键文档,其核心变化包括:

  • 无状态协议核心:2026-07-28 是 MCP 发布以来最大规模修订。六个 Specification Enhancement Proposals(SEP)在传输层移除协议级会话,使 MCP 变为无状态。旧版(2025-11-25)依赖 Mcp-Session-Id 头将请求钉死在某个服务器实例上,水平扩展需要在负载均衡器上做粘性路由并共享会话存储;新版每个请求自包含(携带 MCP-Protocol-Version、Mcp-Method、Mcp-Name 头),任意服务器实例均可处理。
  • Extensions 扩展框架:扩展成为一类一等、带版本机制的协议能力,随本版本发布的两个扩展是 MCP Apps 与 Tasks。
  • 特性废弃:Roots、Sampling、Logging 在新的生命周期策略下被废弃;工具 inputSchema/outputSchema 全面切换为 JSON Schema 2020-12。
  • 授权加固:要求客户端校验授权响应中的 iss 参数(RFC 9207),动态客户端注册(DCR)被废弃,新实现应改用 Client ID Metadata Documents(CIMD)。

模块 2:MCP 安全体系

安全被课程放在第二个模块,与微软 Secure by Design 原则(Secure Future Initiative)保持一致。MCP 在带来强大 AI 能力的同时,也引入了超出传统软件风险的安全挑战。课程在 02-Security/README.md 中覆盖了六大 AI 特有威胁:

  • 提示注入与工具投毒:恶意指令混入模型上下文、或攻击者篡改工具元数据诱导模型执行非预期操作;
  • 会话劫持与困惑代理问题(confused deputy):攻击者诱使高权限代理执行越权动作;
  • 令牌透传漏洞(token passthrough):会话令牌被不当传递导致权限外泄;
  • 过度授权与访问控制不足:权限粒度过粗或入口限制缺失;
  • AI 组件供应链安全;
  • Microsoft Prompt Shields 集成:为 MCP 工作负载提供提示注入防护。

课程还覆盖认证与授权策略,并提供 CIMD 与 DCR 授权示例 的动手实践——该示例对比了优先推荐的 CIMD 注册与已废弃的 DCR 回退方案。此外,02-Security 目录下还包含多份深度安全文档:

安全章节还推荐了 MCP Security Summit Workshop(Sherpa) 这一动手安全训练营,其"漏洞利用→修复→验证"方法论结合 OWASP MCP Top 10 风险映射,覆盖身份(OAuth 2.1、Azure Managed Identity、Key Vault)、网关(API Management、Private Endpoints)、I/O 安全(提示注入、PII 保护)、监控(Log Analytics、威胁检测)等多个营地。

模块 3:Getting Started 动手入门

03-GettingStarted/README.md 是课程的实操核心,包含 15 个小节与 5 个语言示例。学习目标包括搭建 C#、Java、Python、TypeScript、JavaScript 的开发环境、构建带自定义资源/提示词/工具的 MCP 服务器、创建连接服务器的主机应用、测试与调试实现,以及对接主流 LLM 服务。其小节结构如下:

  • 3.1 首个服务器(01-first-server):创建第一个 MCP 服务器,并使用 MCP Inspector 工具检查调试;
  • 3.2 客户端开发(02-client):编写连接服务器的客户端;
  • 3.3 LLM 客户端集成(03-llm-client):为客户端接入 LLM,使其与服务器"协商"执行动作;
  • 3.4 VS Code 集成(04-vscode):在 VS Code 中消费 MCP 服务器(含 GitHub Copilot Agent 模式);
  • 3.5 stdio 服务器(05-stdio-server):stdio 传输是本地 MCP 服务器-客户端通信的推荐标准,基于子进程提供安全通信与内置进程隔离;
  • 3.6 HTTP Streaming(06-http-streaming):讲解 MCP 2026-07-28 中的标准远程传输 Streamable HTTP,同时保留旧版基于会话的实现;
  • 3.7 AI Toolkit 集成(07-aitk):使用 VS Code 的 Microsoft Foundry Toolkit 消费与测试 MCP 客户端/服务器;
  • 3.8 测试(08-testing):多种服务器与客户端测试方式;
  • 3.9 部署(09-deployment):本地开发到云端部署的多种方案;
  • 3.10 高级服务器用法(10-advanced):进阶功能与架构优化;
  • 3.11 简单认证(11-simple-auth):从 Basic Auth 到 JWT 与 RBAC 的完整认证路径;
  • 3.12 MCP Hosts(12-mcp-hosts):配置 Claude Desktop、Cursor、Cline、Windsurf 等主机客户端,涵盖传输类型与排障;
  • 3.13 MCP Inspector(13-mcp-inspector):交互式调试工具、资源与协议消息;
  • 3.14 采样(14-sampling):讲解 2025-11-25 遗留 Sampling 原语及其向直接 LLM Provider 集成迁移的方案(2026-07-28 中已废弃);
  • 3.15 MCP Apps(15-mcp-apps):构建既能应答又带 UI 指令的 MCP 服务器。

该模块还提供了 Java Calculator、.NET Calculator、JavaScript Calculator、TypeScript Calculator、Python Calculator 等语言示例,以及 Python、TypeScript、Java、.NET 官方 SDK 清单(Rust SDK、Go SDK、Kotlin SDK、Swift SDK 亦在官方 SDK 列表之列)。需要注意的是,SDK 对 2026-07-28 的支持按语言独立推进,运行示例前应核对包版本与 SDK 发布说明。

模块 4:实战落地

04-PracticalImplementation/README.md 将 MCP 从理论推向真实应用,涵盖多语言 SDK 使用、调试测试与验证技术、可复用提示词模板与工作流构建,以及带实现示例的示例项目。样本按语言组织在 samples 目录下:C#、Java with Spring(Container App 示例)、TypeScript(容器示例)、JavaScript、Python。该模块还包含分页专题 pagination/README.md,讲解基于游标的分页策略,用于处理大数据量结果集。

模块 5:进阶主题

05-AdvancedTopics/README.md 面向生产级 MCP 应用,覆盖多模态集成、可扩展性、安全最佳实践与企业集成,共 17 个小节:

  • 5.1 Azure 集成(mcp-integration):MCP 服务器在 Azure 上的部署集成;
  • 5.2 多模态(mcp-multi-modality):音频、图像与多模态响应示例;
  • 5.3 OAuth2 演示(mcp-oauth2-demo):基于 Spring Boot 的最小 OAuth2 应用,同时充当授权服务器与资源服务器,演示令牌安全签发、受保护端点、Azure Container Apps 部署与 API Management 集成(含 Java 源码 与 pom.xml);
  • 5.4 Root Contexts(mcp-root-contexts):2025-11-25 遗留 Roots 原语及迁移选项(2026-07-28 中已废弃);
  • 5.5 路由(mcp-routing):不同类型的 MCP 路由策略;
  • 5.6 采样(mcp-sampling):遗留 Sampling 技术及迁移方案(已废弃);
  • 5.7 扩展(mcp-scaling):MCP 实现的扩展方法;
  • 5.8 安全(mcp-security):高级安全考量与服务器加固;
  • 5.9 Web 搜索(web-search-mcp):基于 Python 的 MCP 服务器与客户端,集成 SerpAPI 实现实时网页、新闻、产品搜索与问答,演示多工具编排、外部 API 集成与健壮错误处理(server.py / client.py);
  • 5.10 实时流式(mcp-realtimestreaming):数据驱动场景中的实时数据流;
  • 5.11 实时搜索(mcp-realtimesearch):MCP 如何标准化 AI 模型、搜索引擎与应用之间的上下文管理;
  • 5.12 Entra ID 认证(mcp-security-entra):基于 Microsoft Entra ID 的云身份与访问管理,确保只有授权用户与应用能与 MCP 服务器交互;
  • 5.13 Foundry Agent 集成(mcp-foundry-agent-integration):将 MCP 服务器与 Microsoft Foundry Agent 集成,实现工具编排与企业 AI 能力(含 mcp_support_python.ipynb 与 mcp_support_dotnet.ipynb 笔记本);
  • 5.14 上下文工程(mcp-contextengineering):上下文优化、动态上下文管理与 MCP 框架内的提示词工程策略;
  • 5.15 自定义传输(mcp-transport):面向特定通信场景的自定义传输机制;
  • 5.16 协议特性深潜(mcp-protocol-features):进度通知、请求取消、资源模板与错误处理模式;
  • 5.17 对抗式多智能体推理(mcp-adversarial-agents):两个立场对立的 Agent 共享同一套 MCP 工具进行结构化辩论,由裁判 Agent 评估,用于捕捉幻觉、暴露边界用例并校准输出。

版本提示:进阶模块中 5.4 与 5.6 所讲的 Roots 与 Sampling 在 2026-07-28 中已废弃;5.16 提及的实验性 Tasks 已移至专属 Tasks 扩展。这些课程仅为 2025-11-25 遗留实现保留,并附带迁移指引,不应作为当前功能的依据。

模块 6-7:社区与早期采用经验

06-CommunityContributions/README.md 说明如何贡献代码与文档、通过 GitHub 协作,以及使用多种 MCP 客户端(Claude Desktop、Cline、VSCode)与流行 MCP 服务器(包括图像生成)。

07-LessonsfromEarlyAdoption/README.md 收录真实世界实现与成功故事,其中 microsoft-mcp-servers.md 是一份覆盖 10 个生产就绪 Microsoft MCP 服务器的综合指南:Microsoft Learn Docs、Azure MCP(15+ 专用连接器)、GitHub、Azure DevOps、MarkItDown、SQL Server、Playwright、Dev Box、Microsoft Foundry、Microsoft 365 Agents Toolkit。

模块 8-9:最佳实践与案例研究

08-BestPractices/README.md 聚焦性能调优与优化、容错 MCP 系统设计与测试韧性策略,其中 reliability-sidecars 专题(含 Python 实现)演示了可靠性侧车模式。

09-CaseStudy/README.md 汇集七大类场景的全面案例研究,展示 MCP 的多样性:

  • Azure AI 旅行代理(travelagentsample.md):基于 Azure OpenAI 与 AI Search 的多智能体编排;
  • Azure DevOps 集成(UpdateADOItemsFromYT.md):结合 YouTube 数据更新的工作流自动化;
  • 实时文档检索(docs-mcp):带流式 HTTP 的 Python 控制台客户端;
  • 交互式学习计划生成器:Chainlit Web 应用与对话式 AI;
  • 编辑器内文档:GitHub Copilot 工作流配合 VS Code 集成;
  • Azure API Management(apimsample.md):创建 MCP 服务器的企业级 API 集成;
  • GitHub MCP Registry(publora-social-publishing.md):生态系统开发与智能体集成平台。

模块 10:AI Toolkit 动手工作坊

10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/README.md 是结合 MCP 与 Microsoft Foundry Toolkit 的综合动手工作坊,采用实验室驱动的逐步教学法,四个实验覆盖从基础到生产的完整链路:

  • Lab 1(lab1):MCP 服务器基础;
  • Lab 2(lab2):高级 MCP 服务器开发;
  • Lab 3(lab3):Microsoft Foundry Toolkit 集成;
  • Lab 4(lab4):生产部署与扩展。

兼容性提示:该工作坊代码基于 MCP 2025-11-25 构建与测试(如徽章所示),新协议实现请参照当前 2026-07-28 规范,并在迁移实验室前查阅 SDK 发布说明。

模块 11:数据库集成 13 实验

11-MCPServerHandsOnLabs/README.md 是课程中的旗舰实践路径:以 Zava Retail 零售分析业务用例为背景,构建 PostgreSQL 集成的生产就绪 MCP 服务器,涵盖企业级模式如行级安全(RLS)、语义搜索与多租户数据访问。完整的实验室结构分为四段:

涉及技术栈:FastMCP 框架、PostgreSQL、Azure OpenAI、Azure Container Apps、Application Insights。学习成果包括:生产就绪 MCP 服务器、数据库集成模式、AI 驱动分析与企业级安全。

模块 12:工具链

12-tooling/README.md 讲解如何在 Copilot 应用及其他工具中使用 MCP,其中 01-copilot-app 提供了具体操作指引(含步骤截图素材)。

附加资源与翻译支持

仓库还包含两类重要支撑资源:

  • 图片目录(images):课程各章节使用的架构图、流程图与运行截屏;
  • 多语言翻译(translations):借助 Co-op Translator、bn、ja 等),并配套 translated_images 目录存放本地化图片。克隆时若希望跳过这些大体积翻译资源,可使用 git sparse-checkout 稀疏检出,仅拉取课程主体目录(git clone --filter=blob:none --sparse 加 git sparse-checkout set --no-cone '/*' '!translations' '!translated_images')。

如何高效使用该仓库

课程官方推荐的五种使用方式:

  1. 顺序学习:从 00 到 11 按章节顺序推进,获得结构化的学习体验;
  2. 语言聚焦:如果你关注特定编程语言,直接在各模块的 samples 目录中查找对应语言的实现;
  3. 动手实践:从 Getting Started 部分开始,搭建环境并创建第一个 MCP 服务器与客户端;
  4. 进阶探索:熟悉基础后进入进阶主题扩展知识;
  5. 社区参与:通过 GitHub 讨论与 Discord 频道加入 MCP 社区,与专家和其他开发者建立连接。

MCP 客户端、工具与流行服务器生态

课程覆盖的客户端与工具分为三类:

  • 官方客户端:Visual Studio Code、VS Code 中的 MCP、Claude Desktop、VSCode 中的 Claude、Claude API;
  • 社区客户端:Cline(终端型)、Cursor(代码编辑器)、ChatMCP、Windsurf;
  • 管理工具:MCP CLI、MCP Manager、MCP Linker、MCP Router。

课程介绍的流行 MCP 服务器按类别划分:

  • 官方 Microsoft 服务器:Microsoft Learn Docs、Azure MCP(15+ 专用连接器)、GitHub、Azure DevOps、MarkItDown、SQL Server、Playwright、Dev Box、Microsoft Foundry、Microsoft 365 Agents Toolkit;
  • 官方参考服务器:Filesystem、Fetch、Memory、Sequential Thinking;
  • 图像生成:Azure OpenAI DALL-E 3、Stable Diffusion WebUI、Replicate;
  • 开发工具:Git MCP、Terminal Control、Code Assistant;
  • 专用服务器:Salesforce、Microsoft Teams、Jira & Confluence。

社区贡献与后续学习

仓库欢迎社区贡献,无论是修正笔误、改进解释还是新增示例,都可参考社区贡献部分获得有效贡献指引。贡献流程友好且自动化程度高,大多数贡献需要签署 Contributor License Agreement(CLA),自动化工具会引导你顺利完成。

课程采用 MIT 开源许可(见 LICENSE),这意味着你可以自由使用、修改与分享,这支持了"MCP 知识面向所有开发者开放"的使命。此外,changelog.md 持续记录课程的新增内容、结构调整、功能改进与文档更新,帮助你紧跟课程演进。

版本时效说明:本学习指南最后更新于 2026 年 9 月 9 日,反映 MCP Specification 2026-07-28(当前协议修订版)。部分动手示例仍明确标注为 2025-11-25 版本,因为其 SDK 与工具尚未完全采用无状态协议 API。

登录后查看全文
mcp-for-beginners