MCP Server Poc

🚀 MCP 服務器 POC

本項目是一個用於增強 AI 助手功能的 Model Context Protocol (MCP) 服務器的概念驗證實現，藉助自定義工具和資源，為 AI 助手帶來更強大的能力。

🚀 快速開始

本項目展示瞭如何創建和使用一個 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 傳輸機制出現問題。

📚 詳細文檔

故障排除

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 提供。