Mcp Learning Project

Mcp Learning Project

笔记 TypeScript

🚀 MCP学习项目 - 完整指南

这是一个全面的教程项目，将教授你从入门到进阶的模型上下文协议（Model Context Protocol，MCP）开发。你将学习服务器端（后端）和客户端（前端）的开发。

🚀 快速开始

1. 项目设置

# 创建项目目录
mkdir mcp-learning-project
cd mcp-learning-project

# 初始化npm项目
npm init -y

# 安装依赖
npm install @modelcontextprotocol/sdk

# 安装开发依赖
npm install --save-dev typescript @types/node tsx

2. 创建package.json

{
"name": "mcp-learning-project",
"version": "1.0.0",
"description": "Learn MCP development from beginner to advanced",
"main": "dist/server.js",
"type": "module",
"scripts": {
"build": "tsc",
"start:server": "node dist/server.js",
"start:client": "node dist/client.js dist/server.js",
"dev:server": "tsx src/server.ts",
"dev:client": "tsx src/client.ts dist/server.js",
"demo": "npm run build && npm run start:client"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^0.4.0"
},
"devDependencies": {
"@types/node": "^20.0.0",
"tsx": "^4.0.0",
"typescript": "^5.0.0"
}
}

3. 创建TypeScript配置文件

创建 tsconfig.json：

{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "node",
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"outDir": "./dist",
"rootDir": "./src",
"declaration": true,
"skipLibCheck": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}

4. 保存代码文件

  • 将 MCP学习服务器 代码保存为 src/server.ts
  • 将 MCP学习客户端 代码保存为 src/client.ts

5. 构建并运行项目

# 构建项目
npm run build

# 运行交互式客户端（这也将启动服务器）
npm run demo

✨ 主要特性

入门级别

  • ✅ 基础MCP服务器结构和概念
  • ✅ 简单工具的创建和注册
  • ✅ 参数处理和验证
  • ✅ 基本的客户端连接和工具调用

中级水平

  • ✅ 工具调用之间的状态管理
  • ✅ 资源管理（为AI提供数据）
  • ✅ 数据处理和复杂操作
  • ✅ 客户端 - 服务器通信模式

高级阶段

  • ✅ 具有持久状态的CRUD操作
  • ✅ 全面的错误处理
  • ✅ 用于AI交互的提示模板
  • ✅ 最佳实践和生产环境考虑因素

📦 安装指南

见快速开始部分的步骤，包含项目设置、依赖安装、配置文件创建等内容。

💻 使用示例

基础用法

// 服务器设置
const server = new Server({
name: 'my-server',
version: '1.0.0'
}, {
capabilities: {
tools: {},      // Functions AI can call
resources: {},  // Data AI can read  
prompts: {}     // Templates AI can use
}
});

// 工具注册
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'my_tool',
description: 'What this tool does',
inputSchema: { /* JSON Schema */ }
}
]
}));

// 工具实现
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
// Process the tool call and return results
return {
content: [{
type: 'text',
text: 'Tool response'
}]
};
});

// 客户端设置
const client = new Client({
name: 'my-client',
version: '1.0.0'
}, {
capabilities: { /* client capabilities */ }
});

// 连接到服务器
const transport = new StdioClientTransport(/* server process */);
await client.connect(transport);

// 发现服务器功能
const tools = await client.listTools();
const resources = await client.listResources();

// 使用服务器工具
const result = await client.callTool({
name: 'tool_name',
arguments: { /* tool parameters */ }
});

高级用法

// 以下是一些高级场景的代码示例
// 例如创建自定义工具、资源和提示等

// 创建自定义工具 - 天气工具
{
name: 'weather',
description: 'Get weather information',
inputSchema: {
type: 'object',
properties: {
city: { type: 'string', description: 'City name' },
units: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
},
required: ['city']
}
}

// 创建自定义资源 - 配置资源
{
uri: 'config://app-settings',
name: 'Application Settings',
description: 'Current application configuration',
mimeType: 'application/json'
}

// 创建交互式提示 - 代码审查提示
{
name: 'code-review',
description: 'Start a code review session',
arguments: [
{
name: 'language',
description: 'Programming language',
required: true
},
{
name: 'focus',
description: 'Review focus (security, performance, style)',
required: false
}
]
}

📚 详细文档

学习路径

阶段1：理解基础

  1. 启动交互式客户端：

    npm run demo

  2. 尝试基本命令：

    mcp-learning> help
mcp-learning> tools
mcp-learning> call hello_world {"name": "Alice"}

  3. 了解资源：

    mcp-learning> resources
mcp-learning> read mcp-concepts

阶段2：实践操作

  1. 运行入门级演示：

    mcp-learning> demo beginner

  2. 练习工具调用：

    mcp-learning> call calculator {"operation": "add", "a": 5, "b": 3}
mcp-learning> call calculator {"operation": "divide", "a": 10, "b": 0}

  3. 理解状态管理：

    mcp-learning> call counter {"action": "get"}
mcp-learning> call counter {"action": "increment", "amount": 5}
mcp-learning> call counter {"action": "get"}

阶段3：高级概念

  1. 运行中级演示：

    mcp-learning> demo intermediate

  2. 处理复杂数据：

    mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "sort"}
mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "average"}

  3. CRUD操作：

    mcp-learning> call task_manager {"action": "create", "task": {"title": "Learn MCP", "priority": "high"}}
mcp-learning> call task_manager {"action": "list"}

阶段4：生产就绪

  1. 运行高级演示：

    mcp-learning> demo advanced

  2. 学习错误处理：

    mcp-learning> call error_demo {"error_type": "none"}
mcp-learning> call error_demo {"error_type": "validation"}

  3. 研究最佳实践：

    mcp-learning> read best-practices

关键概念解释

1. MCP服务器（后端）

服务器为AI模型提供功能：

// 服务器设置
const server = new Server({
name: 'my-server',
version: '1.0.0'
}, {
capabilities: {
tools: {},      // Functions AI can call
resources: {},  // Data AI can read  
prompts: {}     // Templates AI can use
}
});

// 工具注册
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'my_tool',
description: 'What this tool does',
inputSchema: { /* JSON Schema */ }
}
]
}));

// 工具实现
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
// Process the tool call and return results
return {
content: [{
type: 'text',
text: 'Tool response'
}]
};
});

2. MCP客户端（前端）

客户端连接到服务器并使用其功能：

// 客户端设置
const client = new Client({
name: 'my-client',
version: '1.0.0'
}, {
capabilities: { /* client capabilities */ }
});

// 连接到服务器
const transport = new StdioClientTransport(/* server process */);
await client.connect(transport);

// 发现服务器功能
const tools = await client.listTools();
const resources = await client.listResources();

// 使用服务器工具
const result = await client.callTool({
name: 'tool_name',
arguments: { /* tool parameters */ }
});

3. 通信流程

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   AI Model  │ ───▶ │ MCP Client  │ ───▶ │ MCP Server  │
│             │      │ (Frontend)  │      │ (Backend)   │
│             │ ◀─── │             │ ◀─── │             │
└─────────────┘      └─────────────┘      └─────────────┘
▲                      │                      │
│                      │                      │
└──────────────────────┴──────────────────────┘
Uses server capabilities

实验思路

创建自己的工具：

  1. 天气工具：

    {
name: 'weather',
description: 'Get weather information',
inputSchema: {
type: 'object',
properties: {
city: { type: 'string', description: 'City name' },
units: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
},
required: ['city']
}
}

  2. 文件系统工具：

    {
name: 'file_operations',
description: 'Basic file system operations',
inputSchema: {
type: 'object',
properties: {
action: { type: 'string', enum: ['list', 'read', 'write'] },
path: { type: 'string', description: 'File or directory path' },
content: { type: 'string', description: 'Content to write' }
},
required: ['action', 'path']
}
}

  3. 数据库工具：

    {
name: 'database',
description: 'Simple in-memory database operations',
inputSchema: {
type: 'object',
properties: {
action: { type: 'string', enum: ['create', 'read', 'update', 'delete'] },
table: { type: 'string', description: 'Table name' },
data: { type: 'object', description: 'Data to store/update' },
id: { type: 'string', description: 'Record ID' }
},
required: ['action', 'table']
}
}

创建自定义资源：

  1. 配置资源：

    {
uri: 'config://app-settings',
name: 'Application Settings',
description: 'Current application configuration',
mimeType: 'application/json'
}

  2. 文档资源：

    {
uri: 'docs://api-reference',
name: 'API Reference',
description: 'Complete API documentation',
mimeType: 'text/markdown'
}

创建交互式提示：

  1. 代码审查提示：
    {
name: 'code-review',
description: 'Start a code review session',
arguments: [
{
name: 'language',
description: 'Programming language',
required: true
},
{
name: 'focus',
description: 'Review focus (security, performance, style)',
required: false
}
]
}

调试和故障排除

常见问题：

  1. 服务器无法启动：

    # 检查TypeScript是否正确编译
npm run build

# 查找编译错误
npx tsc --noEmit

# 检查是否缺少依赖
npm install

  2. 客户端无法连接：

    # 确保服务器路径正确
node dist/client.js dist/server.js

# 检查服务器进程是否启动
node dist/server.js

  3. 工具调用失败：

    // 在服务器中添加调试信息
console.error(`[DEBUG] Tool called: ${name}`, JSON.stringify(args));

// 仔细验证输入参数
if (typeof args.requiredParam === 'undefined') {
throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter');
}

调试模式：

在服务器和客户端启用详细日志记录：

// 在服务器中
console.error('[SERVER]', 'Detailed log message');

// 在客户端  
console.log('[CLIENT]', 'Connection status:', connected);

下一步：构建生产服务器

1. 添加实际功能

用实际有用的功能替换演示工具：

// 示例：实际的文件系统访问
private async handleFileOperations(args: any) {
const { action, path, content } = args;

switch (action) {
case 'read':
return {
content: [{
type: 'text',
text: await fs.readFile(path, 'utf-8')
}]
};
case 'write':
await fs.writeFile(path, content);
return {
content: [{
type: 'text',
text: `File written: ${path}`
}]
};
}
}

2. 添加外部集成

// 示例：HTTP API集成
private async handleApiCall(args: any) {
const { url, method, data } = args;

const response = await fetch(url, {
method,
headers: { 'Content-Type': 'application/json' },
body: data ? JSON.stringify(data) : undefined
});

return {
content: [{
type: 'text',
text: JSON.stringify({
status: response.status,
data: await response.json()
}, null, 2)
}]
};
}

3. 添加持久化功能

import * as fs from 'fs/promises';

class PersistentMCPServer {
private dataFile = './mcp-data.json';

async loadState(): Promise<Map<string, any>> {
try {
const data = await fs.readFile(this.dataFile, 'utf-8');
return new Map(Object.entries(JSON.parse(data)));
} catch {
return new Map();
}
}

async saveState(state: Map<string, any>): Promise<void> {
const data = Object.fromEntries(state);
await fs.writeFile(this.dataFile, JSON.stringify(data, null, 2));
}
}

4. 添加身份验证

private validateAuth(headers: any): boolean {
const token = headers['authorization'];
return token === 'Bearer your-secret-token';
}

private async handleSecureTool(args: any, headers: any) {
if (!this.validateAuth(headers)) {
throw new McpError(ErrorCode.InvalidParams, 'Authentication required');
}

// 继续工具逻辑...
}

🔧 技术细节

服务器和客户端的工作原理

服务器端通过 Server 类初始化，设置名称、版本和功能（工具、资源、提示）。使用 setRequestHandler 方法注册工具和处理工具调用请求。客户端通过 Client 类初始化，连接到服务器后可以发现服务器的功能并调用工具。

通信流程

AI模型通过MCP客户端与MCP服务器进行交互。客户端负责连接服务器、发现功能和调用工具，服务器负责提供功能和处理工具调用请求。

错误处理

在服务器和客户端中，通过捕获异常和验证输入参数来处理错误。例如，在工具调用时检查输入参数是否合法，若不合法则抛出 McpError 异常。

📚 额外资源

官方文档：

社区示例：

高级主题：

  • 用于Web服务的HTTP传输
  • 用于实时通信的WebSocket传输
  • 自定义传输实现
  • 性能优化技术
  • 安全最佳实践

🎯 学习练习

练习1：扩展计算器

添加更多操作：power、sqrt、factorial、sin、cos

练习2：构建笔记系统

创建用于创建、编辑、搜索和组织带标签笔记的工具。

练习3：添加外部API集成

与真实的API（天气、新闻、股票价格）集成并创建相应的工具。

练习4：构建项目管理系统

创建一个全面的项目管理系统，包含任务、截止日期、优先级和进度跟踪。

练习5：添加实时功能

实现可以向客户端发送通知或更新的工具。

🏆 掌握清单

入门级别 ✅

  • [ ] 理解MCP架构（客户端、服务器、传输）
  • [ ] 创建带有输入验证的基本工具
  • [ ] 处理简单的工具调用和响应
  • [ ] 阅读并理解错误消息

中级水平 ✅

  • [ ] 实现具有持久化功能的有状态工具
  • [ ] 创建并为AI提供资源
  • [ ] 处理复杂的数据处理
  • [ ] 实现适当的错误处理模式

高级阶段 ✅

  • [ ] 构建具有复杂状态的CRUD操作
  • [ ] 创建交互式提示模板
  • [ ] 实现适用于生产环境的错误处理
  • [ ] 理解安全和身份验证概念
  • [ ] 优化生产环境的性能

专家级别 🚀

  • [ ] 构建自定义传输层
  • [ ] 创建MCP服务器框架
  • [ ] 实现高级安全措施
  • [ ] 构建分布式MCP架构
  • [ ] 为MCP生态系统做出贡献

🎉 恭喜！

现在你已经从前端和后端的角度全面了解了MCP开发。你可以：

  • 构建MCP服务器，提供工具、资源和提示
  • 创建MCP客户端，与服务器进行有效交互
  • 优雅地处理错误 并实现适当的验证
  • 管理工具调用和会话之间的状态
  • 遵循最佳实践 进行生产环境的实现

本项目中的交互式学习环境让你亲身体验所有MCP概念。以此为基础，为任何领域或用例构建你自己的专业MCP服务器！

编码愉快！🚀

默认排序 时间排序

0 个评论

« 上一篇
Y
下一篇 »
Teamretro Mcp Server
  • 0 关注
  • 0 收藏，31 浏览
  • system 提出于 2025-10-02 23:18

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »