1. 项目概述为你的AI编程助手构建一个透明、可控的文档检索大脑如果你和我一样日常重度依赖 Cursor、Claude Code 这类“AI原生”的 IDE 来写代码那你肯定遇到过这样的场景当你向助手提问一个关于某个框架比如 LangGraph的具体问题时它有时能给出精准的答案有时却会“胡言乱语”或者干脆说“我不了解这个库的最新信息”。这背后的原因很大程度上取决于它背后那个神秘的“文档检索”机制。这些 IDE 通常会内置一些工具来读取像llms.txt这样的网站索引文件以获取上下文。但这个过程对开发者来说是个黑盒——你不知道它读了哪些文档怎么读的甚至读没读对。今天要聊的这个开源项目mcpdoc就是来解决这个痛点的。它是一个基于Model Context Protocol (MCP)的文档服务器。简单说它让你能完全掌控你的 AI 助手在回答问题时到底去查阅哪些文档、如何查阅并且整个过程对你完全透明、可审计。你可以把它想象成给你的 AI 编程助手外挂了一个“自定义知识库查询引擎”而且这个引擎的每一次“翻书”动作你都能看得一清二楚。它的核心价值在于将文档检索的主动权交还给开发者。通过配置你信任的llms.txt文件比如官方发布的 LangChain、LangGraph 文档索引mcpdoc会暴露出标准的 MCP 工具主要是fetch_docs让你的 Cursor、Windsurf 或 Claude Desktop 等应用在需要时通过调用这些工具来获取精确的文档片段而不是依赖其内部不透明的机制。这对于需要精准、可靠技术支持的开发者尤其是那些在复杂框架如 AI Agent 开发框架上进行构建的工程师来说是一个游戏规则的改变者。2. 核心概念与工作原理深度解析要玩转mcpdoc我们需要先理解几个关键概念这能帮你更好地理解它“为什么”要这么设计以及如何最大化其效用。2.1 llms.txtAI 的“网站地图”llms.txt不是一个新概念但它是这个项目的基石。你可以把它理解为一个专门为大型语言模型LLM优化的、机器可读的“网站地图”或“文档索引”。传统的robots.txt告诉网络爬虫哪里不能去而llms.txt则是主动告诉 AI 助手“如果你想了解我请重点看这些页面。”一个典型的llms.txt文件内容非常简单就是一系列 Markdown 文档的 URL 列表。例如LangGraph Python 的llms.txt可能包含了其官方文档中所有核心概念、API 参考和教程的链接。当 AI 助手需要回答关于 LangGraph 的问题时它理论上应该优先从这个列表指向的页面中寻找答案因为这些页面被维护者认定为是最相关、最权威的。然而问题在于不同的 IDE 和 AI 应用Cursor, Windsurf, Claude Code实现读取和利用llms.txt的机制各不相同且通常不向用户开放。你无法确认它是否真的使用了你期望的文档源也无法在它给出错误答案时进行排查。2.2 Model Context Protocol (MCP)工具调用的标准化协议MCP 是 Anthropic 推出的一种开放协议旨在标准化 AI 应用程序客户端与外部工具、数据源服务器之间的通信。你可以把它类比成 AI 世界的USB 协议或HTTP 协议——它定义了一套通用的“插口”和“数据格式”让不同的“设备”工具服务器可以轻松地接入不同的“主机”AI 应用。mcpdoc就是一个 MCP 服务器。它实现了 MCP 协议对外提供两个核心工具list_doc_sources: 列出当前服务器配置的所有llms.txt源比如“LangGraph Python”、“LangChain JS”。fetch_docs: 根据给定的 URL必须属于已配置的llms.txt文件中的链接抓取并返回该 URL 对应的 Markdown 文档内容。当 Cursor 这样的 MCP 客户端配置了mcpdoc服务器后它就可以通过 MCP 协议调用这些工具。这取代了其内置的、不透明的文档检索逻辑。2.3 mcpdoc 的工作流与安全边界mcpdoc的工作流程可以概括为以下几步理解这个过程对后续配置和排错至关重要初始化与源加载启动mcpdoc时你通过命令行参数或配置文件指定一个或多个llms.txt文件的 URL。服务器会立即抓取这些文件解析出其中包含的所有文档链接。构建安全域白名单这是mcpdoc一个非常重要的安全设计。它不会允许fetch_docs工具抓取任意互联网 URL。如果指定的是远程llms.txtURL如https://langchain-ai.github.io/langgraph/llms.txtmcpdoc会自动将该 URL 的域名langchain-ai.github.io加入允许列表。如果指定的是本地文件路径则不会自动添加任何域名你必须通过--allowed-domains参数显式指定。你始终可以通过--allowed-domains参数额外添加域名或者使用*通配符允许所有域名极度不推荐存在安全风险。工具暴露与等待调用服务器启动后通过 SSE (Server-Sent Events) 或 stdio 等传输方式将list_doc_sources和fetch_docs工具暴露给连接的客户端。客户端如 Cursor的查询过程用户提问“LangGraph 中有哪些类型的内存”Cursor 的 AI 代理根据预设的规则Rules决定调用mcpdoc服务器的工具。它首先调用list_doc_sources了解可用的文档集。然后可能调用fetch_docs获取llms.txt文件本身的内容分析其中哪些 URL 可能与问题相关。接着针对分析出的相关 URL例如关于内存管理的文档页逐个调用fetch_docs获取具体内容。最后AI 代理综合这些检索到的文档内容生成最终答案。整个过程中在 Cursor 的 MCP 工具调用面板或 MCP Inspector 中你可以清晰地看到每一次fetch_docs被调用的记录、传入的 URL 以及返回的文档内容片段。这种透明性是调试 AI 回答准确性的强大武器。注意安全与可控是第一要务这个白名单机制至关重要。它确保了你的 AI 助手只能从你明确授权的、可信的域名获取文档防止了潜在的安全风险比如被诱导访问恶意或无关的网站。在配置时请务必确认你添加的llms.txt来源是官方或可信的。3. 从零开始环境搭建与 mcpdoc 服务器部署理论讲完我们动手实操。我会带你走一遍完整的安装和本地测试流程并解释每个步骤背后的考量。3.1 安装 uv现代 Python 项目的打包与运行利器项目推荐使用uv来安装和运行。uv是一个用 Rust 编写的、极其快速的 Python 包管理器和项目运行器可以看作是pip、pipenv、virtualenv等工具的超集。用它来管理 MCP 服务器这类工具依赖能避免污染系统 Python 环境并且安装速度飞快。# 使用官方安装脚本安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启你的终端或者执行source ~/.bashrc(或source ~/.zshrc) 来让uv命令生效。你可以通过uv --version来验证安装。为什么选择 uv对于像mcpdoc这样可能被全局安装和频繁调用的工具uv的uvx命令特别方便。uvx可以直接从网络如 PyPI下载并运行一个 Python 工具包而无需先进行pip install。它会在后台自动管理隔离的虚拟环境和依赖对用户完全透明。这比用系统pip安装要干净和安全得多。3.2 选择并验证你的 llms.txt 源在启动服务器前你需要决定让mcpdoc加载哪些文档。这里以 LangGraph 和 LangChain 的官方文档为例它们都是高质量、持续更新的源。你可以直接在浏览器中打开这些链接查看llms.txt的内容感受一下它是什么LangGraph Python: https://langchain-ai.github.io/langgraph/llms.txtLangChain Python: https://python.langchain.com/llms.txt你会看到它们就是一系列 Markdown 文件的 URL 列表。这些就是mcpdoc将要建立索引并允许查询的文档范围。3.3 本地测试运行 mcpdoc 服务器在将其配置到 IDE 之前强烈建议先在本地独立运行和测试服务器确保一切正常。# 使用 uvx 运行 mcpdoc指定两个 llms.txt 源并使用 SSE 传输在本地端口 8082 启动 uvx --from mcpdoc mcpdoc \ --urls LangGraph:https://langchain-ai.github.io/langgraph/llms.txt \ --urls LangChain:https://python.langchain.com/llms.txt \ --transport sse \ --port 8082 \ --host localhost参数拆解与注意事项uvx --from mcpdoc mcpdoc: 使用uvx从 PyPI 的mcpdoc包中运行名为mcpdoc的命令。--urls “Name:URL”: 这是指定源的主要方式。你可以为每个源起一个别名如 “LangGraph”方便在工具调用列表中识别。别名是可选的但建议加上。--transport sse: 指定使用 Server-Sent Events 协议进行通信。这在独立测试时非常有用因为它允许我们通过 HTTP 访问服务器状态。--port 8082 --host localhost: 将服务器绑定到本地的 8082 端口。运行命令后如果成功终端会显示服务器已启动并监听在http://localhost:8082。访问这个地址你可能会看到一个简单的状态页或提示取决于 MCP 服务器的实现确认服务正在运行。保持这个终端窗口打开服务器会一直运行直到你按下CtrlC。3.4 使用 MCP Inspector 进行工具测试MCP Inspector 是一个官方提供的调试工具可以连接到任何 MCP 服务器并可视化地测试其提供的工具。这是验证mcpdoc是否正常工作、理解其工具调用方式的最佳途径。# 全局安装 MCP Inspector (需要 Node.js 环境) npx modelcontextprotocol/inspector运行后Inspector 通常会打开一个浏览器窗口或给出一个连接地址。在 Inspector 的界面中你需要输入刚才启动的mcpdoc服务器的 SSE 地址http://localhost:8082/sse注意SSE 端点通常是/sse。连接成功后你应该能在 Inspector 的 “Tools” 面板看到list_doc_sources和fetch_docs这两个工具。测试list_doc_sources点击调用它应该返回一个列表包含你刚才配置的两个源及其名称。测试fetch_docs调用fetch_docs工具。你需要从之前浏览过的llms.txt文件中复制一个具体的文档 URL例如LangGraph 内存管理相关的某个页面链接作为参数传入。如果一切正常工具会返回该 URL 对应的 Markdown 文档内容。通过 Inspector 的测试你不仅验证了服务器的功能性也直观地看到了 MCP 工具调用的请求和响应格式这对后续在 IDE 中编写调用规则Rules非常有帮助。4. 集成到主流 AI IDE配置详解与实战本地测试通过后就可以将它集成到你的日常开发环境中了。下面我将详细讲解在 Cursor、Windsurf、Claude Desktop 和 Claude Code 中的配置方法并分享一些关键的实操心得。4.1 集成到 Cursor打造专属的 LangGraph 专家助手Cursor 是目前对 MCP 支持最完善、体验最好的 IDE 之一。配置过程主要涉及两个文件MCP 服务器配置和全局规则。步骤一配置 MCP 服务器打开 Cursor进入Settings(快捷键Cmd,on Mac)。找到MCP标签页。点击后Cursor 会自动打开或创建MCP 配置文件~/.cursor/mcp.json。将以下配置粘贴到该文件中{ mcpServers: { langgraph-docs-mcp: { command: uvx, args: [ --from, mcpdoc, mcpdoc, --urls, LangGraph:https://langchain-ai.github.io/langgraph/llms.txt LangChain:https://python.langchain.com/llms.txt, --transport, stdio ] } } }配置解析与避坑点”langgraph-docs-mcp”: 这是你给这个服务器起的名字会在 Cursor 的工具列表中显示。”command”: “uvx”: 告诉 Cursor 使用uvx命令来启动服务器。”args”: 这里的参数和之前本地测试时几乎一样关键区别是--transport stdio。在 IDE 集成场景下通常使用stdio标准输入输出进行通信这比 SSE 更高效、更稳定。重要注意--urls参数后面两个源被合并成了一个字符串用空格分隔。这是 Cursor 配置的常见写法。确保整个字符串格式正确特别是 URL 没有多余或缺失的引号。保存文件后返回 Cursor Settings 的 MCP 标签页你应该能看到langgraph-docs-mcp服务器显示为已连接绿色或已加载状态。如果显示错误请检查终端是否有错误输出Cursor 可能会在后台尝试启动服务器并报错最常见的问题是uv未安装或不在 PATH 中。步骤二设置全局规则 (Rules)仅仅连接服务器还不够你需要告诉 Cursor 的 AI 代理“什么时候”以及“如何”使用这个服务器。这通过 Cursor 的Rules功能实现。在 Cursor Settings 中进入Rules标签页。在User Rules用户全局规则区域添加如下规则for ANY question about LangGraph, use the langgraph-docs-mcp server to help answer -- call list_doc_sources tool to get the available llms.txt file call fetch_docs tool to read it reflect on the urls in llms.txt reflect on the input question call fetch_docs on any urls relevant to the question use this to answer the question规则编写心法这条规则是一个简单的“提示工程”。它指示 AI 代理当遇到任何关于 LangGraph 的问题时应该走一个标准的检索流程。reflect指令是让 AI 在“内心”思考一下llms.txt里有哪些 URL用户的问题可能和哪些 URL 相关。这比直接让它“去查资料”更结构化成功率更高。步骤三实战测试在 Cursor 中用CmdL(Mac) 打开聊天面板。确保右下角选择了agent模式这是能使用工具的模式。输入测试问题what are types of memory in LangGraph?观察过程在聊天界面或右侧的工具调用面板你应该能看到 Cursor 依次调用list_doc_sources和多次fetch_docs的过程。最终它给出的答案应该非常精准并且引用了来自 LangGraph 官方文档的具体内容。实操心得规则需要迭代第一次写的规则可能不完美。如果发现 AI 没有正确调用工具或者调用顺序不对可以修改规则。例如如果问题涉及多个库你可以将规则扩展为for ANY question about LangGraph OR LangChain...。规则的本质是引导 AI 的工作流需要根据实际效果进行微调。4.2 集成到 WindsurfWindsurf原名 Codeium的配置流程与 Cursor 高度相似。配置 MCP 服务器在 Windsurf 中使用CmdL打开 Cascade 命令面板输入Configure MCP并执行这会打开配置文件~/.codeium/windsurf/mcp_config.json。将上述与 Cursor 相同的 JSON 配置粘贴进去。设置全局规则在 Windsurf Settings 中找到Rules / Global rules粘贴与 Cursor 相同的规则文本。测试同样在聊天框中提问关于 LangGraph 的问题观察工具调用和回答。4.3 集成到 Claude Desktop 与 Claude CodeAnthropic 官方的 Claude 应用也支持 MCP但配置方式和规则应用略有不同。Claude Desktop 配置打开 Claude Desktop 应用进入Settings-Developer页面。这里会显示配置文件路径~/Library/Application Support/Claude/claude_desktop_config.json(Mac) 或类似路径。编辑该文件添加mcpServers配置段内容与 Cursor 的配置一致。重启 Claude Desktop应用以使配置生效。Claude Desktop 规则应用的特殊性截至当前基于项目文档提示Claude Desktop 的图形界面可能不支持全局规则的直接配置。变通方法是在每次提问时将规则文本包裹在rules标签内并放在问题前面或后面。例如rules for ANY question about LangGraph, use the langgraph-docs-mcp server to help answer -- call list_doc_sources tool to get the available llms.txt file call fetch_docs tool to read it reflect on the urls in llms.txt reflect on the input question call fetch_docs on any urls relevant to the question /rules 我的问题是what are types of memory in LangGraph?Claude Code 配置Claude Code 是命令行工具配置更直接。在终端中执行以下命令将服务器配置添加到当前用户全局claude mcp add-json langgraph-docs {type:stdio,command:uvx ,args:[--from, mcpdoc, mcpdoc, --urls, langgraph:https://langchain-ai.github.io/langgraph/llms.txt, LangChain:https://python.langchain.com/llms.txt]} -s local这条命令会更新~/.claude.json配置文件。验证在终端启动 Claude Code (claude)然后输入/mcp命令应该能看到已配置的langgraph-docs服务器及其工具。规则应用与 Claude Desktop 类似目前可能需要在提问时手动附加rules标签。重要提示Python 版本兼容性问题如果你在 Claude Desktop/Code 中遇到uvx或 Python 环境问题可以在配置中显式指定 Python 解释器的路径。这是解决此类问题最有效的方法。{ mcpServers: { langgraph-docs-mcp: { command: uvx, args: [ --python, /usr/local/bin/python3, // 替换为你的 python 实际路径可通过 which python3 查看 --from, mcpdoc, mcpdoc, --urls, LangGraph:https://langchain-ai.github.io/langgraph/llms.txt, --transport, stdio ] } } }5. 高级配置与管理灵活运用 mcpdoc除了基本的命令行运行mcpdoc提供了更灵活、更适合生产环境的配置方式。5.1 使用配置文件管理文档源当你的文档源很多或者需要团队共享配置时使用 YAML 或 JSON 配置文件是更佳选择。项目仓库中通常会有sample_config.yaml或sample_config.json示例。YAML 配置示例 (my_docs_config.yaml):- name: LangGraph 核心指南 llms_txt: https://langchain-ai.github.io/langgraph/llms.txt - name: LangChain Python 全文档 llms_txt: https://python.langchain.com/llms.txt - name: 内部项目文档 llms_txt: file:///Users/yourname/docs/internal-llms.txt # 支持本地文件JSON 配置示例 (my_docs_config.json):[ { name: LangGraph 核心指南, llms_txt: https://langchain-ai.github.io/langgraph/llms.txt }, { name: LangChain Python 全文档, llms_txt: https://python.langchain.com/llms.txt } ]使用配置文件启动服务器# 使用 YAML 配置 mcpdoc --yaml my_docs_config.yaml --transport stdio # 使用 JSON 配置 mcpdoc --json my_docs_config.json --transport stdio混合使用配置文件和命令行参数你可以组合多种方式这对于在基础配置上临时添加一两个源非常方便。mcpdoc --yaml base_config.yaml --urls “临时API文档:https://api.example.com/v2/llms.txt”5.2 关键命令行参数解析--follow-redirects: 默认情况下HTTP 请求不跟随重定向。如果您的llms.txt或文档 URL 发生了重定向如 HTTP 到 HTTPS需要启用此选项。建议在配置未知源时先开启确认最终地址后再决定是否关闭。--timeout SECONDS: 设置 HTTP 请求超时时间默认为 10 秒。如果文档服务器响应慢或者网络状况不佳可以适当调高此值如--timeout 30。--allowed-domains: 这是安全核心参数。--allowed-domains “*.example.com” “api.github.com”: 允许example.com的所有子域和api.github.com。--allowed-domains “*”:允许所有域名。仅在你完全信任所有llms.txt内的链接且仅在安全隔离环境中测试时使用。一个包含所有可选参数的完整示例uvx --from mcpdoc mcpdoc \ --json my_config.json \ --follow-redirects \ --timeout 20 \ --allowed-domains “langchain-ai.github.io” “python.langchain.com” \ --transport stdio5.3 以编程方式使用 mcpdoc如果你是 Python 开发者或者希望将mcpdoc的功能集成到自己的自动化脚本或应用中可以直接调用其 Python API。from mcpdoc.main import create_server import asyncio async def main(): # 1. 创建服务器实例 server create_server( sources[ { name: My Custom Docs, llms_txt: https://my-domain.com/docs/llms.txt, } ], follow_redirectsTrue, timeout15.0, allowed_domains[my-domain.com, trusted-cdn.com] # 编程方式设置白名单 ) # 2. 运行服务器例如集成到 FastAPI 等异步框架中 # 这里以 stdio 模式为例实际上你可以适配不同的传输层 async with server.run(transportstdio) as client: # 此时服务器已启动并等待客户端连接 # 你可以在这里执行其他逻辑或者只是保持运行 await asyncio.Future() # 永久运行直到被中断 if __name__ __main__: asyncio.run(main())这种方式给予了最大的灵活性你可以基于mcpdoc的核心功能构建更复杂的文档检索服务例如添加缓存层、权限验证、或者将多个llms.txt源合并处理后提供统一的工具接口。6. 常见问题、排查技巧与最佳实践实录在实际部署和使用mcpdoc的过程中你可能会遇到一些问题。下面是我总结的一些常见坑点及其解决方案。6.1 服务器启动失败与连接问题问题现象可能原因排查步骤与解决方案运行uvx命令报错提示命令未找到或安装失败。1.uv未正确安装或未加入 PATH。2. 网络问题导致uvx无法从 PyPI 下载mcpdoc。1. 在终端执行which uv确认安装。重新执行安装脚本或手动添加 PATH。2. 尝试使用pip install mcpdoc全局安装然后在命令中直接使用mcpdoc而非uvx --from mcpdoc mcpdoc。Cursor/Windsurf 的 MCP 配置显示服务器连接失败红色或错误状态。1. 配置文件 JSON 格式错误。2.uvx或mcpdoc命令在 IDE 的上下文中执行失败如环境变量不同。3.--transport stdio参数缺失或错误。1. 使用 JSON 校验工具检查~/.cursor/mcp.json等文件格式。2. 在终端中手动执行配置中的完整命令如uvx --from mcpdoc mcpdoc --urls ... --transport stdio看是否报错。根据错误信息解决通常是 Python 依赖或网络问题。3.确保在 IDE 配置中使用--transport stdioSSE 通常仅用于本地测试。MCP Inspector 无法连接到http://localhost:8082/sse。1. 本地测试的mcpdoc服务器未启动。2. 端口被占用或--host参数不对。3. Inspector 连接地址错误。1. 确认运行mcpdoc的终端未关闭且无报错。2. 尝试更换端口如--port 8083。3. 确认连接地址是http://localhost:端口号/sse。有些 MCP 服务器根路径可能就是 SSE 端点可以试试http://localhost:8082/。6.2 工具调用无响应或返回空内容问题现象可能原因排查步骤与解决方案在 IDE 中提问后AI 没有调用任何工具直接回答了可能不准确。1.规则 (Rules) 未生效或未正确编写。这是最常见的原因。2. AI 代理Agent模式未开启。1.仔细检查规则语法确保规则指向的服务器名称与配置中的mcpServerskey 完全一致如langgraph-docs-mcp。规则描述要清晰如for ANY question about LangGraph。2. 在 Cursor/Windsurf 中确认聊天面板右下角选择了agent模式而不是composer模式。工具被调用了能看到调用记录但fetch_docs返回错误或空内容。1.域名不在白名单内。2. 目标 URL 无法访问404超时等。3.llms.txt文件格式不正确。1.重点检查如果使用本地llms.txt文件必须通过--allowed-domains添加域名。使用 MCP Inspector 测试时传入完整 URL 看具体错误信息。2. 手动在浏览器中打开fetch_docs尝试调用的那个具体文档 URL确认可访问。3. 检查llms.txt文件确保其内容是纯文本每行一个有效的 URL。Claude Desktop/Code 中工具需要手动批准无法自动调用。这是 Claude 应用当前的安全策略。工具调用需要用户手动点击“批准”。目前没有自动批准的设置。这虽然降低了效率但提高了安全性。在提问时注意观察界面右下角的工具调用提示及时点击批准。6.3 性能优化与最佳实践为不同的项目配置不同的服务器不要把所有文档源都塞进一个mcpdoc配置。例如你可以创建一个langgraph-mcp专门服务 LangGraph 问题另一个internal-api-mcp服务内部 API 文档。这样规则可以写得更精准AI 也不会在无关的工具列表中困惑。使用本地缓存的llms.txt对于内部文档或访问速度慢的源可以将llms.txt文件下载到本地然后使用file://协议指定路径。这可以加快服务器启动速度并避免因网络问题导致源加载失败。mcpdoc --urls “内部文档:file:///path/to/local/llms.txt” --allowed-domains “internal.company.com”编写更精确的规则基础的规则可能对复杂问题效果不佳。你可以编写更细致的规则例如If the user asks about “memory”, “state”, or “persistence” in the context of LangGraph, then: 1. Use the langgraph-docs-mcp server. 2. First, call list_doc_sources. 3. Then, fetch the llms.txt and look for URLs containing “memory” or “state”. 4. Fetch those specific docs and use them to answer.定期更新llms.txt源官方文档会更新llms.txt内容也会变。定期检查你配置的源是否仍然有效或者是否有新的、更全面的llms.txt文件发布。结合 IDE 项目级配置除了全局配置一些 IDE如 Cursor也支持项目级的.cursor/mcp.json配置。你可以在项目根目录放置此文件定义只与此项目相关的文档源如该项目特定依赖库的文档实现更精细化的管理。通过mcpdoc你将文档检索的模糊地带变成了一个清晰、可控、可审计的管道。它不仅仅是连接了一个文档源更是为你与 AI 助手之间的协作引入了一种可预测、可调试的新范式。当你下次再疑惑“为什么 AI 会给出这个答案”时你可以打开工具调用记录像查看日志一样追溯它的“思考”过程这种掌控感对于进行严肃开发的工程师来说是无价的。