MCP with RAG Demo

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  # On Windows: mcp-env\Scripts\activate

3. 安装所需依赖：

pip install -r requirements.txt

项目结构

mcp-demo/
├── server.py           # Main MCP server implementation
├── client_example.py   # Example client to interact with the server
├── requirements.txt    # Project dependencies
├── sample_data.txt     # Sample data available as a resource
├── tools/
│   ├── __init__.py     # Package initialization
│   └── rag_tools.py    # RAG tools implementation
└── README.md           # This readme file

运行演示

第 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 服务

# Make sure your virtual environment is activated
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

# Run the client with SSE mode
python client_example.py --sse http://localhost:8000

如果 URL 中尚未包含 "/sse"，客户端会自动追加该路径。

通过 stdio 连接

# Make sure your virtual environment is activated
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

# Run the client with stdio mode
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.
    """

故障排除

客户端连接问题

如果运行客户端时出现 "Connection refused" 错误：

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 License 发布。

设置

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）