跳至主要內容

用 QwenPaw 配置 MCP 玩转 LLMs 编程：agentscope-docs2 实战指南

Keep Simple2026/8/20大约 7 分钟qwenpawqwenpawmcpllms

用 QwenPaw 配置 MCP 玩转 LLMs 编程：agentscope-docs2 实战指南

发布日期： 2026-08-20
适用版本： QwenPaw 2.1.0 + uv 0.11.x + mcpdoc 0.0.10
测试平台： Windows 11（Windows / macOS / Linux 通用）

目录

  1. 什么是 LLMs 编程？
  2. 为什么用 MCP 而不是直接翻网页？
  3. 认识 mcpdoc 与 agentscope-docs2
  4. 前置准备
  5. 在 QwenPaw 中配置 agentscope-docs2
  6. 使用效果实测
  7. 进阶：多文档源与配置化
  8. 踩坑记录：mcp 2.0 兼容性事故
  9. 总结

1. 什么是 LLMs 编程？

llms.txt 是 2025 年提出的一项开放标准（llmstxt.org），它让网站为「大语言模型」提供一个精简的纯文本索引文件，类似 robots.txt 之于搜索引擎、sitemap.xml 之于爬虫。

一个典型的 llms.txt 长这样（这是 AgentScope Java v2 文档站的真实内容）：

# AgentScope Java v2
> AgentScope Java 2.0 documentation for new projects and production agent engineering with HarnessAgent.

## Docs
- [What's AgentScope 2.0?](https://java.agentscope.io/_sources/v2/en/docs/index.md): Harness engineering...
- [Quickstart](https://java.agentscope.io/_sources/v2/en/docs/quickstart.md): Get started with AgentScope Java 2.0...
- [Model](https://java.agentscope.io/_sources/v2/en/docs/building-blocks/model.md): Configure LLM providers...
...

LLMs 编程 就是把这类 llms.txt 文档库交给 AI 编程智能体（Claude Code、Cursor、Windsurf、QwenPaw 等）：智能体先读索引，按需拉取具体页面，从而带着最新、最准确的官方文档写代码，而不是靠训练数据里的旧记忆「猜 API」。

2. 为什么用 MCP 而不是直接翻网页？

  • 省 token：llms.txt 是索引，只有几 KB；具体页面按需 fetch_docs 才拉，不会把整个文档站灌进上下文
  • 准确：文档是实时从官方站抓的，不依赖模型训练时的知识截止点
  • 可审计：每次智能体调用哪个文档、读了多少内容，MCP 层都看得见，可以加权限策略
  • 统一入口：多个项目的文档可以挂到一个 MCP 服务下，一套配置全局生效

3. 认识 mcpdoc 与 agentscope-docs2

mcpdoc 是 LangChain 团队开源的 MCP Server（github.com/langchain-ai/mcpdoc），专做「把 llms.txt 暴露给 IDE / 智能体」这件事：

  • 注册一个或多个 llms.txt 源（名称:URL 形式）
  • 对外暴露两个工具：
    • list_doc_sources — 列出所有已注册的文档源
    • fetch_docs — 按 URL 拉取文档内容（仅限已注册源内的 URL，天然做域名白名单）
  • 支持 stdio / SSE 两种传输方式

agentscope-docs2 就是我们在 QwenPaw 里创建的、指向 https://java.agentscope.io/v2/llms.txt（AgentScope Java v2 官方文档）的 mcpdoc 实例。配置后 QwenPaw 智能体会自动获得上面两个 MCP 工具（工具名前缀为 agentscope-docs2__）。

4. 前置准备

QwenPaw 文档要求本地 stdio MCP 服务至少满足：

  • uv（含 uvx）：mcpdoc 通过 uvx --from mcpdoc mcpdoc 即用即装，不污染全局 Python 环境
uvx --version
# uvx 0.11.6 (...)

远程 MCP（streamable_http / sse）不需要本地依赖；本文演示的是本地 stdio 方案，这也是绝大多数文档类 MCP 的用法。

5. 在 QwenPaw 中配置 agentscope-docs2

方式一：控制台 GUI（推荐）

  1. 打开 QwenPaw 控制台，进入 智能体 → MCP
  2. 点击 + 创建
  3. 粘贴以下 JSON（标准 mcpServers 格式）：
  4. 点击 创建，完成导入
{
  "mcpServers": {
    "agentscope-docs2": {
      "command": "uvx",
      "args": [
        "--from", "mcpdoc",
        "--with", "mcp[cli]<2",
        "mcpdoc",
        "--urls", "AgentScopeJava:https://java.agentscope.io/v2/llms.txt"
      ],
      "env": {}
    }
  }
}

注意 --with "mcp[cli]<2" 这一节：这是 2026-08 之后必须加的防雷参数，原因见第 8 节。若你的 mcpdoc 已发新版适配了 mcp 2.0，可去掉。

QwenPaw 支持三种 JSON 格式（标准 mcpServers 包装 / 直接键值对 / 单客户端对象），任选其一即可；也支持一次导入多个客户端。

方式二：直接写配置文件

创建后，配置会落到当前智能体工作区的 drivers/mcp/agentscope-docs.yaml（YAML 驱动格式，含权限策略）：

name: agentscope-docs        # MCP client key
protocol: mcp
endpoint:
  transport: stdio
  command: uvx
  args:
  - --from
  - mcpdoc
  - --with
  - mcp[cli]<2
  - mcpdoc
  - --urls
  - AgentScopeJava:https://java.agentscope.io/v2/llms.txt
  env: {}
credentials: {}
config:
  display_name: agentscope-docs2   # 会话里显示的名字
  description: ''
  tools: null
enabled: true
policy:
  default_effect: ask              # 默认询问
  rules: []
  • 想改文档源 URL / 加更多源，直接改这个文件的 args 即可
  • policy 可以细化权限：例如只放行 fetch_docs、list_doc_sources 两个工具，其余一律 deny，未授权工具走 ask 人工确认

配置字段速查（QwenPaw MCP）

字段类型默认值说明
namestring-客户端名称（必填）
commandstring""stdio 启动命令（如 uvx、npx）
argsstring[][]启动参数
envobject{}运行时环境变量（如 API Key）
transportstring"stdio"stdio / streamable_http / sse，通常自动识别
urlstring""远程服务地址（http/sse 必填）
headersobject{}HTTP 请求头（用于认证）
cwdstring""工作目录
enabledbooltrue是否启用

6. 使用效果实测

配置完成、重启 QwenPaw 会话后，智能体的工具列表里会出现两个 MCP 工具。实测效果：

① 列出文档源

调用 agentscope-docs2__list_doc_sources：

AgentScopeJava
URL: https://java.agentscope.io/v2/llms.txt

② 拉取文档

调用 agentscope-docs2__fetch_docs（传入 llms.txt 内的具体页面 URL），智能体就能拿到最新版官方文档全文，例如 AgentScope Java 2.0 的 Quickstart、Harness 架构、Model 接入、MySQL State Store 等上百个页面，全部按需可读。

典型工作流：在 QwenPaw 里问「AgentScope Java 怎么配 Kimi 模型」→ 智能体自动 fetch_docs 拉 integration/model/kimi.md → 基于官方文档给出准确配置代码。不再依赖模型的记忆，也不再需要手动去翻文档站。

7. 进阶：多文档源与配置化

多文档源一网打尽

--urls 可以传多个，一次挂多个项目的文档：

{
  "mcpServers": {
    "my-docs": {
      "command": "uvx",
      "args": [
        "--from", "mcpdoc", "--with", "mcp[cli]<2",
        "mcpdoc",
        "--urls",
        "AgentScopeJava:https://java.agentscope.io/v2/llms.txt",
        "LangGraph:https://langchain-ai.github.io/langgraph/llms.txt",
        "LangChain:https://docs.langchain.com/llms.txt"
      ]
    }
  }
}

配置文件模式（团队共享）

llms.txt 源多了以后，用 JSON/YAML 配置管理更清晰：

{
  "docs": [
    { "name": "AgentScopeJava", "url": "https://java.agentscope.io/v2/llms.txt" },
    { "name": "LangGraph", "url": "https://langchain-ai.github.io/langgraph/llms.txt" }
  ]
}
uvx --from mcpdoc --with "mcp[cli]<2" mcpdoc --json sample_config.json

其他有用参数

参数作用
--allowed-domains 'a.com' 'b.com'允许额外拉取指定域名的文档（默认只允许已注册源所在域名）
--allowed-domains '*'放行任意域名（谨慎）
--transport sse --host 127.0.0.1 --port 8000以 SSE 方式启动，供浏览器 / 多客户端共享
--timeout 15自定义 HTTP 超时（默认 10s）

8. 踩坑记录：mcp 2.0 兼容性事故

现象：某天 agentscope-docs2 突然启动失败，报：

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

根因（排查链）：

  1. uvx --from mcpdoc mcpdoc --help 直接复现崩溃，拿到 Python traceback
  2. 检查 uv 缓存环境：装的竟是 mcp 2.0.0（当天刚发布）
  3. 查 PyPI：mcpdoc 0.0.10 依赖声明 mcp[cli]>=1.4.1，没有版本上界
  4. 结论：mcp SDK 2.0 是 major breaking 版本，移除了 mcp.server.fastmcp（FastMCP 独立成包），mcpdoc 尚未适配。依赖「无上界 + 上游发 major」的经典事故链。

修复：给 uvx 加约束，强制解析回 1.x：

uvx --from mcpdoc --with "mcp[cli]<2" mcpdoc --urls AgentScopeJava:https://java.agentscope.io/v2/llms.txt

验证：

  • uvx --from mcpdoc --with "mcp[cli]<2" mcpdoc --help 正常输出 → 修复生效
  • 在 Claude Code 里 claude mcp list 显示 agentscope-docs ✔ Connected

给同类工具的经验：

  • 依赖声明带 >= 无上界、且用 uvx 即用即装的 MCP，都是这种事故的高发区
  • 排查口诀：先手动跑 --help 看 traceback → 查 uv 缓存环境的 dist-info 版本 → 对比 PyPI requires_dist，三步锁定「上游发 major 破坏」
  • 打补丁用 uvx --with "pkg<x.y"，比改代码等上游适配快得多

9. 总结

环节关键点
标准llms.txt 让文档站为 LLM 提供索引，是 LLMs 编程的基础
工具mcpdoc（LangChain 开源）负责把 llms.txt 暴露成 list_doc_sources + fetch_docs
配置QwenPaw 控制台 智能体 → MCP → + 创建 粘贴 JSON，5 秒完成
落地配置落在 drivers/mcp/*.yaml，含权限策略，可精细管控
效果智能体按需拉最新官方文档编程，省 token、准确、可审计
防雷务必带 --with "mcp[cli]<2"，直到 mcpdoc 适配 mcp 2.0

配好之后，你的 QwenPaw / Claude Code / Cursor 就都拥有了「带着官方文档写代码」的能力。把这条配置复制到任意工作区，你就获得了一套可复用的 LLMs 编程基础设施。

相关阅读：

✨ 保持简单，专注创造 ✨
Copyright © 2026 Keep Simple