使用说明

项目简介

本项目 'mcp-fun' 演示了如何使用 'FastMCP' 框架快速搭建 MCP (Model Context Protocol) 服务器。项目中包含了两个独立的 MCP 服务器示例：

BMI 计算器服务器 (bmi_server.py): 提供一个简单的 BMI (身体质量指数) 计算工具，演示了如何通过 MCP 工具向 LLM 提供计算能力。
MySQL 数据库服务器 (mcp-mysql-server/main.py): 连接 MySQL 数据库，将数据库表作为资源暴露，并提供读取数据和执行 SQL 查询的工具，演示了如何通过 MCP 资源和工具向 LLM 提供数据访问和操作能力。

此外，项目还包含一个 MCP 客户端示例 ('mcp-client/main.py')，展示了如何配置和使用 'MultiServerMCPClient' 连接和调用多个 MCP 服务器提供的工具。

主要功能点

资源管理 (MySQL Server): 将 MySQL 数据库的表结构作为资源暴露给客户端，支持客户端获取资源列表和读取资源内容。
工具注册与执行 (BMI Server & MySQL Server): 注册了 BMI 计算工具（'calculate_bmi'）、列出数据库资源工具（'list_resources'）、读取资源内容工具（'read_resource'）和执行 SQL 查询工具（'ececute_query'），允许 LLM 客户端通过调用这些工具扩展功能。
多种传输协议支持: BMI 服务器使用 'stdio' 传输协议，MySQL 服务器使用 'sse' (Server-Sent Events) 传输协议，客户端可以根据服务器类型配置不同的连接方式。
易于扩展: 基于 'FastMCP' 框架，可以方便地添加更多工具和资源，构建更复杂的 MCP 服务器。
客户端示例: 提供了一个使用 'langchain' 和 'langgraph' 框架构建的 ReAct Agent 客户端，演示了如何利用 MCP 客户端连接和使用 MCP 服务器提供的工具，构建基于 LLM 的应用。

安装步骤

克隆仓库:

git clone https://github.com/kaaquist/mcp-fun.git
cd mcp-fun

安装依赖: 在项目根目录下，以及 'mcp-client' 和 'mcp-mysql-server' 目录下分别执行：
```
pip install -r requirements.txt
```
配置 MySQL 数据库 (仅 MySQL 服务器需要):
- 复制 'mcp-mysql-server/.env.example' 文件为 'mcp-mysql-server/.env'。
- 修改 '.env' 文件中的数据库连接信息 (MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE) 为你本地 MySQL 数据库的配置。
- 你可以使用 'docker-compose.yaml' 文件快速启动一个 MySQL 数据库，具体参考 'README.md' 中的 "MySQL Docker Compose" 部分。

服务器配置 (MCP 客户端)

MCP 客户端 ('mcp-client/main.py') 需要配置连接的 MCP 服务器信息。配置信息在 'MultiServerMCPClient' 的初始化参数中定义，是一个 JSON 格式的字典，key 为服务器名称，value 为服务器连接配置。

以下是 'mcp-client/main.py' 中提供的服务器配置示例，可以直接复制使用：

{
    "bmi": {
        "command": "python",
        "args": [ "{file_path}/bmi_server.py"],  // {file_path} 需要替换为 bmi_server.py 文件的绝对路径
        "transport": "stdio"
    },
    "mysql_server": {
        "url": "http://localhost:8000/sse", // MySQL 服务器 SSE 协议的 URL
        "transport": "sse"
    }
}

配置参数说明:

'bmi': BMI 计算器服务器的名称，客户端通过此名称引用该服务器。
- 'command': 启动服务器的命令，这里使用 'python' 命令。
- 'args': 启动服务器命令的参数列表，这里指定了 'bmi_server.py' 脚本的路径。请务必将 '{file_path}' 替换为 'bmi_server.py' 文件在你本地文件系统中的绝对路径。 你可以先运行 'mcp-client/bmi_server.py' 查看其运行时输出，确认路径是否正确。
- 'transport': 服务器使用的传输协议，这里是 'stdio' (标准输入输出)。
'mysql_server': MySQL 数据库服务器的名称。
- 'url': MySQL 服务器的 URL，用于 SSE 协议连接。确保 MySQL 服务器运行在 'http://localhost:8000' 并使用 SSE 协议。
- 'transport': 服务器使用的传输协议，这里是 'sse' (Server-Sent Events)。

注意:

在运行 'mcp-client/main.py' 之前，你需要先分别启动 'bmi_server.py' 和 'mcp-mysql-server/main.py' 这两个 MCP 服务器。
'bmi_server.py' 使用 'stdio' 协议，客户端配置中指定 'command' 和 'args' 后，'MultiServerMCPClient' 会自动启动 'bmi_server.py' 进程并建立连接。
'mcp-mysql-server/main.py' 使用 'sse' 协议，你需要手动先启动 'mcp-mysql-server/main.py'，确保它运行在 'http://localhost:8000/sse'，客户端才能通过 URL 连接。你可以使用如下命令启动 'mcp-mysql-server/main.py' (确保已配置好 '.env' 文件):
```
cd mcp-mysql-server
uv run --env-file=.env main.py
```
或者使用 Docker Compose 启动，参考 'README.md'。

基本使用方法

启动 MCP 服务器:
- 按照 "服务器配置" 中的说明，手动启动 'mcp-mysql-server/main.py' (如果使用 SSE 协议)。
- 'bmi_server.py' 服务器会在客户端连接时自动启动 (stdio 协议)。

运行 MCP 客户端:

在 'mcp-client' 目录下，运行 'main.py' 客户端程序:

cd mcp-client
uv run --env-file=.env main.py

与客户端交互:
- 客户端启动后，会进入交互式命令行界面，提示 "Please enter your prompt."
- 输入自然语言提示，例如:
  - 'What is my BMI if my weight is 70 kg and height is 1.75 meters?' (调用 BMI 计算工具)
  - 'List all tables in the database.' (调用 MySQL 服务器的 'list_resources' 工具)
  - 'Read data from table xxx.' (将 'xxx' 替换为数据库表名，调用 'read_resource' 工具)
  - 'Execute query select * from yyy limit 5.' (将 'yyy' 替换为数据库表名，调用 'ececute_query' 工具执行 SQL 查询)
- 客户端会将提示发送给配置的 ReAct Agent，Agent 会根据提示判断是否需要调用 MCP 服务器提供的工具，并返回结果。
结束交互:
- 在每次任务完成后，客户端会询问 "Do you want to perform another task?"，选择 'n' (No) 即可退出客户端程序。

注意事项

确保 MySQL 数据库配置正确，并且 MySQL 服务器能够正常连接。
首次运行客户端前，可能需要先手动启动 'mcp-mysql-server/main.py' 服务器。
客户端需要联网才能使用 'ChatOpenAI' 模型 (默认配置)。你可以根据需要修改客户端代码，使用本地模型或其他 LLM 模型。
仔细阅读 'README.md' 文件，了解更多关于 Docker Compose 和 MySQL 数据库配置的信息。

关键词