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生态系统：提供协议基础