MCP 服务器 POC

一个用于增强 AI 助手功能的 Model Context Protocol (MCP) 服务器的概念验证实现，通过自定义工具和资源。

概述

该项目展示了如何创建和使用一个 Model Context Protocol (MCP) 服务器，该服务器可以为支持 MCP 标准的 AI 助手（如 Claude 等）提供自定义工具和资源。该服务器包括：

• 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. 创建并激活虚拟环境：

# 初始化 uv 包管理器 
uv init

# 创建 Python 3.11 虚拟环境
uv venv

# 在 Windows 上激活
 .venv\Scripts\activate

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

3. 安装所需的包：

uv pip install -r requirements.txt

4. （可选）如果需要开发或替代集成，安装 MCP CLI 工具：

uv add "mcp[cli]"

5. 设置环境变量：

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

SERPER_API_KEY=your_serper_api_key_here

运行应用程序

要运行 MCP 服务器：

uv run mcp 

服务器将启动并等待使用 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 传输正确运行：

# 设置(stdin/stdout)的二进制模式在 Windows 上
if os.name == 'nt':
    import msvcrt
    msvcrt.setmode(sys.stdin.fileno(), os.O_BINARY)
    msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)

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

故障排除

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

Windows 特定问题

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

一般问题

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

许可证

MIT License

致谢

• 该项目使用了 Model Context Protocol SDK
• 网页抓取功能由 crawl4ai 提供