MCP 服务器/客户端 示例

🔍 Model Context Protocol（MCP）的实现示例项目

💡 项目背景

此项目旨在实现以下目标：

• MCP 的基础学习: 提供 Model Context Protocol 基本概念的最小实现示例
• 简单的实现: 通过实现仅包含最少功能的 MCP 服务器，专注于协议的本质部分
• 独立实现: 展示如何独立实现 MCP 服务器，而不依赖于 Claude Desktop App 等特定客户端
• 低成本验证: 通过 Google Gemini 经由 MCP 进行验证，可以低成本（利用免费额度等）进行验证

通过此示例项目，您可以学习 MCP 的基本机制和工具集成实现方法。

🎯 功能概要

此项目提供以下主要功能：

MCP 服务器功能

• 提供数值比较工具
  • 实现一个比较两个数字大小的工具。虽然很简单，但可以解决 AI 容易出错的比较问题（例如 9.11 和 9.9 的大小比较）。
• 工具的注册和执行管理

工具使用前

工具使用后

MCP 客户端功能

• 与服务器的双向通信
• 通过配置文件进行连接管理
• 错误处理和重试机制

聊天界面

• 基于 Google Gemini API 的自然语言处理
• 与 MCP 工具的集成功能

📋 必要条件

• Bun 运行时（v1.0.0 以上）
• 支持 MCP 的客户端（例如：Claude Desktop App、Cline、Cursor）
• Gemini API 密钥（使用聊天 CLI 时）

🚀 快速开始

1. 项目设置

# 安装依赖
bun install

# 创建环境变量文件
cp .env.example .env

# 在 .env 文件中设置 Gemini API 密钥
# 从 Google Cloud Console 获取 API 密钥并进行设置
GEMINI_API_KEY="your-api-key-here"

2. 服务器设置

// 创建 server-config.json
{
    "my-simple-tool": {
        "command": "bun",
        "args": [
            "run",
            "/absolute/path/to/mcp-server/index.ts"
        ]
    }
}

※ 请根据环境将路径更改为适当的绝对路径。

3. 运行

# 启动聊天 CLI
bun run chat

🏗️ 系统构成

目录结构

src/
├── index.ts                 # 聊天 CLI 的入口点
├── llm-clients/            # LLM 客户端实现
│   └── gemini.ts           # Google Gemini API 客户端
├── mcp-client/            # MCP 客户端模块
│   ├── client.ts          # MCP 工具客户端实现
│   └── config.ts          # 客户端配置加载器
└── mcp-server/           # MCP 服务器模块
    ├── index.ts          # 服务器的入口点
    └── tools/            # MCP 工具实现
        └── compare-numbers.ts  # 数值比较工具

组件说明

MCP 服务器

• src/mcp-server/: 符合 Model Context Protocol 的服务器实现
• 管理工具的注册和执行
• 提供数值比较等工具

MCP 客户端

• src/mcp-client/: 与 MCP 服务器通信的客户端库
• 加载服务器配置并管理连接
• 调用工具并处理响应

LLM 客户端

• src/llm-clients/: 管理与语言模型的对话
• 使用 Google Gemini API 进行自然语言处理
• 实现与 MCP 工具的集成功能

数据流

1. 用户在聊天 CLI 中输入

   • 以文本形式输入问题或命令
   • 可以使用日语进行自然形式的输入

2. Gemini 客户端处理输入

   • 分析输入文本
   • 判断是否需要使用工具
   • 选择合适的工具和参数

3. 根据需要调用 MCP 工具

   • 通过 MCP 客户端与服务器通信
   • 将工具所需的参数传递给服务器
   • 接收执行结果

4. 将工具的执行结果传递给 Gemini 以生成响应

   • 将工具的输出转换为自然语言
   • 生成符合上下文的适当说明
   • 发生错误时创建易于理解的消息

5. 将结果显示给用户

   • 以易于理解的日语显示处理结果
   • 如果发生错误，还会提供解决方法

⚙️ 配置指南

服务器配置

服务器的配置由以下两个文件管理：

1. 环境变量（.env）

# 从 Google Cloud Console 获取 API 密钥并进行设置
GEMINI_API_KEY="your-api-key-here"

2. 服务器配置（server-config.json）

// 创建 server-config.json
{
    "my-simple-tool": {
        "command": "bun",
        "args": [
            "run",
            "/absolute/path/to/mcp-server/index.ts"
        ]
    }
}

配置项目	必须	默认值	说明
command	✓	-	服务器执行命令（bun/node 等）
args	✓	-	执行参数（服务器文件路径等）
disabled	-	false	服务器的禁用标志
autoApprove	-	[]	自动批准的工具列表
timeout	-	30000	工具执行的超时时间（毫秒）

⚠️ 重要注意事项

• 服务器文件的路径必须使用绝对路径
• 更改配置后需要重新启动客户端
• autoApprove 的使用应尽可能少
• 环境变量在 .env 文件中管理，并添加到 .gitignore 中

基本用法

# 开始聊天
bun run chat

# 结束聊天的方法
exit    # 结束
quit    # 结束
结束     # 结束