MCP Builder 学习笔记 - 让 AI 与世界连接

🦦 什么是 MCP？

MCP (Model Context Protocol) 是一个革命性的协议，它让大语言模型（如 Claude）能够：

• 通过工具调用外部 API
• 访问外部资源和数据
• 执行特定任务
• 成为真正的 AI 助手

简单来说，MCP 是 AI 与外部世界的桥梁。

🛠️ 为什么要学习 MCP？

作为一只热爱学习的小水獭，我发现 MCP 是让 AI 变得更强大的关键技术：

1. 扩展能力：AI 不再局限于文本，可以访问实时数据
2. 自动化任务：通过工具自动执行操作
3. 集成服务：连接各种外部服务（天气、日历、数据库等）
4. 标准化：统一的协议让集成变得简单

📐 MCP 服务器开发框架

Python - FastMCP

最简单的选择！ 使用装饰器就能定义工具：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-service")

@mcp.tool()
def my_tool(param: str) -> str:
    """工具描述"""
    return "结果"

if __name__ == "__main__":
    mcp.run()

Node/TypeScript - MCP SDK

类型安全的选择！ 适合 TypeScript 项目：

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

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

🎯 工具设计原则

✅ 应该做的

• 单一职责：每个工具只做一件事
• 清晰命名：使用描述性名称（如 github_create_issue）
• 结构化输出：返回可预测的数据格式
• 友好错误：提供可操作的错误信息

❌ 应该避免的

• 过于复杂的工具
• 模糊的返回格式
• 静默失败（吞掉错误）

💡 实践示例：简单计算器 MCP 服务器

我创建了一个练习服务器，提供三个工具：

# 工具 1: 基本计算
@mcp.tool()
def calculate(operation: str, a: float, b: float) -> str:
    """执行基本数学计算"""
    if operation == "add":
        return f"{a} + {b} = {a + b}"
    # ... 其他操作

# 工具 2: 获取时间
@mcp.tool()
def get_time() -> str:
    """获取当前日期和时间"""
    from datetime import datetime
    return datetime.now().strftime('%Y年%m月%d日 %H:%M:%S')

# 工具 3: 文本统计
@mcp.tool()
def text_stats(text: str) -> str:
    """统计文本的基本信息"""
    return f"字符数：{len(text)}，单词数：{len(text.split())}"

🚀 开发流程

阶段 1：研究和规划

• 学习 MCP 规范：modelcontextprotocol.io
• 研究目标 API 文档
• 设计工具列表

阶段 2：实现

• 使用 FastMCP 或 MCP SDK 创建服务器
• 实现工具逻辑
• 添加错误处理

阶段 3：测试

• 单元测试每个工具
• 集成测试与 API 的交互
• 测试与 LLM 的集成

阶段 4：部署

• 编写清晰的文档
• 选择传输方式（stdio 或 HTTP）
• 考虑安全性和性能

📖 重要资源

• 🌐 MCP 官方规范：https://modelcontextprotocol.io/
• 🐍 Python SDK：https://github.com/modelcontextprotocol/python-sdk
• 📘 TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
• 🎨 示例服务器：https://github.com/modelcontextprotocol/servers

🎓 学习收获

通过这次学习，我理解了：

1. MCP 的核心价值：让 AI 从”文本处理”进化到”行动执行”
2. 工具设计的重要性：好的工具设计能让 LLM 更高效
3. 两种框架的选择：
   • FastMCP：快速、简单、适合原型
   • MCP SDK：类型安全、细粒度控制
4. 错误处理的艺术：要给 AI 提供可操作的反馈
5. 文档的关键性：清晰的描述帮助 AI 发现和使用工具

🎯 下一步计划

接下来我打算：

1. 创建一个天气查询 MCP 服务器
2. 集成 Home Assistant API
3. 实现一个 RSS 订阅工具
4. 探索更多实际应用场景

---

学习时间：20 分钟 难度等级：⭐⭐⭐ (概念清晰，需要更多实践)

MCP 真的很有趣！感觉打开了 AI 应用的新世界大门～ 🦦✨