AI导哈

AI工具交互协议教程

Model Context Protocol (MCP) 是一个标准化协议，使AI助手能够与外部工具和数据源进行交互。本教程通过实践学习MCP的基本概念、架构和实现方法。

  • by MasaoAsano
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 MasaoAsano/mcp-handson

使用说明

MCP 入门教材

概要

在本教材中模型上下文协议（MCP） 一边实际动手一边学习。MCP单击功能区上AI一种协议，允许助手以标准化的方式与外部工具和数据源交互。

学习目标

通过此项技能，您可以学到以下技能：

  • 传统REST API和MCP感受
  • MCP基本概念和体系结构的理解
  • MCP如何实施服务器
  • MCP如何连接客户端
  • 实现资源、工具和提示
  • 实践性的MCP应用程序开发

前提知识

  • JavaScript/TypeScript 基本知识
  • Node.js 基本的使用方法
  • 命令行 基本操作
  • JSON 基本的理解

MCP的基本组成部分：

  • 服务器：提供功能的一方
  • 客户端：使用功能的一侧
  • 资源：只读数据
  • 工具：可执行的操作
  • 提示: LLM的模板

环境设置

所需工具

# Node.js (v18以上推奨)
node --version

# npmの確認
npm --version

项目设置

# リポジトリをクローン
git clone https://github.com/MasaoAsano/mcp-handson.git
cd mcp-handson

# 依存パッケージをインストール
npm install

准备完毕！

快速启动

# 第1章: 従来のAPIとMCPを比較してみる
npm run ch01:mcp

# 第2章: Hello Worldサーバーを起動
npm run ch02:hello

# 第6章: タスク管理システムを使ってみる
npm run ch06:client

汉斯通配置

第1章：以往API和MCP比较⭐

所要时间：30分

同样的任务管理功能REST API和MCP中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

学習内容:

  • REST API的实施（Express.js）
  • MCP同等实施
  • 两者设计思想的差异
  • MCPの利点（自己记述性、AI统合）

包含的文件：

  • traditional-api/server.ts - REST API服务器
  • traditional-api/client.ts - fetch使用的客户机
  • mcp-approach/server.ts - MCP服务器
  • mcp-approach/client.ts - MCP客户机
  • comparison.md -详细比较文档

実行方法:

npm run ch01:traditional  # REST API版
npm run ch01:mcp          # MCP版

第2章：最初的MCP服务器

所要时间：40分

MCP了解服务器的基本结构，学习如何提供资源。

2.1 Hello World服务器

最简单的MCP创建服务器。

示例： samples/01-hello-server.ts

  • 服务器基本结构
  • 提供单个资源
  • 设置请求处理程序

演习1: 创建要返回其名称的服务器

  • exercises/exercise-01.md -练习指南
  • exercises/exercise-01-template.ts -模板

2.2提供多个资源

动态URI和多个资源的处理方法。

示例： samples/02-server-with-resources.ts

  • 定义多个资源
  • 动态URI（示例： books://item/{id}）
  • 模式匹配

演习2: 制作喜欢的电影/动画的目录服务器

  • exercises/exercise-02.md -练习指南
  • exercises/exercise-02-template.ts -模板

実行方法:

npm run ch02:hello      # Hello Worldサーバー
npm run ch02:resources  # 書籍ライブラリサーバー

第3章：实现工具

所要时间：50分

学习如何实现更改状态的操作（工具）。

3.1基本工具

示例： samples/calculator-tool.ts

  • 四则运算工具（add，subtract，multiply，divide）
  • 定义输入架构
  • 验证参数
  • 错误处理

3.2多工具集成

示例： samples/weather-tool.ts 和 samples/server-with-tools.ts

  • 天气信息获取工具（莫克数据）
  • 多工具集成服务器
  • 工具间协作

演习： 创建字符串操作工具

  • exercises/exercise-01.md -练习指南
  • exercises/exercise-01-template.ts -模板
  • uppercase, lowercase, reverse 三个工具

実行方法:

npm run ch03:calculator  # 統合ツールサーバー

第4章：实现提示

所要时间：35分

LLM中所述修改相应参数的值。

4.1动态提示

示例： samples/prompt-templates.ts

  • 邮件创建提示（tone，recipient，subject对应）
  • 代码审阅提示（language，focus支持）
  • 文章摘要提示（length对应）
  • 使用参数动态生成

4.2集成资源工具提示

示例： samples/server-with-prompts.ts

  • 具有所有功能的服务器
  • 统一使用示例

実行方法:

npm run ch04:prompts  # プロンプトサーバー

第5章：客户端实现

所要时间：40分

MCP实现与服务器通信的客户端。

5.1基本客户端

示例： samples/basic-client.ts

  • 客户端初始化
  • 连接到服务器
  • 调用工具
  • 读取资源

5.2高级客户端

示例： samples/client-with-tools.ts

  • 批处理
  • 错误处理
  • 连续执行多个操作

実行方法:

npm run ch05:client  # クライアントデモ

第6章：实践项目-任务管理系统🎯

所要时间：90分

构建一个实用的任务管理系统，它集成了您之前学到的所有元素。

系统配置：

数据层： samples/task-manager/types.ts + storage.ts

  • Task定义类型
  • JSON基于文件的存储
  • CRUD操作
  • 検索机能

服务器层： samples/task-manager/server.ts

资源：

  • tasks://all -列出所有任务
  • tasks://summary -统计情报
  • tasks://item/{id} -个别任务

工具：

  • create_task -创建任务
  • update_task -任务更新
  • delete_task -删除任务
  • search_tasks - 検索

提示：

  • create_task_prompt -任务创建帮助
  • weekly_report -生成每周报告

客户端： samples/task-manager/client.ts

  • 演示客户机
  • 所有功能的使用示例

机能：

  • ✅ 创建、更新和删除任务
  • ✅ 状态管理
  • ✅ 优先度设定（low，medium，high）
  • ✅ 标记功能
  • ✅ 搜索和过滤
  • ✅ 查看统计信息

実行方法:

npm run ch06:server  # サーバー起動
npm run ch06:client  # クライアントデモ

第7章：测试和调试

所要时间：30分

MCP学习应用程序测试和调试方法。

7.1单元测试

示例： samples/tools.test.ts

  • Jest使用测试
  • 工具测试示例
  • 考试的写法

実行方法:

npm test  # テスト実行

7.2调试最佳实践

  • console.error使用的日志输出
  • 设计错误消息
  • 故障排除

发展挑战（如果有时间）：

  • 安全性：输入验证增强
  • 性能：缓存策略
  • Claude Desktop与集成

目录配置

mcp-handson/
├── readme.md                                  # このファイル
├── package.json                               # プロジェクト設定
├── tsconfig.json                              # TypeScript設定
├── jest.config.js                             # Jestテスト設定
├── .gitignore
│
├── chapter-01/                                # 第1章: API比較
│   ├── traditional-api/
│   │   ├── server.ts                      # REST APIサーバー
│   │   └── client.ts                      # REST APIクライアント
│   ├── mcp-approach/
│   │   ├── server.ts                      # MCPサーバー
│   │   └── client.ts                      # MCPクライアント
│   └── comparison.md                      # 比較ドキュメント
│
├── chapter-02/                                # 第2章: 最初のサーバー
│   ├── samples/
│   │   ├── 01-hello-server.ts             # Hello World
│   │   └── 02-server-with-resources.ts    # リソース付き
│   └── exercises/
│       ├── exercise-01.md                 # 演習ガイド
│       ├── exercise-01-template.ts        # テンプレート
│       ├── exercise-02.md
│       └── exercise-02-template.ts
│
├── chapter-03/                                # 第3章: ツール
│   ├── samples/
│   │   ├── calculator-tool.ts             # 計算機
│   │   ├── weather-tool.ts                # 天気情報
│   │   └── server-with-tools.ts           # 統合サーバー
│   └── exercises/
│       ├── exercise-01.md                 # 文字列操作演習
│       └── exercise-01-template.ts
│
├── chapter-04/                                # 第4章: プロンプト
│   └── samples/
│       ├── prompt-templates.ts            # テンプレート集
│       └── server-with-prompts.ts         # 統合サーバー
│
├── chapter-05/                                # 第5章: クライアント
│   └── samples/
│       ├── basic-client.ts                # 基本クライアント
│       └── client-with-tools.ts           # 高度な使用例
│
├── chapter-06/                                # 第6章: 実践プロジェクト
│   └── samples/
│       └── task-manager/
│           ├── types.ts                   # 型定義
│           ├── storage.ts                 # データ永続化
│           ├── server.ts                  # タスク管理サーバー
│           └── client.ts                  # クライアント
│
└── chapter-07/                                # 第7章: テスト
    └── samples/
        └── tools.test.ts                      # テスト例

各章的执行命令

# 第1章: API比較
npm run ch01:traditional    # 従来のREST API
npm run ch01:mcp            # MCPアプローチ

# 第2章: 最初のサーバー
npm run ch02:hello          # Hello Worldサーバー
npm run ch02:resources      # リソース付きサーバー

# 第3章: ツール
npm run ch03:calculator     # 計算機 & 天気ツール

# 第4章: プロンプト
npm run ch04:prompts        # プロンプトテンプレート

# 第5章: クライアント
npm run ch05:client         # MCPクライアントデモ

# 第6章: 実践プロジェクト
npm run ch06:server         # タスク管理サーバー
npm run ch06:client         # タスク管理クライアント

# 第7章: テスト
npm test                    # 全テスト実行

学习方法

建议的学习路径

  1. 第1章 - MCP体验的不同（30分钟）
  2. 第2章 -了解服务器基础知识（40分钟）
  3. 第3章 -学习工具实施（50分钟）
  4. 第4章 -了解提示（35分钟）
  5. 第5章 -创建客户端（40分钟）
  6. 第6章 -挑战实践项目（90分钟）
  7. 第7章 -测试和调试（30分钟）

合计所要时间：约5时间15分

学习的诀窍

✅ 必须运行示例：不仅仅是阅读，试着实际移动一下吧 ✅ 致力于演习：通过移动手来加深理解 ✅ 分阶段进行：不要着急，每一章都要切实理解 ✅ 不怕出错：错误是学习的机会

参考资源

正式文档

示例代码

社区

故障排除

常见问题及解决办法

1.软件包安装错误

npm install @modelcontextprotocol/sdk
npm install -D @types/node typescript

2.服务器未启动

  • Node.js 查看版本（建议使用v18或更高版本）
  • node --version

3. TypeScript错误

npx tsc --noEmit  # 型チェックのみ実行

4.客户端无法连接

  • 确认服务器是否正常启动
  • 检查文件路径是否正确

下一步

完成此项后，请尝试以下挑战：

🚀 实现更复杂的工具

  • 文件操作工具
  • 数据库协作工具

🚀 实际的AI与助手集成

  • Claude Desktop内置到
  • 创建配置文件

🚀 部署到生产环境

  • 安全增强
  • 性能优化

🚀 社区贡献

  • 发布自制服务器
  • 文档改进

许可证

这个Hanson教材MIT 在许可证下提供。

反馈

关于本教材的反馈和改善提案GitHub的，之Issues求值时使用曲面法线的原始方向。

那么，MCP欢迎来到这个世界！

从第1章开始依次进行，实际一边移动手MCP的理解吧。

相关 MCP