分类： AI学习

基于 modelcontextprotocol/python-sdk v2 源码分析，协议版本 2026-07-28

概述

MCP Python SDK 是 Model Context Protocol 的官方 Python 实现，当前为 v2 版本——一次重大的架构重写，既支持 2026-07-28 规范及所有早期版本，也修复了长期存在的架构问题。SDK 同时提供 Server 和 Client 两套完整能力，支持 stdio、Streamable HTTP、SSE 三种标准传输方式。

1. 分层架构：四层分离

SDK 采用清晰的四层分层设计，每层职责明确、边界严格：

┌─────────────────────────────────────────┐
│  FastMCP 层 (MCPServer)                 │  装饰器 API，开发者面向
├─────────────────────────────────────────┤
│  Lowlevel Server 层 (Server)            │  构造函数 handler 注册
├─────────────────────────────────────────┤
│  Dispatcher 层 (JSONRPCDispatcher)      │  请求-响应关联、并发调度
├─────────────────────────────────────────┤
│  Transport 层 (stdio / StreamableHTTP)  │  字节流 ↔ 消息流
└─────────────────────────────────────────┘

FastMCP 层（MCPServer）提供最高级抽象——@mcp.tool()、@mcp.resource()、@mcp.prompt() 装饰器，开发者只需写带类型注解的 Python 函数，SDK 自动推导 JSON Schema、处理参数校验和协议交互。15 行代码即可构建完整 MCP Server。

（更多…）

前面48篇，你把数据装进过变量、装进过文件、装进过CSV和Excel。今天开门迎接编程路上第三个新台阶——数据库。这一篇不急着写SQL，先把一个根本问题掰开揉碎：CSV用得好好的，为什么全世界的软件都在用数据库？想通了这个问题，后面11篇学起来才不迷路。

一、真实场景：一个被自己数据”噎住”的价格监控

接着第48篇的故事讲。你的价格监控工具勤勤恳恳跑了一个月，price_history.csv 从2行长到了2000多行，每天30分钟一轮，机械键盘和无线鼠标的价格历史一条不落。你很满意——直到某天你想问它几个问题：

1. “上周三到今天，机械键盘降了几次？”
2. “现在把无线鼠标的目标价从90改成120，顺便告诉我：按新目标价，历史里有几天是’该提醒我’的？”
3. “把两个商品按’每降价10元记一次’重新统计一份月报。”

用CSV做这三件事，你得：把2000行全部读进内存、写循环逐行比对字符串时间、自己处理”价格是字符串”的老坑（第48篇坑2）、按条件重新拼一份文件……三个问题写三段几乎重复的代码。更要命的是第四件事——

1. 你手滑用Excel打开了 price_history.csv，随手删了两行”看起来重复”的记录，保存。第二天监控工具追加新数据时，文件里混进了两种格式的行尾，csv.DictReader 直接读乱了。

这就是CSV的天花板：它只负责”存”，不负责”管”。数据一多、问题一复杂、或者多一只手来碰它，纯文件就开始散架。是时候请专业选手出场了。

（更多…）

项目: google/adk-python

版本: ADK 2.0 (2026)

许可证: Apache 2.0

语言: Python 3.10+

一、项目概述与设计哲学

Google Agent Development Kit (ADK) 是 Google 开源的、代码优先 (code-first) 的 AI Agent 开发框架，旨在将软件工程原则系统性地引入 AI Agent 构建流程。ADK 2.0 是一次重大架构升级，引入了图执行引擎 (Workflow Runtime)、Task API、Agent Config 等全新概念，从一个”Agent 脚手架”演进为一个完整的 Agent 操作系统。

ADK 的核心设计哲学是 “软件工程原则应用于 Agent”：模块化、可测试、可版本化、可部署。它不是简单的 LLM 包装器，而是一个涵盖 Agent 定义、工具管理、会话状态、记忆系统、制品存储、工作流编排、评估和部署的全栈框架。

二、整体架构拓扑

ADK 源码位于 src/google/adk/，包含 30 个子模块，架构层次清晰：

（更多…）

阶段4的收官之战来了。这一篇不学新概念——因为你要用的每一样手艺都学过了：requests 抓网页（第37篇）、BeautifulSoup 抠数据（第41~42篇）、robots.txt + 限速讲礼貌（第47篇）、CSV 存历史（第25篇）、API 发通知（第38篇）。今天干一件更大的事：把散装手艺攒成一台会转的机器——一个真的、每天能替你干活的价格监控工具：定时去商城看一眼价格，历史记录存进 CSV，一旦跌破你心里的目标价，第一时间提醒你。做完这篇，”从网上拿数据”这件事你就正式出师了。

一、真实场景：你和”降价”之间差一个机器人

双十一前你看中一把机械键盘，标价 239 元，你猜它会降到 180 以下，于是每天早晚各刷一次商品页。刷到第五天忘了，第六天想起来一看——179 元，但活动已经结束，涨回去了。你气得拍大腿：我不是在等降价，我是在跟降价赌眼力。

其实这种活儿根本不该人干。人刷价格有两个致命弱点：一是记不住（昨天到底多少钱来着？），二是熬不起（总不能半夜三点定闹钟看一眼）。而这两件事恰恰是程序的强项：它记性好（历史全存着）、不用睡觉（定时自己跑）、还特别听话（说盯几个就盯几个）。

所以今天把价格监控拆成一条流水线，六道工序，每道都是学过的东西：

（更多…）

项目: VRSEN/agency-swarm

定位: 基于 OpenAI Agents SDK 的多智能体编排框架

许可证: MIT

版本: v1.x（完全重写，基于 OpenAI Agents SDK）

语言: Python 3.12+

一、核心设计理念

Agency Swarm 的设计哲学源于一个直觉类比：将 AI 多智能体系统映射为现实世界的组织架构。框架的创始人 Arsenii Shatokhin（VRSEN）提出，通过”公司组织结构”的隐喻来构建 AI 代理机构，使代理之间的协作关系对开发者和用户都更加直观。

这一理念体现在三个核心原则上：

1. 角色专业化：每个 Agent 拥有明确的职责描述（如 CEO、Developer、Virtual Assistant），就像公司中的岗位分工
2. 层级化通信：Agent 之间的通信路径通过显式的 communication_flows 定义，模拟组织中的汇报关系
3. 自主性与可控性平衡：Agent 在护栏（guardrails）内自主决策，同时人类可以通过入口 Agent 直接干预

v1.x 版本是基于 OpenAI Agents SDK 的完全重写，从 v0.x 的 Assistants API 黑盒模式转向了更透明、更可控的架构。

（更多…）

前面十篇练的全是”怎么从网上拿东西”：抓网页、抠表格、提交表单、带登录拿、批量下载。但有一句老话得在第47篇正式讲：程序能干，不等于可以随便干。今天新概念只有一个：robots.txt——网站贴在大门口的”欢迎参观 / 后院别进”告示牌，程序进门之前先看一眼。再配一个老手艺的新用法：time.sleep 限速，让程序做个”走马观花的体面访客”，而不是”把人家门槛踏破的暴走团”。学完这篇，你的爬虫才算毕业：不光会拿，还知道什么能拿、拿多快、拿多少。

一、真实场景：一封”友好”的律师函

你把第43篇的爬虫升级了一下：盯上了一个行业资讯网站，每小时跑一次，把所有新文章扒下来存进自己的资料库。头两天美滋滋——数据哗哗地来。第三天早上，程序报错了：Connection refused。浏览器一打开，人家网站正常得很，就你的程序被拒之门外——你的 IP 被封了。

你心想：封就封，我换个网络接着爬。于是改成每 10 秒狂抓一次，一晚上抓了人家三万页。第四天，收到的不是新数据，是网站管理员的一封邮件，措辞客气但意思很硬：”贵方的自动化访问已对我方服务器造成明显负载，请立即停止，否则我方将保留进一步追究的权利。”

你懵了：网上公开的东西，我”看”一下怎么还犯法了？

（更多…）

前面四十多篇拿到的都是文字——网页内容、表格数据、JSON。但网上更多好东西是文件：PDF 通知、Excel 模板、图片素材、安装包。今天新概念只有一个：二进制文件写入——resp.content 拿到的不再是”字”，而是”原样的字节”，得用 open(path, "wb") 原封不动写进硬盘。学完这篇，”右键→另存为→等→再右键→再另存为”的体力活就彻底交给程序了：它半夜能把 30 份 PDF 整整齐齐搬进你的文件夹。

一、真实场景：月底的”资料搬运工”

单位的”资料下载”栏每月更新一批文件：本月的工作简报 PDF（12 期，编号 01 到 12）、报销模板 Excel、还有几张通知截图。领导让你”把这些都下下来，归到 D:月度资料10月 里”。

这事没有任何技术含量：点开链接 → 右键 → 另存为 → 选文件夹 → 改文件名 → 重复 15 遍。难就难在烦：每次都要选路径、等进度条、文件名还容易存错（简报(1).pdf、简报(2).pdf 这种鬼东西就是这么来的）。而且这种活每月一次，下个月还得再来一遍。

更别提另一种情况：批量。比如教研组要下载 200 份学生交的电子作业（每份一个 PDF 链接，都在一个页面上排着），手工点 200 次另存为？点到手抽筋。

（更多…）

项目: instructor-ai/instructor (567-labs/instructor)

定位: 为 LLM 提供结构化输出的 Python 库，基于 Pydantic 实现类型安全的 JSON 提取

版本: v1.17.1 | Stars: 13,000+ | 语言: Python 100% | 许可证: MIT

主页: https://python.useinstructor.com/

1. 项目定位与核心价值

Instructor 解决的是一个极其具体的问题：从 LLM 的非结构化文本输出中可靠地提取结构化数据。传统方式需要手动编写 JSON Schema、处理验证错误、实现重试逻辑、解析不同提供商的 API 差异——Instructor 将这一切封装为一个极简接口：

client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
    response_model=User,  # Pydantic 模型即 Schema
    messages=[{"role": "user", "content": "John is 25 years old"}],
)
# 直接得到 User(name='John', age=25)

核心理念是 Schema-First：开发者只需定义 Pydantic BaseModel，Instructor 自动完成 JSON Schema 生成、API 适配、响应解析、验证重试的全链路。与 PydanticAI（Pydantic 官方的 Agent 运行时）形成互补——Instructor 聚焦于快速提取场景，PydanticAI 面向更复杂的 Agent 编排。

2. 整体架构：v1/v2 双层结构

Instructor 的代码库经历了从 v1 到 v2 的重大重构，当前采用 兼容层 + 核心层 的双层架构：

（更多…）

上一篇的表单提交已经能”递单子办事”了，但很多网站更狠：单子都不让你递——先登录，才有资格查。账号密码递进去不难，难的是网站认完人发你一张”工牌”（Cookie），之后每次进门都得出示它。今天新概念只有一个：requests.Session——一个自动保管工牌、进门自动出示的请求会话。学完这篇，需要登录的查询也能自动化：登录一次，工位一坐，把该查的都查完。

一、真实场景：每季度一次的”学时查询”折腾

你所在单位有个”继续教育平台”，每季度要查一次自己的培训学时：登录（用户名+密码）→ 点”我的学时” → 看着页面上的数字抄下来 → 填进单位的汇总表。你一个人查一次也就两分钟，但你们科室 15 个人，每到季度末都来问你：”帮我看看我学时够不够？”——账号密码一个个发过来，你一个个登录、一个个查、一个个回复，一上午就没了。

更气人的是：这平台的”我的学时”页面不登录根本打不开——直接访问网址，它把你踢回登录页。上一篇学的 requests.post 在这里只能递登录表单，递完之后呢？程序换下一个网址去查学时，服务器冷冰冰地回一句：”请先登录。”

问题出在哪？上一篇的程序是”一次性”的：每次请求都是陌生人上门，递完单子扭头就忘。 而真实世界的规矩是：你登录时，前台认出你，发你一张工牌；之后你去每个窗口办事，都得把工牌亮一下，工作人员一看：”哦，是三楼的老王，进来吧。”

（更多…）

项目: langfuse/langfuse

定位: 开源 LLM 工程平台（可观测性、评估、Prompt 管理、数据集）

技术栈: Next.js + tRPC + Prisma + ClickHouse + Redis (BullMQ) + TypeScript

许可证: MIT（ee/ 目录为企业版，限制性许可）

背景: YC W23，2026年1月被 ClickHouse 收购

1. 系统总体架构

Langfuse 采用经典的 Web + Worker 双进程 架构，辅以 ClickHouse 做分析型存储、PostgreSQL 做事务型存储、Redis/BullMQ 做任务队列。

┌─────────────────────────────────────────────────────┐
│                   SDK (Python/JS)                    │
│  @observe() / OpenAI wrapper / LangChain callback   │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP / OTLP
                       ▼
┌──────────────────────────────────────────────────────┐
│              Web Server (Next.js App)                 │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │  tRPC    │  │ REST API │  │ Next.js Pages/App │  │
│  │ (internal)│  │ (public) │  │   (React UI)      │  │
│  └────┬─────┘  └────┬─────┘  └───────────────────┘  │
│       │              │                                │
│       ▼              ▼                                │
│  ┌─────────────────────────┐  ┌──────────────────┐  │
│  │    Prisma ORM (PG)      │  │  ClickHouse Client│  │
│  │  users/orgs/projects    │  │  traces/obs/scores│  │
│  │  prompts/datasets/config│  │  (analytics OLAP) │  │
│  └─────────────────────────┘  └──────────────────┘  │
└──────────────────────┬───────────────────────────────┘
                       │ BullMQ Jobs
                       ▼
┌──────────────────────────────────────────────────────┐
│              Worker (独立 Node.js 进程)                │
│  ┌─────────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ Ingestion   │ │ Eval     │ │ Batch Export     │  │
│  │ Queue       │ │ Queue    │ │ Queue            │  │
│  ├─────────────┤ ├──────────┤ ├──────────────────┤  │
│  │ Experiment  │ │ Monitor  │ │ Data Retention   │  │
│  │ Queue       │ │ Queue    │ │ Queue (EE)       │  │
│  ├─────────────┤ ├──────────┤ ├──────────────────┤  │
│  │ OTel        │ │ Webhook  │ │ In-App Agent     │  │
│  │ Ingestion   │ │ Queue    │ │ Run Queue        │  │
│  └─────────────┘ └──────────┘ └──────────────────┘  │
└──────────────────────────────────────────────────────┘

核心设计原则：写入路径（ingestion）通过队列异步化，读取路径走 ClickHouse OLAP 查询，事务型数据（用户、项目、Prompt 配置）走 PostgreSQL + Prisma。

2. Monorepo 结构与模块划分

Langfuse 使用 pnpm workspace + Turborepo 管理 monorepo：

（更多…）