AI导哈

模型上下文协议演示

一个展示模型上下文协议（MCP）实现的演示项目，包含服务器和客户端组件，用于构建和消费MCP工具、资源和提示。

  • by frankkinuthian
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 frankkinuthian/mcp-server-and-client-quick-crash

使用说明

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密钥

安装

  1. 克隆存储库：
git clone <repository-url>
cd mcp-server-and-client
  1. 安装依赖项：
npm install
  1. 创建一个 .env 项目根目录中的文件：
GEMINI_API_KEY=your_google_gemini_api_key_here

获取Gemini 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)

重要注意事项和假设

偏离最佳实践

注： 本项目仅用于演示目的。 一些设计决策偏离了生产最佳实践：

  1. 客户端和服务器位于同一位置

    • 当前：客户端和服务器都在同一个存储库和目录中
    • 最佳实践：在生产中，MCP服务器和客户端应该是单独的项目
    • 演示原因：简化设置，并在一个地方演示完整的MCP工作流程

  2. 基于文件的数据存储

    • 当前：使用JSON文件(users.json)用于数据持久性
    • 最佳实践：使用合适的数据库（PostgreSQL、MongoDB等）
    • 演示原因：消除了外部依赖和设置复杂性

  3. 无身份验证/授权

    • 当前：未实现身份验证机制
    • 最佳实践：实施适当的身份验证和授权
    • 演示原因：关注MCP概念而非安全

  4. 硬编码配置

    • 当前：服务器连接详细信息硬编码在客户端中
    • 最佳实践：使用配置文件或服务发现
    • 演示原因：简化演示

  5. 单一运输方式

    • 当前：仅实现stdio传输
    • 最佳实践：支持多种传输方式（HTTP、WebSocket等）
    • 演示原因：Stdio最适合当地开发

  6. 有限的错误处理

    • 当前：基本错误处理
    • 最佳实践：全面的错误处理、日志记录和监控
    • 演示原因：保持代码简洁易读

  7. 无测试

    • 当前：无单元或集成测试
    • 最佳实践：全面的测试覆盖率
    • 演示原因：专注于核心功能演示

生产建议

在构建生产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

检查控制台输出是否有特定的错误消息。

了解更多

许可证

国际学生委员会

贡献

这是一个示范项目。您可以根据自己的学习目的进行分叉和修改。

相关 MCP