mcp-for-beginners 学习指南:MCP 课程体系、仓库导航与实践路线图
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-best-practices.md(MCP 安全最佳实践)
- azure-content-safety-implementation.md(Azure 内容安全实现指南)
- mcp-security-controls.md(MCP 安全控制与策略)
- mcp-best-practices.md(MCP 最佳实践速查)
安全章节还推荐了 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)、语义搜索与多租户数据访问。完整的实验室结构分为四段:
- Lab 00-03:基础——介绍、架构、安全、环境设置;
- Lab 04-06:构建 MCP 服务器——数据库设计、MCP 服务器实现、工具开发;
- Lab 07-09:高级特性——语义搜索(Azure OpenAI + pgvector 向量嵌入)、测试与调试、VS Code 集成;
- Lab 10-12:生产与最佳实践——部署(Docker、Azure Container Apps)、监控(Application Insights)、最佳实践(性能优化、安全加固)。
涉及技术栈: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')。
如何高效使用该仓库
课程官方推荐的五种使用方式:
- 顺序学习:从 00 到 11 按章节顺序推进,获得结构化的学习体验;
- 语言聚焦:如果你关注特定编程语言,直接在各模块的
samples目录中查找对应语言的实现; - 动手实践:从 Getting Started 部分开始,搭建环境并创建第一个 MCP 服务器与客户端;
- 进阶探索:熟悉基础后进入进阶主题扩展知识;
- 社区参与:通过 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。