Exercise 2: 写你的第一个 MCP Server

练习目标

构建一个实用的 MCP Server，让 Claude 能与你工作中使用的某个系统交互。

选择你的场景

从以下场景中选一个（或自定义）：

场景 A: 笔记搜索 Server

让 Claude 能搜索和读取你的笔记（本地 Markdown 文件）。

Tools:

search_notes: 按关键词搜索笔记
read_note: 读取指定笔记内容
list_recent: 列出最近修改的笔记

场景 B: 日程管理 Server

让 Claude 能查询和创建日程。

Tools:

list_events: 查询某天的日程
create_event: 创建新日程
check_availability: 检查某时段是否有空

场景 C: 任务管理 Server

让 Claude 能管理你的 TODO 列表。

Tools:

list_tasks: 列出所有任务（支持按状态筛选）
add_task: 添加新任务
complete_task: 标记任务完成
get_summary: 获取任务统计摘要

实施步骤

Step 1: 项目搭建（10 分钟）

mkdir my-mcp-server && cd my-mcp-server
bun init
bun add @modelcontextprotocol/sdk zod

Step 2: 定义 Tools（15 分钟）

为你选择的场景定义 2-3 个 Tools。注意：

名称要清晰（动词_名词格式）
描述要让 AI 理解什么时候用
参数要用 Zod 严格验证

Step 3: 实现逻辑（30 分钟）

实现每个 Tool 的业务逻辑。可以用本地文件系统作为存储。

Step 4: 测试（15 分钟）

用 MCP Inspector 测试每个 Tool
配置到 Claude Desktop
用自然语言触发工具调用

Step 5: 错误处理（10 分钟）

确保每个 Tool 都有合理的错误处理：

文件不存在
参数无效
外部 API 超时

评分标准

Tool 定义质量（描述清晰、参数验证严格）: 30%
功能实现完整性（能正确执行操作）: 30%
错误处理（优雅处理各种异常）: 20%
代码质量（TypeScript 类型安全、代码整洁）: 20%

加分项

添加 Resource（暴露可读数据源）
添加 Prompt（预定义交互模板）
写单元测试
处理并发调用