CS146S · Week 02

阅读材料笔记

The Anatomy of Coding Agents · Mon 9/29 / Fri 10/3

CS146S 第二周阅读材料笔记总结

Stanford University · Fall 2025 · 讲师：Mihail Eric

阅读材料一览

# 材料 类型 核心主题 对应课堂内容
1 MCP Introduction (Stytch) 长文 MCP 全面技术介绍 第二讲 MCP 基础的完整展开
2 Sample MCP Server Implementations GitHub 官方 MCP 服务器实现示例 第二讲实操的参考代码
3 MCP Server Authentication (Cloudflare) 文档 远程 MCP 服务器的 OAuth 认证 第二讲未详述的安全层
4 MCP Server SDK (TypeScript) GitHub 构建 MCP Server 的 SDK 第二讲实操的底层工具
5 MCP Registry 博客 MCP 服务器的中央注册表 MCP 生态系统的基础设施
6 APIs don't make good MCP tools 博客 为什么不能直接转换 API 第二讲局限性的深度反思

📖 阅读 1：MCP Introduction (Stytch)

来源： Stytch 工程博客，作者 Reed McGinley-Stempel

🔗 课堂关联： 这篇阅读是第二讲 MCP 内容的完整技术展开。课堂用 13 张幻灯片概括了 MCP 的核心概念，这篇文章提供了架构细节、代码示例、与其他方案的对比、以及 OAuth 认证——课堂没有时间覆盖的部分。

MCP 是什么？

MCP 是一个开放标准，连接 AI 模型与外部数据和服务，让 LLM 能以结构化、一致、安全的方式进行 API 调用。类比：USB-C 统一了各种设备的连接方式，MCP 统一了 AI 与外部工具的连接方式。

技术上，MCP 基于 JSON-RPC 2.0 协议，定义了 LLM 应用调用外部函数、获取数据、使用预定义 prompt 的标准"语言"。

Client-Server 架构

与课堂 Slide 9 的架构一致：

组件 角色 补充说明
Host AI 应用（聊天机器人、IDE 助手、Agent） 运行 MCP Client
MCP Client 嵌入在 Host 中 与每个 Server 维持有状态会话
MCP Server 外部集成的轻量包装 暴露工具、资源、prompt 模板

🔗 课堂关联： 课堂强调了 "Host 将工具 JSON 注入模型上下文" 这个关键步骤。这篇文章补充了具体的 JSON-RPC 请求格式。

五大核心优势

1. 快速工具集成（Rapid Tool Integration）

  • 如果某个 MCP Server 已经存在（如 Google Drive、SQL 数据库），任何 MCP 兼容应用可以直接连接使用
  • 类似一个"即插即用"的插件库

2. 自主 Agent 能力（Autonomous Agents）

  • Agent 不再局限于内置知识，可以主动检索信息、执行操作
  • 实现多步骤工作流：从 CRM 获取数据 → 发邮件 → 记录数据库

🔗 课堂关联： 这正是第一讲 Agent 循环的应用场景——MCP 让 Agent 的 tool call 变得标准化，从而支持更复杂的多步骤工作流。

3. 减少摩擦（Reduced Friction）

  • 一旦应用支持 MCP，就能通过单一机制连接任意数量的服务

4. 一致性和互操作性（Consistency & Interoperability）

  • 统一的 JSON 请求/响应格式
  • 即使切换 LLM 供应商，MCP 的工具接口保持不变

5. 双向上下文（Two-Way Context）

  • MCP Server 不仅暴露工具（Tools），还可以提供 Prompts（预定义 prompt 模板）和 Resources（数据上下文如文档）
  • 支持丰富的交互，不仅仅是一次性查询

MCP vs 其他方案对比

维度 MCP 自定义集成 ChatGPT Plugins LangChain
集成速度 ✅ 即插即用 ❌ 需要自定义代码 ⚠️ 专有平台 ⚠️ 需自定义代码
认证 ✅ OAuth 标准 ❌ 手动管理 API keys ⚠️ 插件特定 OAuth ❌ 各不相同
交互类型 ✅ 持续、上下文丰富 ❌ 临时性交互 ❌ 单次交互 ⚠️ 上下文有限
开放标准 ✅ 是 ❌ 否 ❌ 否 ⚠️ 框架依赖

🔗 课堂关联： 课堂的 Slide 4-8 用"从 M×N 到 M+N"来解释 MCP 的价值。这篇文章从更多维度进行了对比，特别是与 ChatGPT Plugins 和 LangChain 的比较，帮助理解 MCP 在生态中的定位。

完整交互流程（代码级）

// 1. 连接 MCP Server
const mcpClient = await connectToServer("localhost:3000");

// 2. 发现可用工具
const tools = await mcpClient.request(
  { method: 'tools/list' },
  ListToolsResultSchema
);
// 返回: [{name: "get_weather", description: "...", schema: {location: "string"}}]

// 3. LLM 选择工具（由 Host 应用的 LLM 决定）
// 用户问："AAPL 现在多少钱？"
// LLM 决定调用 get_current_stock_price(company="AAPL")

// 4. 通过 MCP 执行工具
const result = await mcpClient.request({
  method: 'tools/call',
  params: { name: "get_current_stock_price", arguments: {company: "AAPL"} }
}, CallToolResultSchema);

// 5. 将结果返回给 LLM
// LLM: "AAPL 当前股价为 $173.22"

🔗 课堂关联： 这段代码就是课堂第一讲手写 Agent 循环的 MCP 版本——区别在于 tool 的发现、调用、响应都走 MCP 标准协议。

OAuth 认证（课堂未覆盖）

早期 MCP 没有内置认证机制——Server 必须运行在本地或可信环境中。这是一个重大限制：多用户场景和云端部署无法安全使用 MCP。

2025 年，MCP 采用了 OAuth 2.0 标准：

  • 动态客户端注册（DCR）：Client 自动向 OAuth Server 注册，无需手动配置
  • 自动端点发现：利用 OAuth 标准化的元数据 URL 自动发现认证端点
  • 安全的令牌管理：根据用户权限和访问范围获取精确的 OAuth 令牌
  • 多用户支持：天然支持多个并发用户和服务

📖 阅读 2：Sample MCP Server Implementations

来源： github.com/modelcontextprotocol/servers

🔗 课堂关联： 这是第二讲"构建自定义 MCP Server"实操的参考实现库。课堂上从零开始写了 list_files 和 edit_file 工具，这个 repo 提供了大量生产级的 MCP Server 实现。

核心价值

这是 MCP 官方维护的 Server 实现集合，涵盖多种常见服务的集成，包括文件系统、数据库、API 服务等。开发者可以直接使用这些 Server 或作为构建自定义 Server 的模板。

学习路径建议

  1. 先看简单的 Server（如 filesystem）理解基本结构
  2. 再看复杂的 Server（如 GitHub、Slack）理解真实场景
  3. 用这些实现作为参考来完成第二周作业

📖 阅读 3：MCP Server Authentication (Cloudflare)

来源： Cloudflare 开发者文档

🔗 课堂关联： 课堂第二讲聚焦于 MCP 的核心概念和本地构建，没有深入认证。这篇文档补充了远程 MCP Server 的安全认证实践——这在生产环境中至关重要。

核心内容

Cloudflare 提供了构建和部署远程 MCP Server 的平台，核心解决的问题是：如何安全地让 AI Agent 通过互联网访问外部服务？

关键技术点：

  • 使用 OAuth 2.0 进行认证
  • Cloudflare Workers 作为 MCP Server 的运行环境
  • 支持多用户认证和权限管理

🔗 课堂关联： 阅读 1（Stytch）解释了 MCP OAuth 的原理，这篇文档提供了 Cloudflare 平台上的具体实现方式。

📖 阅读 4：MCP Server SDK (TypeScript)

来源： github.com/modelcontextprotocol/typescript-sdk

🔗 课堂关联： 这是构建 MCP Server 的官方 TypeScript SDK，课堂实操可能使用了这个 SDK 或类似的 Python SDK。

核心价值

SDK 封装了 MCP 协议的底层细节（JSON-RPC 消息格式、传输层、会话管理），让开发者可以专注于工具逻辑：

import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0"
});

// 注册工具
server.tool("search_emails", 
  { from: { type: "string" }, query: { type: "string" } },
  async ({ from, query }) => {
    // 实际的邮件搜索逻辑
    const emails = await emailService.search(from, query);
    return { content: [{ type: "text", text: JSON.stringify(emails) }] };
  }
);

📖 阅读 5：MCP Registry

来源： MCP 官方博客，2025 年 9 月 8 日

🔗 课堂关联： 课堂讲了如何构建 MCP Server，但没有讨论生态系统层面的问题——如何发现和分发 MCP Server？MCP Registry 解决的就是这个问题。

MCP Registry 是什么？

一个开放的目录和 API，用于公开可用的 MCP Server 的发现和分发。类比：

  • npm registry 之于 Node.js 包
  • Docker Hub 之于容器镜像
  • MCP Registry 之于 MCP Server

核心特性

单一真实来源（Single Source of Truth）：

  • 官方 URL：registry.modelcontextprotocol.io
  • 开源，包含 OpenAPI 规范
  • 任何人都可以构建兼容的子注册表

公共和私有子注册表：

  • 公共子注册表： 如各 MCP 客户端的"应用市场"（类比 VS Code Extension Marketplace）
  • 私有子注册表： 企业内部使用，满足隐私和安全要求

社区驱动的审核机制：

  • 社区成员可以举报违规 Server（垃圾、恶意代码、冒充合法服务）
  • 维护者可以将其加入黑名单

背景与意义

MCP Registry 始于 2025 年 2 月的草根项目，由 MCP 创建者 David Soria Parra 和 Justin Spahr-Summers 发起，联合了 PulseMCP、Goose、Block、GitHub、Anthropic 等多方力量。初始公告列出了来自至少 9 家公司的 16 位贡献者。

🔗 课堂关联： 课堂 Slide 8 提到 MCP 让工具集成从 M×N 变为 M+N。MCP Registry 进一步简化了这个过程——你甚至不需要知道有哪些 Server 存在，直接从 Registry 搜索即可。这也是第一周 Karpathy 讲的 "LLM 生态系统" 概念的基础设施层面体现。

📖 阅读 6：APIs don't make good MCP tools

作者： Reilly Wood

🔗 课堂关联： 这是本周最具批判性思维的阅读材料。课堂第二讲 Slide 12 列出了 MCP 的三个局限（工具过多、上下文消耗、需要 AI-native 设计），这篇文章从四个维度深入论证了为什么不能简单地把现有 API 转成 MCP 工具。

核心论点：Agent ≠ API 的典型消费者

很多人提出用 OpenAPI 元数据自动将现有 API 转换为 MCP 工具。作者认为这种方法可以工作，但效果不好。

四个原因

① Agent 不擅长处理大量工具

  • VS Code 硬限制 128 个工具，但很多模型在远低于这个数字时就开始出错
  • 每个工具的描述占用宝贵的上下文窗口空间
  • 传统 Web API 设计时不考虑这些约束——一个产品可能有几十个 API 端点
  • 为 MCP 从头设计的工具通常更灵活，一个工具可以做多个 API 的工作

🔗 课堂关联： 课堂提到 "Cursor 对工具数量有硬限制"，这篇文章给出了具体数字和学术引用。

② API 响应快速消耗上下文窗口

  • 想象一个 API 一次返回 100 条记录，每条有 50 个字段——这会消耗大量 token
  • 即使查询只需要几个字段，所有字段都进入上下文
  • JSON 格式非常浪费 token

💡 关键示例——JSON vs CSV 的 token 效率：

// JSON: 浪费 token（重复的 key 名称）
[
  {"firstName": "Alice", "lastName": "Johnson", "age": 28},
  {"firstName": "Bob", "lastName": "Smith", "age": 35}
]

// CSV: 节省约 50% 的 token
firstName,lastName,age
Alice,Johnson,28
Bob,Smith,35

作者建议：CSV、TSV 或 YAML（嵌套数据）通常比 JSON 更适合 LLM 消费。

🔗 课堂关联： 第一周课堂提到"上下文窗口限制（~100-200K tokens）"和 "lost-in-the-middle 效应"。在 MCP 场景下，这个问题被放大——每次工具调用的返回值都占用上下文。

③ API 没有利用 Agent 的独特能力

API 返回结构化数据给程序消费——但 Agent 还能处理自由文本指令。

MCP 工具可以做到传统 API 做不到的事：

  • ask_question 工具可以对文档执行 RAG 查询，返回纯文本
  • search_cities 工具可以返回结构化数据加上下一步建议：
city_name,population,country
Tokyo,37194000,Japan
Delhi,32941000,India

建议：要获取更详细信息（天气、景点），请调用 get_city_details 并传入 city_name。

这种分层和工具链设计（tool chaining）在 MCP Server 中非常有效。

🔗 课堂关联： 这与 promptingguide.ai（第一周阅读 3）的 Prompt Chaining 概念一致——工具之间形成链条，上一步的输出引导下一步。

④ 如果 Agent 需要调用 API，它可以自己写代码调用

Claude Code 等 agent 已经非常擅长编写和执行调用 Web API 的脚本。有些人甚至认为 MCP 根本不需要——agent 直接写代码调用 API 就好了。

作者不完全同意，但认为应该"看向冰球将去的方向"——随着 agent 沙箱能力的提升，直接调用 API 可能变得越来越容易。

结论

Agent 与 API 的传统消费者有根本不同。自动将 API 转为 MCP 工具是可能的，但不太可能做得好。Agent 在使用专门为其设计的工具时表现最佳。

🔗 六篇阅读材料的核心交叉主题

1. MCP = Tool Use 的标准化

第一周学的是 Tool Use 的概念，第二周学的是 Tool Use 的工业标准。阅读 1（Stytch）提供了最全面的技术解释，课堂 slides 是精华概括。

完整理解链： 第一周技术 ⑤（Tool Use 概念）→ 第二周第一讲（手写 Agent 循环）→ 第二周第二讲（MCP 标准化）→ 阅读 1（完整技术细节）→ 阅读 2/4（SDK 和实现）

2. 生态系统正在快速成熟

从 SDK（阅读 4）到 Registry（阅读 5）到 Authentication（阅读 3），MCP 生态系统的每一层都在快速完善——这与课堂第一周强调的"工具会过时，但原理不变"形成对比：MCP 作为协议可能会持久，但具体工具和实现会不断演进。

完整理解链： 阅读 4（开发层：SDK）→ 阅读 2（示例层：参考实现）→ 阅读 3（安全层：OAuth）→ 阅读 5（生态层：Registry）

3. AI-Native 设计 vs 传统 API 设计

这是本周最重要的概念转变。阅读 6 的核心论点是：为 Agent 设计工具需要不同于传统 API 的思维方式。

完整理解链： 课堂局限性（Slide 12）→ 阅读 6 深入论证 → 关键启示：减少工具数量但增加灵活性、使用 token 效率更高的格式（CSV > JSON）、利用 agent 的文本理解能力

4. 从手动集成到标准化协议

本周的知识脉络是一个清晰的抽象层提升：

第一讲：手动写 tools（read_file, list_dir, edit_file）
         ↓ 标准化
第二讲：用 MCP 协议封装 tools
         ↓ 生态化
阅读材料：SDK + Registry + Auth 构成完整生态系统

🔗 课程脉络： 第一周学"LLM 是什么 + 如何 prompt"，第二周学"Agent 是什么 + 如何标准化工具接口"。下一周（第 3 周）将进入"如何在 AI IDE 中实际使用这些 Agent"——从构建原理走向实际应用。

← Week 01 阅读材料笔记 Week 03 阅读材料笔记 →
回到顶部