MCP服务器和客户端演示
一个展示 模型上下文协议（MCP） 使用服务器和客户端组件实现。该项目演示了如何构建公开工具、资源和提示的MCP服务器，以及如何使用AI模型构建使用它们的客户端。
概述
本项目实施：
- MCP服务器：显示用户管理工具、资源和提示
- MCP客户端：连接到服务器并使用AI（Google Gemini）使用MCP工具处理查询的交互式CLI
特性
服务器功能
资源：
users://all-从数据库中获取所有用户users://{userId}/profile-获取个人用户配置文件（模板资源）
工具：
create-user-使用指定的详细信息创建新用户create-random-user-使用人工智能生成的虚假数据生成和创建用户
提示：
generate-fake-user-基于名称生成虚假用户数据的模板
客户能力
- 用于探索MCP服务器功能的交互式CLI界面
- 使用Google Gemini的人工智能查询处理
- 基于自然语言查询的自动工具调用
- 手动浏览和执行工具、资源和提示
项目结构
mcp-server-and-client/
├── src/
│ ├── client.ts # MCP client implementation
│ ├── server.ts # MCP server implementation
│ └── data/
│ └── users.json # User data store
├── package.json
├── tsconfig.json
└── .env # Environment variables (not tracked)先决条件
- Node.js v18或更高版本
- npm或纱线
- Google Gemini API密钥
安装
- 克隆存储库：
git clone
cd mcp-server-and-client- 安装依赖项：
npm install- 创建一个
.env项目根目录中的文件：
GEMINI_API_KEY=your_google_gemini_api_key_here获取Gemini API密钥：
- 访问 谷歌人工智能工作室
- 使用您的Google帐户登录
- 创建并复制API密钥
用法
运行服务器（用于检查）
npm run server:dev使用MCP检查器与服务器交互：
npm run server:inspect这将打开一个web界面，您可以在其中测试服务器功能。
运行客户端
首先，构建服务器（客户端连接所需）：
npm run server:build然后启动客户端：
npm run client:dev客户端提供了一个交互式菜单，其中包含以下选项：
- 查询 -使用MCP工具提出自然语言问题
- 工具 -手动执行可用工具
- 资源 -浏览和阅读资源
- 鼓励 -执行提示模板
查询示例
使用“查询”选项时，您可以问：
- “为我获取所有用户”
- “创建一个名为John Doe的新用户”
- “显示用户1的配置文件”
- “创建随机用户”
AI将自动选择并执行适当的MCP工具。
可用脚本
| 脚本 | 描述 |
|---|---|
npm run server:build | 将TypeScript服务器编译为JavaScript |
npm run server:build:watch | 服务器编译的监视模式 |
npm run server:dev | 在开发模式下运行服务器 |
npm run server:inspect | 使用MCP检查器运行服务器 |
npm run client:dev | 运行交互式客户端 |
技术栈
- TypeScript -类型安全开发
- MCP-SDK (
@modelcontextprotocol/sdk)-模型上下文协议实现 - AI SDK (
ai+@ai-sdk/google)AI模型与工具调用的集成 - 问询者 (
@inquirer/prompts)-交互式CLI提示 - 萨德 -架构验证
- Dotenv。 -环境变量管理
建筑
服务器架构
服务器使用MCP SDK通过stdio传输公开功能：
McpServer → StdioServerTransport → Client Connection客户端体系结构
客户端连接到服务器并与Google Gemini集成：
Client → StdioClientTransport → Server
↓
Gemini AI (with MCP tools)重要注意事项和假设
偏离最佳实践
注： 本项目仅用于演示目的。 一些设计决策偏离了生产最佳实践：
- 客户端和服务器位于同一位置
- 当前：客户端和服务器都在同一个存储库和目录中 - 最佳实践：在生产中，MCP服务器和客户端应该是单独的项目 - 演示原因：简化设置，并在一个地方演示完整的MCP工作流程
- 基于文件的数据存储
- 当前：使用JSON文件(users.json)用于数据持久性 - 最佳实践：使用合适的数据库（PostgreSQL、MongoDB等） - 演示原因：消除了外部依赖和设置复杂性
- 无身份验证/授权
- 当前：未实现身份验证机制 - 最佳实践：实施适当的身份验证和授权 - 演示原因：关注MCP概念而非安全
- 硬编码配置
- 当前：服务器连接详细信息硬编码在客户端中 - 最佳实践：使用配置文件或服务发现 - 演示原因：简化演示
- 单一运输方式
- 当前：仅实现stdio传输 - 最佳实践：支持多种传输方式（HTTP、WebSocket等） - 演示原因：Stdio最适合当地开发
- 有限的错误处理
- 当前：基本错误处理 - 最佳实践：全面的错误处理、日志记录和监控 - 演示原因：保持代码简洁易读
- 无测试
- 当前：无单元或集成测试 - 最佳实践：全面的测试覆盖率 - 演示原因：专注于核心功能演示
生产建议
在构建生产MCP应用程序时：
- 将服务器和客户端分离为独立的项目
- 使用具有连接池的适当数据库
- 实现身份验证（OAuth、API密钥等）
- 添加全面的错误处理和日志记录
- 使用基于环境的配置
- 添加速率限制和输入验证
- 实施监控和可观察性
- 编写全面的测试
- 使用合适的CI/CD管道
- 考虑使用HTTP/WebSocket传输进行远程连接
- 实施适当的会话管理
- 添加请求验证和清理
故障排除
API关键问题
如果你看到 LoadAPIKeyError:
- 确保您的
.env文件存在于项目根目录中 - 验证
GEMINI_API_KEY设置正确 - 确保API键值周围没有引号
连接问题
如果客户端无法连接到服务器：
- 确保你已经跑过了
npm run server:build第一 - 检查一下
build/server.js存在 - 验证Node.js版本是否为v18或更高版本
TypeScript错误
如果你遇到TypeScript编译错误：
npm run server:build检查控制台输出是否有特定的错误消息。
了解更多
许可证
国际学生委员会
贡献
这是一个示范项目。您可以根据自己的学习目的进行分叉和修改。