MCP Server Python

🚀 MCP服務器：文檔檢索與網頁抓取（uv + FastMCP）

本項目提供了一個輕量級的異步MCP（模型上下文協議）服務器，它具備一個工具，可用於檢索和清理流行的AI/Python生態系統庫的官方文檔內容。該項目使用了以下技術和工具：

• fastmcp：用於在標準輸入輸出上定義和運行MCP服務器。
• httpx：用於異步HTTP調用。
• serper.dev：提供類似谷歌的搜索功能（通過API）。
• groq API（大語言模型）：將原始HTML清理為易讀的文本塊。
• python-dotenv：用於管理環境變量。
• uv：作為包管理器和運行器（快速、基於鎖文件，適用於Python 3.11及以上版本）。

✨ 主要特性

• 搜索範圍限制在官方文檔域名（uv、langchain、openai、llama-index）內。
• 工具 get_docs(query, library)：返回帶有 SOURCE: 標籤的拼接後的清理部分。
• 具備流式安全的異步設計（在使用大語言模型清理之前對大型HTML頁面進行分塊處理）。
• 提供單獨的 client.py 文件，演示瞭如何作為MCP客戶端連接並調用該工具，然後使用大語言模型進行後處理。

🚀 快速開始

前提條件

• Python 3.11及以上版本
• 已安裝 uv（https://docs.astral.sh/uv/）
• 擁有以下API密鑰：SERPER_API_KEY、GROQ_API_KEY

1. 克隆並安裝

git clone <your-repo-url> mcp-server-python
cd mcp-server-python
uv sync

這將根據 pyproject.toml 和 uv.lock 創建或刷新 .venv。

2. 配置環境變量

在項目根目錄下創建一個 .env 文件：

SERPER_API_KEY=your_serper_api_key_here
GROQ_API_KEY=your_groq_api_key_here

可選操作：如果後續要擴展功能，可以添加其他模型設置。

3. 直接運行MCP服務器

uv run mcp_server.py

服務器將啟動並在標準輸入輸出上等待（除非添加日誌記錄，否則不會有額外輸出）。它會註冊工具 get_docs。

4. 使用提供的客戶端

uv run client.py

你應該會看到類似以下的輸出：

Available tools: ['get_docs']
ANSWER: <model-produced answer referencing SOURCE lines>

如果工具列表為空，請確保服務器已正確啟動且沒有拋出異常（可添加日誌記錄，詳見下文）。

💻 使用示例

基礎用法

from mcp.client.stdio import stdio_client
from mcp import ClientSession, StdioServerParameters
import asyncio

async def demo():
    params = StdioServerParameters(command="uv", args=["run", "mcp_server.py"])
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            docs = await session.call_tool("get_docs", {"query": "install", "library": "uv"})
            print(docs.content[:500])

asyncio.run(demo())

📚 詳細文檔

工具：get_docs

函數簽名

get_docs(query: str, library: str) -> str

支持的庫（鍵）

uv、langchain、openai、llama-index。

執行流程

1. 構建限定網站的查詢：site:<docs-domain> <query>。
2. 調用Serper API獲取自然搜索結果。
3. 通過 httpx 異步獲取每個結果的URL。
4. 將HTML拆分為約4000字符的塊（確保內存安全和符合大語言模型的限制）。
5. 使用Groq大語言模型（openai/gpt-oss-20b）和系統提示清理每個塊。
6. 拼接每個塊並使用 SOURCE: <url> 進行標記，以便追溯。

返回值

一個適合用於檢索增強提示的大文本塊，保留了來源歸屬行。

架構

依賴說明

核心運行時依賴（來自 pyproject.toml）：

• fastmcp：MCP服務器輔助工具。
• httpx：異步HTTP客戶端。
• groq：Groq API客戶端。
• python-dotenv：從 .env 文件加載變量。
• trafilatura：啟發式內容提取（目前部分使用，可擴展）。

💡 使用建議

如果添加更多抓取工具，為了提高性能，可複用單個 httpx.AsyncClient。

日誌記錄與調試

要查看服務器的運行情況，可以臨時添加以下代碼：

import logging, sys
logging.basicConfig(level=logging.INFO, stream=sys.stderr)

將上述代碼放在 mcp_server.py 文件導入語句之後的頂部位置。由於協議使用標準輸出進行JSON-RPC通信，因此請僅將日誌發送到標準錯誤輸出。

常見問題

• 工具列表為空：服務器提前退出或崩潰，請添加標準錯誤日誌記錄；手動運行 uv run mcp_server.py。
• .text 屬性錯誤：清理器返回 None，請確保在 fetch_url 或大語言模型調用中返回實際的字符串。
• Serper返回401錯誤：API密鑰錯誤或缺失，請檢查 .env 文件並重新加載shell。
• 搜索結果為空：查詢範圍過窄，請簡化查詢或驗證域名鍵。
• 延遲過高：進行了大量順序的大語言模型塊調用，請進行批量處理或減小塊大小。

擴展建議

• 添加緩存層（例如 sqlite 或內存字典），避免重複獲取相同的URL。
• 使用 asyncio.gather() 並行化URL獲取和清理操作（注意速率限制和大語言模型成本）。
• 添加其他工具（例如 summarize_diff、list_endpoints）。
• 提供結構化的JSON輸出（來源列表 + 清理後的文本），而不是拼接後的字符串。
• 使用 pytest 和 pytest-asyncio 添加測試（模擬Serper和大語言模型API）。

使用已激活的虛擬環境運行

如果你已經激活了虛擬環境，並且想使用該環境而不是項目的固定環境，可以強制 uv 指向它：

uv run --active client.py

否則，uv 會警告你當前激活的 $VIRTUAL_ENV 與項目的 .venv 不同，但仍會繼續使用項目環境。

許可證

如果你打算分發該項目，請在此處添加許可證部分（例如MIT許可證）。

故障排除速查表

貢獻指南

1. 分叉倉庫並創建分支。
2. 運行 uv sync。
3. 為新工具添加測試（如果有新增工具）。
4. 提交清晰描述的拉取請求。

路線圖（可選）

• [] 為工具參數添加JSON模式元數據。
• [] 提供結構化響應格式（{來源, 文本} 列表）。
• [] 添加緩存層。
• [] 添加速率限制/退避機制。
• [] 添加持續集成工作流（代碼檢查 + 測試）。

致謝

• Serper.dev：提供搜索API
• Groq：提供快速的開源模型服務
• Astral：開發了 uv
• MCP生態系統：提供協議基礎