用Python和FastMCP为AI助手打造专属文档搜索工具：从本地Stdio到云端SSE部署全流程

用Python和FastMCP构建AI文档搜索引擎从本地到云端的智能解决方案在AI编程助手日益普及的今天开发者们面临一个共同挑战如何让这些助手准确理解并回答特定技术框架的问题传统方法依赖静态知识库但技术文档更新频繁导致回答经常过时。本文将介绍如何利用Python和FastMCP技术构建一个实时搜索主流AI框架官方文档的智能工具彻底解决这一痛点。1. 技术选型与架构设计1.1 为什么选择MCP协议MCPModel Context Protocol作为新兴的标准化接口协议解决了AI工具集成中的三个核心问题接口统一化不同厂商的Function Call格式差异导致集成困难MCP提供了类似USB-C的统一接口工具管理标准化通过声明式描述自动处理输入输出转换减少胶水代码传输协议多样化同时支持本地Stdio和云端SSE两种通信模式对比传统Function Call方式MCP在文档搜索场景的优势尤为明显特性传统Function CallMCP协议开发效率低需手动适配高自动转换维护成本高低跨平台支持有限完善实时性依赖实现内置长连接支持1.2 系统架构设计整个文档搜索工具采用微服务架构核心组件包括class DocumentSearchSystem: def __init__(self): self.search_engine SerperAPIWrapper() self.content_extractor BeautifulSoupParser() self.mcp_server FastMCPServer() self.cache_layer LRUCache() async def process_query(self, query: str, library: str): 端到端查询处理流程 cached self.cache_layer.get((query, library)) if cached: return cached results await self.search_engine.search(query, library) extracted await self.content_extractor.parse(results) self.cache_layer.set((query, library), extracted) return extracted关键设计考虑缓存层减少重复搜索的开销异步处理最大化I/O密集型操作的效率模块化设计便于更换搜索引擎或解析器2. 本地Stdio模式实现2.1 环境配置与依赖安装推荐使用uv作为Python环境管理工具跨平台安装命令如下# MacOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex项目初始化步骤创建项目目录并进入初始化虚拟环境安装核心依赖uv init doc-search cd doc-search uv venv source .venv/bin/activate # Windows: .venv\Scripts\activate uv add fastmcp[cli] httpx beautifulsoup4 python-dotenv2.2 核心搜索功能实现文档搜索的核心在于精准定位和内容提取我们采用站点限定搜索策略docs_urls { langchain: python.langchain.com/docs, llama-index: docs.llamaindex.ai/en/stable, autogen: microsoft.github.io/autogen/stable, # 其他框架配置... } async def search_docs(query: str, library: str) - str: 执行限定站点的文档搜索 if library not in docs_urls: raise ValueError(f不支持的框架: {library}) site docs_urls[library] query fsite:{site} {query} results await serper_search(query) return await extract_content(results)提示Serper API的免费套餐足够个人开发使用生产环境建议升级到付费计划2.3 MCP工具封装将搜索功能封装为MCP工具使其可以被AI助手调用from mcp import tool tool() async def get_ai_docs(query: str, framework: str) - str: 获取AI框架技术文档 参数: query: 搜索关键词 framework: 框架名称(langchain|llama-index|...) 返回: 相关文档内容文本 return await search_docs(query, framework)3. 云端SSE部署方案3.1 SSE协议优势分析相比本地Stdio模式SSEServer-Sent Events特别适合云端部署跨网络访问无需SSH隧道或端口转发自动重连内置心跳机制保持连接多客户端支持单个服务端可服务多个AI助手资源隔离搜索服务与客户端环境解耦3.2 服务端实现基于Starlette构建SSE服务端from fastmcp import FastMCP from mcp.server.sse import SseServerTransport import uvicorn app FastMCP(ai-docs-searcher) app.tool() async def search_ai_docs(query: str, framework: str): # 工具实现同上 pass def create_sse_app(): sse_transport SseServerTransport(/mcp-events/) return sse_transport.create_app(app) if __name__ __main__: uvicorn.run(create_sse_app(), host0.0.0.0, port8020)启动命令uv run server.py --host 0.0.0.0 --port 80203.3 客户端配置云端部署后客户端通过HTTP连接服务端async with mcp_client.SSEClient(http://your-server:8020/mcp-events) as client: result await client.call_tool(search_ai_docs, {query: agent memory, framework: langchain}) print(result)4. 集成到开发环境4.1 Cursor集成配置在Cursor中启用MCP服务只需两步项目根目录创建.cursor/mcp.json添加服务配置{ mcpServers: { ai-docs-searcher: { command: uv, args: [run, server.py] } } }集成后效果输入/docs触发文档搜索自动补全框架名称结果直接嵌入对话流4.2 性能优化技巧实际使用中发现三个关键优化点缓存策略对相同查询返回缓存结果将API调用减少70%内容精简提取文档核心内容去除导航和广告等噪音连接池复用HTTP连接降低SSE模式下的延迟# 优化后的搜索实现 async def optimized_search(query: str, framework: str) - str: cache_key f{query}:{framework} if cached : cache.get(cache_key): return cached async with httpx.AsyncClient(timeout30.0) as client: results await client.post(SERPER_URL, json{q: query}) cleaned clean_content(results.text) cache.set(cache_key, cleaned, ttl3600) return cleaned5. 扩展与定制5.1 支持新框架的步骤添加对新AI框架的支持非常简单在docs_urls字典中添加条目测试站点搜索语法是否有效验证内容提取准确性例如新增支持HuggingFace Agentsdocs_urls[huggingface] huggingface.co/docs/agents5.2 高级功能扩展基于现有架构可以轻松实现更多实用功能多框架联合搜索同时查询多个框架的文档版本切换支持查看不同版本的文档代码示例提取专门提取文档中的代码片段本地文档索引对高频访问文档建立本地索引tool() async def search_multiple_frameworks(query: str, frameworks: List[str]) - Dict[str, str]: 同时在多个框架中搜索文档 results {} for framework in frameworks: results[framework] await search_docs(query, framework) return results在实际项目中这套系统显著提升了开发效率。一个典型场景是当AI助手遇到不熟悉的概念时会自动触发文档搜索并将最相关的内容整合到回答中而不是给出可能过时的通用建议。