使用说明

项目简介

本项目是一个基于Python实现的MCP服务器示例，它通过服务器发送事件（SSE）协议与客户端通信，并提供了一个实用的图书搜索工具。该工具利用古腾堡计划的开放API，允许用户通过关键词搜索免费电子书。此项目旨在展示如何构建一个云原生的、解耦的MCP服务器，客户端可以独立连接和使用服务器提供的功能。

主要功能点

提供图书搜索工具: 通过 'search_gutenberg_books' 工具，用户可以根据关键词在古腾堡计划图书馆中搜索图书信息。
基于SSE的MCP服务器: 使用SSE协议作为传输层，支持客户端与服务器之间的实时通信和解耦部署。
易于部署和运行: 提供详细的安装和运行步骤，支持使用uv或pip进行环境管理。
示例客户端: 包含一个Python客户端示例 'client.py'，演示如何连接和使用MCP服务器提供的工具。
OpenRouter.ai LLM集成: 客户端示例集成了OpenRouter.ai的LLM中转平台，可以利用LLM调用服务器提供的工具，实现更智能的交互体验。

安装步骤

克隆仓库

git clone https://github.com/jayliangdl/py-mcp-sse
cd py-mcp-sse

环境配置 (推荐使用uv)

# 安装uv (如果未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并安装依赖
uv venv
uv pip install .

或者使用pip：

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/MacOS
# 或
.venv\.Scripts\activate  # Windows

# 安装依赖
pip install .

配置环境变量 复制 '.env.sample' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入你的 OpenRouter API 密钥 (用于客户端示例中的LLM调用，非MCP服务器运行必需，但为了完整体验示例建议配置):
```
OPENROUTER_API_KEY=your_api_key_here
```

服务器配置

MCP客户端需要配置以下信息以连接到此MCP服务器。以下是配置示例 (JSON 格式):

{
  "serverName": "book_search_server",
  "command": "uv run mcp_server.py",
  "args": [
    "--host", "0.0.0.0",  // 服务器绑定的主机地址，0.0.0.0 表示监听所有可用网络接口
    "--port", "8080"     // 服务器监听的端口号，默认为 8080
  ]
}

配置参数说明:

'serverName': 服务器的名称，可以自定义，用于在客户端标识服务器。例如: "book_search_server"。
'command': 启动 MCP 服务器的命令。这里使用 'uv run mcp_server.py'，确保你的环境中已安装 'uv' 并能正确执行。如果使用 pip，则命令可能需要调整为 'python mcp_server.py' 或 'python3 mcp_server.py'，取决于你的Python环境配置。
'args': 传递给启动命令的参数列表。
- '--host 0.0.0.0': 指定服务器监听的主机地址为 '0.0.0.0'，表示接受来自任何网络接口的连接。如果需要限制访问，可以设置为 '127.0.0.1' 或特定的IP地址。
- '--port 8080': 指定服务器监听的端口号为 '8080'。如果端口被占用，可以修改为其他未被占用的端口。

注意: 客户端需要根据实际情况配置 'command' 和 'args'，确保能够正确启动和连接到 MCP 服务器。

基本使用方法

启动服务器 在项目根目录下，运行以下命令启动 MCP 服务器：
```
uv run mcp_server.py --host 0.0.0.0 --port 8080
```
或使用默认主机和端口：
```
uv run mcp_server.py
```
服务器成功启动后，会监听在指定的地址和端口，等待客户端连接。
启动客户端 打开另一个终端窗口，同样在项目根目录下，运行客户端示例 'client.py'，并指定 MCP 服务器的 SSE 地址。默认服务器地址为 'http://localhost:8080/sse'。
```
uv run client.py http://localhost:8080/sse
```
客户端启动后，会连接到 MCP 服务器，并列出可用的工具。之后，你可以与 AI 助手进行对话，例如：
```
用户: 请推荐一些科幻小说
```
AI 助手会调用 'search_gutenberg_books' 工具搜索相关图书，并将结果返回给你。你可以继续与 AI 助手对话，利用图书搜索工具获取更多信息。

退出客户端: 在客户端运行过程中，输入 'quit' 或按下 'Ctrl+C' 可以安全退出客户端。