mcp-learning-project - 前后端开发全覆盖，助开发者实践掌握MCP协议核心

探索

MCP Learning Project

这是一个全面的MCP开发学习项目，从入门到高级，涵盖前后端开发，通过实践掌握MCP协议的核心概念和实现方法。

教育与学习工具开发者工具 #MCP开发 #学习项目 #前后端 .TypeScript

评分 : 2分

下载量 : 7.5K

更新时间 : 2025-07-29

打开站点

什么是MCP Learning Project?

这是一个完整的MCP开发学习项目，通过实践教学帮助开发者从基础到高级掌握Model Context Protocol的开发。项目包含服务端(后端)和客户端(前端)开发内容。

如何使用MCP Learning Project?

通过交互式学习环境，您可以逐步学习MCP开发的各个阶段，从基础工具调用到高级状态管理。

适用场景

适合想要学习AI工具开发、构建AI辅助应用或创建自定义MCP服务器的开发者。

主要功能

基础功能

学习MCP服务器基础结构、简单工具创建和参数处理

中级功能

状态管理、资源服务和复杂数据处理

高级功能

持久化状态管理、错误处理和提示模板

交互式学习

内置交互式客户端，可直接测试和体验功能

优势

渐进式学习路径，从基础到高级

完整的功能覆盖，包含服务端和客户端

内置交互式学习环境

详细的文档和示例

局限性

需要基本的编程知识

目前仅支持TypeScript/JavaScript实现

交互式客户端仅限命令行界面

如何使用

项目设置

创建项目目录并安装必要依赖

启动学习环境

构建项目并启动交互式客户端

开始学习

按照学习路径逐步尝试不同功能

使用案例

基础工具调用

调用简单的问候工具

计算器工具

使用内置计算器进行数学运算

任务管理

创建和管理任务列表

常见问题

需要什么前置知识?

如何添加自定义工具?

可以用于生产环境吗?

🚀 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：理解基础

启动交互式客户端：
```
npm run demo
```

尝试基本命令：

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

了解资源：

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

阶段2：实践操作

运行入门级演示：
```
mcp-learning> demo beginner
```

练习工具调用：

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

理解状态管理：

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

阶段3：高级概念

运行中级演示：
```
mcp-learning> demo intermediate
```

处理复杂数据：

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"}

CRUD操作：

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

阶段4：生产就绪

运行高级演示：
```
mcp-learning> demo advanced
```

学习错误处理：

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

研究最佳实践：
```
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

实验思路

创建自己的工具：

天气工具：

{
  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']
  }
}

文件系统工具：

{
  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']
  }
}

数据库工具：

{
  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']
  }
}

创建自定义资源：

配置资源：

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

文档资源：

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

创建交互式提示：

代码审查提示：

{
  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
    }
  ]
}

调试和故障排除

常见问题：

服务器无法启动：

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

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

# 检查是否缺少依赖
npm install

客户端无法连接：

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

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

工具调用失败：

// 在服务器中添加调试信息
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');
  }
  
  // 继续工具逻辑...
}