MCP学习助理
一个全面的学习项目，展示 模型上下文协议（MCP） 通过构建一个连接到天气和笔记服务的人工智能代理。
🎯 项目概述
该项目实现了一个AI代理，该代理使用MCP提供：
- 🌤️ 天气信息 -任何位置的实时天气数据
- 📝 个人笔记管理 -保存、检索和组织个人笔记
- 🤖 自然语言接口 -使用简单的英语命令进行交互
🏗️ 建筑
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ CLI Interface │────│ AI Agent │────│ MCP Host │
│ │ │ Orchestrator │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
│ │
┌──────────────┐ │
│ Natural │ │
│ Language │ │
│ Processing │ │
└──────────────┘ │
│
┌───────────────────────────────────┴───────────────────────────────────┐
│ │
┌───────▼────────┐ ┌────────▼─────────┐
│ Weather Server │ │ Notes Server │
│ (MCP) │ │ (MCP) │
│ │ │ │
│ Tools: │ │ Tools: │
│ • getWeather │ │ • saveNote │
└────────────────┘ │ • listNotes │
│ • getNoteById │
└──────────────────┘🚀 快速开始
先决条件
- Node.js 18+
- npm或纱线
安装
- 克隆和安装依赖关系：
git clone
cd MCP_learn
npm install- 构建项目：
npm run build- 启动交互式助手：
npm run agent
# or for development:
npm run dev使用示例
交互模式
npm run agent
🤖 Welcome to MCP Learning Assistant!
You: What's the weather in Tokyo?
🤖 Assistant: Here's the current weather information:
🌡️ Temperature: 22°C
☁️ Conditions: Partly Cloudy
💧 Humidity: 65%
💨 Wind Speed: 12 km/h
🕐 Updated: 2024-01-15T10:30:00.000Z
You: Save a note about my dentist appointment tomorrow at 2 PM
🤖 Assistant: Note saved successfully!
📝 ID: abc123
📋 Title: Dentist appointment
🏷️ Tags: None
📅 Created: 1/15/2024, 10:30:45 AM单个命令
# Ask a question and exit
npm run agent ask "What's the weather in London?"
# Show system status
npm run agent status🛠️ MCP服务器
天气服务器
位于 src/servers/weather-server.ts
工具：
getWeather(location: string)-获取某个位置的天气信息
特征：
- 实时天气模拟
- 基于位置的查询
- 详细的天气指标（温度、湿度、风速）
Notes服务器
位于 src/servers/notes-server.ts
工具：
saveNote(title: string, content: string, tags?: string[])-保存新笔记listNotes(tag?: string)-列出所有笔记或按标签筛选getNoteById(id: string)-检索特定笔记
特征：
- 持久存储（JSON文件）
- 基于标签的组织
- 全文注释内容
- 元数据跟踪（创建/更新日期）
🧠 AI 代理
AI代理(src/agent/ai-agent.ts)提供：
意图分类
- 使用模式匹配进行自然语言理解
- 上下文提取（位置、注释内容等）
- 信心评分
请求路由
- 基于意图的自动工具选择
- 错误处理和回退响应
- 多步对话
响应生成
- 用户友好的格式
- 工具使用透明度
- 错误解释
🔧 发展
项目结构
src/
├── agent/
│ ├── ai-agent.ts # AI orchestrator with NLU
│ ├── cli.ts # Command-line interface
│ └── mcp-host.ts # MCP server connection manager
├── servers/
│ ├── weather-server.ts # Weather MCP server
│ └── notes-server.ts # Notes MCP server
├── shared/
│ └── config.ts # Shared configuration and types
└── index.ts # Main entry point可用脚本
npm run build # Compile TypeScript
npm run dev # Start with hot reload
npm run start # Start compiled version
npm run agent # Start CLI interface
npm run weather-server # Start weather server only
npm run notes-server # Start notes server only测试服务器
测试天气服务器：
# In one terminal
npm run weather-server
# In another terminal
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm run weather-server测试笔记服务器：
# In one terminal
npm run notes-server
# In another terminal
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm run notes-server📚 学习目标
该项目教授：
1. MCP协议基础
- 服务器/客户端架构
- 工具定义和注册
- 请求/响应模式
- 传输机制（stdio）
2. MCP服务器开发
- 使用SDK实现MCP服务器
- 工具模式定义
- 错误处理模式
- 资源管理
3. MCP客户端集成
- 连接到多个MCP服务器
- 管理服务器生命周期
- 工具发现和执行
- 统一的工具界面
4. AI代理架构
- 意图分类和NLU
- 请求编排
- 上下文管理
- 响应生成
5. 生产模式
- 错误处理和恢复
- 日志记录与监视
- 配置管理
- 平滑关闭
🔍 代码示例
创建简单的MCP服务器
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = new Server({
name: 'my-server',
version: '1.0.0',
}, {
capabilities: { tools: {} }
});
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [{
name: 'myTool',
description: 'A simple tool',
inputSchema: {
type: 'object',
properties: { input: { type: 'string' } },
required: ['input']
}
}]
};
});
const transport = new StdioServerTransport();
await server.connect(transport);连接到MCP服务器
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const client = new Client({
name: 'my-client',
version: '1.0.0'
}, { capabilities: {} });
const transport = new StdioClientTransport({
reader: serverProcess.stdout,
writer: serverProcess.stdin
});
await client.connect(transport);
const tools = await client.listTools();
const result = await client.callTool({
name: 'myTool',
arguments: { input: 'Hello' }
});🚀 扩展项目
添加新的MCP服务器
- 在中创建服务器
src/servers/ - 使用MCP SDK实现工具
- 将配置添加到
src/shared/config.ts - 更新代理以处理新意图
集成真正的LLM API
在中替换基于规则的意图分类器 ai-agent.ts 与：
- OpenAI GPT API
- API人类克劳德
- 通过Ollama获得当地法学硕士学位
- 其他LLM提供商
添加更多工具
- 文件系统操作
- 数据库查询
- API集成
- 日历管理
- 电子邮件功能
📖 额外资源
🤝 贡献
这是一个学习项目！请随意：
- 添加新的MCP服务器
- 改进AI代理
- 添加测试
- 加强文件编制
- 分享你的学习成果
📄 许可证
麻省理工学院许可证-请随意使用此项目进行学习和实验！