MCP Server POC

一个模型上下文协议 (MCP) 服务器的概念验证实现，用于通过自定义工具和资源增强 AI 助手的能力。

概述

本项目演示了如何创建和使用模型上下文协议 (MCP) 服务器，该服务器可以为 AI 助手（如 Claude 和其他支持 MCP 标准的助手）提供自定义工具和资源。 该服务器包括：

• LangChain、LlamaIndex 和 OpenAI 的文档搜索工具
• 网络爬取功能
• 与 Google Search API 集成

要求

• Python 3.11
• requirements.txt 中列出的必需软件包

安装和设置

1. 克隆此存储库：

git clone https://github.com/yourusername/mcp-server-poc.git
cd mcp-server-poc

2. 创建并激活虚拟环境：

# 创建一个 Python 3.11 虚拟环境
python -m venv venv

# 在 Windows 上激活
 .\venv\Scripts\Activate.ps1

# 在 macOS/Linux 上激活
source venv/bin/activate

3. 安装所需的软件包：

pip install -r requirements.txt

4. 设置环境变量：

   在根目录中创建一个 .env 文件，内容如下：

SERPER_API_KEY=your_serper_api_key_here

运行应用程序

要运行 MCP 服务器：

python main.py

服务器将启动并等待使用 stdio 传输方法的连接。

与 Cursor 集成

要将此 MCP 服务器与 Cursor IDE 一起使用：

1. 创建或编辑文件 ~/.cursor/mcp.json（在 Windows 上：C:\Users\<username>\.cursor\mcp.json），内容如下：

{
    "mcpServers": {
        "mcp-server": {
            "command": "python", 
            "args": [
                "ABSOLUTE/PATH/TO/main.py"
            ]
        }
    }
}

2. 将路径替换为 main.py 文件的绝对路径。

   • 在 Windows 上，使用双反斜杠：C:\\Users\\username\\path\\to\\main.py
   • 在 macOS/Linux 上，使用正斜杠：/Users/username/path/to/main.py

3. 完全重启 Cursor（包括结束任何后台进程）以加载 MCP 服务器。

功能

工具

• get_docs(query, library)：搜索指定库（langchain、llama-index 或 openai）的文档并返回相关信息

技术细节

Windows 二进制模式修复

此服务器包含一个针对 Windows 的特定修复程序，以确保与 stdio 传输正常运行：

# Set binary mode for stdin/stdout on Windows
if os.name == 'nt':
    import msvcrt
    msvcrt.setmode(sys.stdin.fileno(), os.O_BINARY)
    msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)

此修复是必要的，因为 Windows 区分文本和二进制文件处理模式，这可能会导致 MCP 使用的 stdio 传输机制出现问题。

故障排除

如果您遇到 MCP 服务器的问题：

Windows 特有问题

• "Failed to create client" 或 "Client closed" 错误：
  • 确保使用服务器中包含的二进制模式修复
  • 在 mcp.json 配置中使用带有双反斜杠的绝对路径
  • 尝试直接运行 MCP 服务器，看看是否产生任何错误输出
  • 完全退出 Cursor（包括通过任务管理器终止任何后台进程）然后再重新启动

一般问题

• 验证是否已安装所有必需的软件包（pip list 检查）
• 检查配置文件中的绝对路径是否正确
• 确保 MCP 服务器以正确的 Python 版本 (3.11) 运行
• 验证您的 .env 文件是否包含所需的 API 密钥
• 尝试重新安装 MCP 包：pip uninstall mcp && pip install mcp

许可证

MIT 许可证

致谢

• 本项目使用 模型上下文协议 SDK
• 网络爬取功能由 crawl4ai 提供