1. 为什么需要AI文档查询MCP服务作为一个长期泡在代码里的开发者我太理解那种被技术文档折磨的痛苦了。记得上周五晚上11点我正赶着用LangChain实现一个智能客服系统结果卡在一个API参数配置上。翻遍了官方文档、Stack Overflow、各种技术博客硬是找不到明确的用法说明。这种场景相信每个开发者都遇到过——当你在IDE里写代码时最需要的是能直接获取精准文档的技术助手。传统解决方案存在三个致命伤首先手动浏览器搜索效率低下要在十几个标签页间反复横跳其次不同框架文档结构差异大像LlamaIndex和AutoGen的文档组织方式就完全不同最重要的是现有AI助手如Cursor虽然能写代码但对技术文档的理解往往停留在训练数据阶段无法获取最新版本的真实文档内容。这就是我们要构建的MCPModel Context Protocol服务的核心价值——在IDE中实现技术文档的实时精准查询。具体来说它能做到自动识别你正在使用的框架如输入LangChain的Agent怎么用实时抓取该框架最新官方文档精准返回与当前编码上下文相关的文档片段整个过程无需离开IDE界面实测下来这个服务让我查文档的时间从平均5分钟缩短到15秒以内。更重要的是它解决了AI助手一本正经胡说八道的老毛病——所有回答都基于真实文档内容不是凭空生成的。2. 技术架构设计解析2.1 MCP协议的核心优势MCP相当于AI工具生态的USB-C接口。在它出现前每个大模型厂商都有自己的Function Call格式就像手机充电口有Lightning、MicroUSB、Type-C等各种标准。我们开发者要对接不同AI服务时得写各种适配层代码既麻烦又容易出错。MCP的三大创新点特别实用统一工具调用规范无论底层是OpenAI、Anthropic还是本地模型工具调用都用同一套JSON格式内置异步通信机制支持SSEServer-Sent Events长连接适合需要持续交互的场景开发环境深度集成原生适配Cursor、Cline等智能IDE调用工具就像写普通函数一样自然我们的文档查询服务就建立在MCP的tool装饰器之上。这个设计太巧妙了——你只需要用Python写个普通异步函数加个装饰器就能变成AI可调用的工具。比如后面会看到的get_docs函数本质上就是个加强版的谷歌搜索网页解析器。2.2 系统工作原理整个服务的工作流程可以分为四个关键阶段查询意图识别用户在IDE输入LangChain的Memory怎么配置AI助手解析出关键参数queryMemory配置,librarylangchain定向文档搜索使用谷歌的site:语法限定搜索范围如site:python.langchain.com/docs Memory配置通过Serper API获取前三名搜索结果比直接用Google API便宜90%智能内容提取用BeautifulSoup解析HTML去除导航栏/广告等噪音合并多个页面的相关内容片段结果格式化返回自动添加文档来源链接保留代码示例等关键格式我特别喜欢这个设计中的失败处理机制当主文档站不可用时会自动回退到框架的GitHub仓库wiki页面最大限度保证服务可用性。3. 手把手实现服务端3.1 基础环境搭建先搞定基础设施这里我推荐使用UV工具链Astral出品就是做Rust那个团队。相比传统的pip/virtualenv组合UV的依赖解析速度快10倍而且完美支持MCP所需的异步IO环境。安装命令根据系统有所不同# MacOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex初始化项目时有个小技巧先创建.env文件存放敏感信息避免API密钥泄露# 项目初始化 uv init mcp-docs-search cd mcp-docs-search # 创建虚拟环境 uv venv source .venv/bin/activate # Windows用.venv\Scripts\activate # 安装核心依赖 uv add mcp[cli] httpx beautifulsoup4 python-dotenv # 创建环境变量文件 echo SERPER_API_KEY你的API密钥 .env echo OPENAI_API_KEYsk-xxx .env提示Serper API的免费套餐足够日常开发使用注册后记得开启AI Search选项3.2 核心工具函数实现文档查询的核心是这两个函数import json import os import httpx from bs4 import BeautifulSoup from mcp import tool # 主流AI框架文档域名映射 DOCS_MAP { langchain: python.langchain.com/docs, llama-index: docs.llamaindex.ai/en/stable, autogen: microsoft.github.io/autogen/stable, # 其他框架... } async def search_web(query: str, site: str) - list: 使用Serper API进行限定站点搜索 payload json.dumps({ q: fsite:{site} {query}, num: 3 # 取前三个结果 }) headers { X-API-KEY: os.getenv(SERPER_API_KEY), Content-Type: application/json } async with httpx.AsyncClient() as client: try: resp await client.post( https://google.serper.dev/search, headersheaders, datapayload, timeout10.0 ) return resp.json().get(organic, []) except httpx.TimeoutException: return [] async def extract_content(url: str) - str: 从网页提取核心内容 async with httpx.AsyncClient() as client: try: resp await client.get(url, timeout10.0) soup BeautifulSoup(resp.text, html.parser) # 移除不需要的元素 for element in soup([nav, footer, script, style]): element.decompose() # 优先获取article/main标签内容 main_content soup.find(article) or soup.find(main) or soup return main_content.get_text( , stripTrue) except Exception as e: return f内容提取失败: {str(e)}这里有几个优化点值得注意使用异步HTTP客户端httpx提升并发性能设置合理的超时时间10秒避免长时间阻塞内容提取时优先获取article或main标签内容彻底移除导航栏、页脚等干扰元素3.3 封装MCP工具将上述函数封装成AI可调用的工具tool() async def get_docs(query: str, library: str) - str: 获取AI框架技术文档内容 参数: query: 查询关键词 (如 Memory配置) library: 框架名称 (如 langchain) 返回: 合并后的文档文本 if library not in DOCS_MAP: return f暂不支持{library}框架 results await search_web(query, DOCS_MAP[library]) if not results: return 未找到相关文档 contents [] for result in results: content await extract_content(result[link]) contents.append(f## 来源: {result[link]}\n{content}) return \n\n.join(contents)[:5000] # 限制返回长度这个tool装饰器是MCP的魔法所在它会自动生成符合MCP规范的OpenAPI Schema处理类型转换和参数校验将函数注册到MCP服务总线3.4 启动MCP服务本地开发推荐使用Stdio协议部署时用SSE协议from mcp.server.fastmcp import FastMCP from dotenv import load_dotenv load_dotenv() # 加载.env文件 mcp FastMCP(DocsSearch) # 注册工具 mcp.register_tool(get_docs) if __name__ __main__: # 本地开发用stdio协议 mcp.run(transportstdio) # 生产部署用SSE协议 # uvicorn.run(mcp.asgi_app(), host0.0.0.0, port8020)启动命令非常简单uv run main.py # 本地模式 uv run main.py --host 0.0.0.0 --port 8020 # 生产模式4. 客户端集成实战4.1 Cursor IDE配置Cursor是目前对MCP支持最好的IDE之一。配置只需要三步在项目根目录创建.cursor/mcp.json{ mcpServers: { docs-search: { command: uv, args: [ --directory, /path/to/your/project, run, main.py ] } } }重启Cursor在设置中开启MCP服务在聊天框直接提问LangChain的ConversationBufferMemory怎么用Cursor会自动调用我们的get_docs工具返回的结果会是这样## 来源: https://python.langchain.com/docs/modules/memory/types/buffer ConversationBufferMemory 用于存储聊天历史记录... 示例代码: memory ConversationBufferMemory() memory.save_context({input: 你好}, {output: 有什么可以帮您})4.2 自定义客户端开发如果需要更灵活的控制可以用Python写自定义客户端from mcp import ClientSession from mcp.client.stdio import stdio_transport async def query_docs(question: str, framework: str): async with ClientSession(*stdio_transport()) as session: result await session.call_tool( get_docs, {query: question, library: framework} ) print(result.content[0].text) # 示例查询LlamaIndex的存储用法 asyncio.run(query_docs(向量存储配置, llama-index))这个客户端特别适合集成到自动化测试流程中比如在CI/CD环节自动验证示例代码是否与最新文档一致。5. 高级优化技巧5.1 性能调优方案在实际使用中我发现三个关键优化点缓存层设计from functools import lru_cache lru_cache(maxsize100) async def cached_search(query: str, site: str) - list: return await search_web(query, site)智能限流策略from asyncio import Semaphore # 限制并发请求数 semaphore Semaphore(5) async def safe_extract(url: str) - str: async with semaphore: return await extract_content(url)混合搜索策略先尝试官方文档站失败后搜索GitHub Issues最后回退到Stack Overflow5.2 安全防护措施生产环境必须添加的安全配置from fastapi.middleware.cors import CORSMiddleware app mcp.asgi_app() # 添加CORS限制 app.add_middleware( CORSMiddleware, allow_origins[https://your-domain.com], allow_methods[POST], max_age600 ) # 速率限制 from slowapi import Limiter from slowapi.util import get_remote_address limiter Limiter(key_funcget_remote_address) app.state.limiter limiter5.3 监控与日志推荐使用Prometheus监控关键指标from prometheus_client import Counter, start_http_server SEARCH_COUNTER Counter(docs_search_total, Total search requests, [framework]) tool() async def get_docs(query: str, library: str) - str: SEARCH_COUNTER.labels(frameworklibrary).inc() # ...原有逻辑...启动监控服务器start_http_server(8000) # 指标暴露在8000端口