使用说明

MCP服务器：文档检索和网络剪贴（uv+FastMCP）

该项目提供了一个最小的异步MCP（模型上下文协议）服务器，该服务器公开了一个用于检索和清理流行AI/Python生态系统库的官方文档内容的工具。它使用：

fastmcp 通过stdio定义和运行MCP服务器。
httpx 用于异步HTTP调用。
serper.dev 用于类似谷歌的搜索（通过API）。
groq API（LLM）将原始HTML清理为可读文本块。
python-dotenv 用于环境变量管理。
uv 作为包管理器和运行器（快速、基于锁文件、Python 3.11+）。

特性

搜索仅限于官方文档域(uv, langchain, openai, llama-index).
工具： get_docs(query, library) 返回连接的已清洁部分 SOURCE: 标签。
流安全异步设计（在LLM清理之前分块大型HTML页面）。
分开 client.py 演示如何作为MCP客户端连接并调用该工具，然后使用LLM进行后处理。

快速开始

先决条件：

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

这将创建/刷新 .venv 基于 pyproject.toml + uv.lock.

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

服务器将启动并等待stdio（除非添加日志记录，否则不会有额外的输出）。它注册了工具 get_docs.

4.使用提供的客户端

uv run client.py

您应该看到类似以下内容：

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

如果列表为空，请确保服务器正确启动并且没有引发异常（添加日志记录——见下文）。

工具：get_docs

签字：

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

支持的库（密钥）： uv, langchain, openai, llama-index.

流量：

构建站点受限查询： site:<docs-domain> <query>.
致电Serper API获取有机结果。
通过以下方式获取每个结果URL（异步） httpx.
将HTML拆分为~4000个字符块（内存安全和LLM限制）。
使用Groq LLM清洁每个块(openai/gpt-oss-20b)系统提示。
连接并标记每个块 SOURCE: <url> 为了可追溯性。

返回值：一个适合检索增强提示的大型文本blob，保留源属性行。

建筑

文件概述：

文件	目的
`mcp_server.py`	定义 `FastMCP` 实例和实现 `search_web`, `fetch_url`，以及 `get_docs` 工具。
`client.py`	通过stdio启动服务器，列出工具，调用 `get_docs`，然后将结果提供给LLM，以获得用户友好的答案。
`utils.py`	HTML清理助手（目前使用LLM+ `trafilatura` 用于提取，Groq用于块转换）。
`.env`	环境变量（不包括在VCS中）。
`pyproject.toml`	声明依赖关系和元数据。
`uv.lock`	由生成的可复制锁文件 `uv`.

依赖关系注释

核心运行时deps（来自 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协议使用stdout，因此仅将日志发送到stderr。

常见问题：

空工具列表：服务器提前退出或崩溃——添加日志记录。
SERPER_API_KEY 缺失→ 401 或空搜索结果。
GROQ_API_KEY 缺失→ LLM清洁失败（以下情况除外 get_response_from_llm).
网络超时：调整 timeout 在 httpx.AsyncClient 电话。

延伸

思想：

添加缓存层（例如。， sqlite 或内存中的字典），以避免重新获取相同的URL。
并行URL获取+清理 asyncio.gather() （思维速率限制/LLM成本）。
添加另一个工具（例如。， summarize_diff, list_endpoints).
提供结构化的JSON输出（源列表+干净的文本），而不是连接字符串。
使用添加测试 pytest + pytest-asyncio （模拟Serper+LLM API）。

程序化使用示例（无客户端包装器）

如果你想使用客户端MCP库在Python脚本中直接调用该工具：

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())

使用活动Virtualenv运行

如果你有一个已经激活的虚拟环境，并且想使用它来代替项目的固定环境，你可以强制uv将其作为目标：

uv run --active client.py

否则，紫外线会警告你的活动 $VIRTUAL_ENV 与项目不同 .venv 但继续使用项目环境。

许可证

如果您打算分发，请在此处添加许可证部分（例如MIT）。

故障排除备忘单

症状	原因	修复
未列出工具	服务器未运行/崩溃	添加stderr日志记录；跑 `uv run mcp_server.py` 手动
属性错误 `.text`	Cleaner返回None	确保您从返回实际字符串 `fetch_url` /LLM电话
401来自Serper	API密钥错误/丢失	检查 `.env` 并重新装弹
空搜索结果	缩小查询范围	简化查询或验证域密钥
高延迟	许多连续的LLM块调用	批量处理或减少块大小

贡献

叉子和树枝。
跑 uv sync.
添加新工具的测试（如果已添加）。
以清晰的描述打开PR。

路线图（可选）

[]为工具参数添加JSON模式元数据。
[]结构化响应格式（{source，text}列表）。
[]添加缓存层。
[]添加速率限制/回退。
[]添加CI工作流（lint+tests）。

致谢

搜索API的Serper.dev
快速OSS模型服务的Groq
Astral for uv
MCP协议基础生态系统