MCP 与 RAG 演示

这个演示项目展示了如何实现一个具有检索增强生成 (RAG) 功能的模型上下文协议 (MCP) 服务器。该演示允许 AI 模型与知识库交互、搜索信息和添加新文档。

功能

• 具有工具和资源支持的 MCP 服务器
• RAG 实现（回退到内存存储）
• 用于与 MCP 服务器交互的客户端示例
• 支持 SSE (HTTP) 和 stdio 通信模式
• 简单的提示模板

前提条件

• Python 3.8+
• pip (Python 包管理器)

安装

1. 克隆存储库：

git clone <repository-url>
cd mcp-demo

2. 创建一个虚拟环境：

python -m venv mcp-env
source mcp-env/bin/activate  # 在 Windows 上：mcp-env\Scripts\activate

3. 安装所需的依赖项：

pip install -r requirements.txt

项目结构

mcp-demo/
├── server.py           # 主要的 MCP 服务器实现
├── client_example.py   # 与服务器交互的客户端示例
├── requirements.txt    # 项目依赖项
├── sample_data.txt     # 可作为资源使用的示例数据
├── tools/
│   ├── __init__.py     # 包初始化
│   └── rag_tools.py    # RAG 工具实现
└── README.md           # 此自述文件

运行演示

步骤 1：启动 MCP 服务器

您可以在两种不同的模式下运行 MCP 服务器：

选项 A：SSE (HTTP) 模式

此模式允许服务器使用服务器发送事件 (SSE) 通过 HTTP 接受连接：

python server.py --sse

默认情况下，服务器将监听 0.0.0.0:8000。您可以自定义主机和端口：

python server.py --sse --host 127.0.0.1 --port 9000

选项 B：stdio 模式

此模式允许服务器通过标准输入/输出进行通信：

python server.py --stdio

步骤 2：运行客户端示例

服务器启动并运行后，打开一个新的终端窗口（保持服务器在第一个窗口中运行）：

连接到 SSE 服务器

# 确保您的虚拟环境已激活
source mcp-env/bin/activate  # 在 Windows 上：mcp-env\Scripts\activate

# 以 SSE 模式运行客户端
python client_example.py --sse http://localhost:8000

如果 URL 中缺少 "/sse"，客户端将自动附加它。

通过 stdio 连接

# 确保您的虚拟环境已激活
source mcp-env/bin/activate  # 在 Windows 上：mcp-env\Scripts\activate

# 以 stdio 模式运行客户端
python client_example.py --stdio --command python --args "server.py --stdio"

您可以根据需要自定义命令和参数。

客户端示例的作用

客户端示例演示了几个关键操作：

1. 列出 MCP 服务器中可用的工具、资源和提示
2. 调用 echo 工具以验证基本通信
3. 使用元数据将文档添加到知识库
4. 使用 RAG 系统搜索知识库
5. 从服务器读取示例资源

可用的 MCP 工具

此演示中提供了以下工具：

• echo: 一个简单的工具，可以回显提供的消息
• add: 一个将两个数字相加的工具
• add_document: 将文档添加到知识库
• rag_search: 在知识库中搜索与查询相关的信息
• list_documents: 列出知识库中的所有文档

可用的 MCP 资源

• sample://data: 提供对 sample_data.txt 中示例数据的访问

可用的 MCP 提示

• greeting: 一个简单的问候提示模板

自定义演示

添加新工具

要添加新工具，请修改 server.py 文件：

@mcp.tool()
def your_tool_name(param1: type, param2: type) -> return_type:
    """Tool description"""
    # Tool implementation
    return result

添加新资源

要添加新资源，请修改 server.py 文件：

@mcp.resource("resource://pattern")
def your_resource_function() -> str:
    """Resource description"""
    # Resource implementation
    return "Resource content"

添加新提示

要添加新的提示模板，请修改 server.py 文件：

@mcp.prompt()
def your_prompt_name(param1: str, param2: str) -> str:
    """Prompt description"""
    return f"""
    Your prompt template text with {param1} and {param2} parameters.
    """

故障排除

客户端连接问题

如果在运行客户端时遇到“连接被拒绝”错误：

1. 确保服务器实际上在另一个终端窗口中运行
2. 检查您是否使用了正确的 URL（默认为 http://localhost:8000）
3. 确保服务器正在监听预期的接口（0.0.0.0 接受外部连接）
4. 尝试显式指定服务器 URL：python client_example.py --sse http://localhost:8000

服务器端点问题

MCP 服务器在 /sse 公开一个 SSE（服务器发送事件）端点。使用客户端连接时：

• 完整的 URL 应该是 http://localhost:8000/sse
• 如果您指定的 URL 中缺少 /sse，客户端将自动附加它

调试模式

如果遇到问题，您可以启用调试模式以获得更详细的输出：

python client_example.py --sse http://localhost:8000 --debug

常见问题

客户端连接的导入错误

如果在运行客户端示例时看到导入错误，请确保已安装所有必需的依赖项：

pip install mcp-sdk

找不到包或版本不匹配

如果您遇到导入错误或版本兼容性问题，请尝试安装特定版本的 MCP 包：

pip install mcp-sdk>=1.0.0

许可证

本项目作为示例实现提供，并根据 MIT 许可证提供。

设置

1. 安装所需的依赖项：

   pip install -r requirements.txt
   

2. 创建一个 .env 文件：

   cp .env.example .env
   

3. 编辑 .env 文件并添加您的 OpenAI API 密钥：

   OPENAI_API_KEY=your_api_key_here
   

   您还可以在 .env 文件中配置其他选项：

   • MCP_SERVER_URL: MCP 服务器的 URL（默认：http://localhost:3000）
   • DEBUG: 启用调试模式（默认：false）

用法

运行演示：

python openai_example.py

您可以使用命令行参数覆盖 .env 文件中的设置：

python openai_example.py --api-key YOUR_API_KEY --server-url http://your-server-url

环境变量

可以在 .env 文件中设置以下环境变量：

• OPENAI_API_KEY: 您的 OpenAI API 密钥（必需）
• MCP_SERVER_URL: MCP 服务器的 URL（可选）
• DEBUG: 启用调试模式（可选）

命令行参数

• --api-key: 您的 OpenAI API 密钥（覆盖 .env 文件）
• --server-url: MCP 服务器的 URL（覆盖 .env 文件）
• --debug: 启用调试模式（覆盖 .env 文件）

MCP OpenAI 示例

此示例演示了如何将模型控制协议 (MCP) 与 OpenAI 的 API 一起使用。

设置

1. 安装所需的依赖项：

   pip install -r requirements.txt
   

2. 基于 .env.example 模板创建一个 .env 文件：

   cp .env.example .env
   

3. 编辑 .env 文件并添加您的 OpenAI API 密钥：

   OPENAI_API_KEY=your_api_key_here
   

运行示例

运行示例脚本：

python openai_example.py

您也可以直接指定选项：

python openai_example.py --api-key your_api_key_here --server-url http://localhost:3000 --debug

示例的作用

1. 从 .env 文件加载环境变量
2. 使用您的 API 密钥配置 OpenAI 客户端
3. 列出可用的模型
4. 使用简单的提示创建聊天完成

环境变量

• OPENAI_API_KEY: 您的 OpenAI API 密钥（必需）
• MCP_SERVER_URL: MCP 服务器的 URL（可选，默认为 http://localhost:3000）
• DEBUG: 启用调试日志记录（可选，默认为 false）