@opencxd/ascend-doc-mcp

配置驱动的昇腾社区文档查询 MCP 服务器。

安装与运行

# 直接使用（npx 自动拉取最新版）
npx @opencxd/ascend-doc-mcp

# 或全局安装
pnpm install -g @opencxd/ascend-doc-mcp

CLI 参数

所有启动参数通过 CLI 传入（跨平台通用，无需设置环境变量）：

| 参数 | 说明 | 默认值 | | ------------------ | ------------- | --------- | ----- | | --transport=stdio | http | 传输模式 | stdio | | --port=3200 | HTTP 端口 | 3200 | | --host=127.0.0.1 | HTTP 监听地址 | 127.0.0.1 |

环境变量 TRANSPORT_MODE、MCP_PORT、MCP_HOST 作为向后兼容 fallback。

社区标识固定为 ascend（昇腾社区）。

传输模式

支持两种传输模式：stdio（默认）和 StreamableHTTP（远程服务）。

| 模式 | 适用场景 | 启动方式 | | -------------- | ---------------------------------------------- | ------------------ | | stdio | 本地 CLI / IDE 集成（Claude Desktop、VS Code） | 默认，无需额外配置 | | StreamableHTTP | 远程服务 / 多客户端共享 / Claude Code url 配置 | --transport=http |

stdio 模式（默认）

# 启动 MCP 服务器
npx @opencxd/ascend-doc-mcp

调用工具时传 community 参数指定昇腾社区：

{ "community": "ascend", "product": "CANNCommunityEdition" }

HTTP 模式

# 启动 HTTP 服务器
npx @opencxd/ascend-doc-mcp --transport=http

AI 客户端配置示例

Claude Desktop — stdio 模式

claude_desktop_config.json：

{
  "mcpServers": {
    "ascend-doc": {
      "command": "npx",
      "args": ["-y", "@opencxd/ascend-doc-mcp"]
    }
  }
}

只需配置一个 MCP server，community 参数固定传 ascend。

Claude Code — HTTP url 模式

~/.claude/settings.json：

{
  "mcpServers": {
    "ascend-doc": { "url": "http://127.0.0.1:3200/mcp" }
  }
}

工具一览

16 个 MCP 工具，按优先级分三层。所有工具均需传 community 参数（ascend）。

P0 — 核心查询链

典型工作流：list_products → list_versions → get_doc_toc → get_doc_content

| 工具 | 说明 | | ----------------- | ------------------------------- | | list_products | 查询社区产品目录（按类别筛选） | | list_versions | 查询产品版本列表 | | get_doc_toc | 获取版本文档目录（章节树） | | get_doc_content | 获取文档页内容（HTML→Markdown） | | search_docs | 全站文档搜索 |

P1 — 深度查询

| 工具 | 说明 | | --------------------------- | -------------------------------------------------------------------------- | | browse_docs | 按面包屑路径浏览文档 | | check_compatibility | 硬件→软件兼容性矩阵 | | search_troubleshooting | 搜索故障案例（源文件路径 case/{caseId} 可传给 get_doc_content 获取正文） | | get_latest_version | 获取产品最新稳定版本 | | get_download_options | 获取软件包下载选项树 | | get_install_commands | 获取定制化安装命令 | | list_pdf_downloads | 获取 PDF 文档下载列表 | | get_version_announcements | 获取版本公告/文档动态 |

P2 — 辅助工具

| 工具 | 说明 | | ------------------------ | ---------------------- | | search_docs_in_product | 产品内文档搜索 | | get_doc_outline | 获取文档大纲（标题树） | | get_code_samples | 获取文档中的代码示例 |

降级机制

每个工具都有三层降级保障，确保不会因单一数据源故障而返回空结果：

1. 实时 API — 优先调用社区网关接口
2. 本地预设 — API 不可用时使用包内预设数据（产品别名、默认路径）
3. llms.txt / 空+指引 — 终极兜底：尝试读取站点 llms.txt，或返回 playwright-cli 调用指引

降级信息会标注数据来源与时效性（实时/本地/空），帮助模型判断结果可信度。

配置驱动架构

核心设计：通过 JSON 配置文件驱动工具行为。CommunityRegistry 持有昇腾社区的配置和预设，每次工具调用根据 community 参数动态解析。

configs/
  hiascend.json       # 昇腾社区配置
presets/
  ascend-aliases.json # 昇腾产品别名（模糊匹配）

配置结构

{
  "community": "ascend", // 社区标识
  "baseUrl": "https://www.hiascend.com", // 站点域名
  "gateway": "/ascendgateway/ascendservice", // 网关前缀
  "sourceBase": "/doc_center/source", // 源文件路径前缀
  "apiStyles": {
    // 接口风格差异
    "breadcrumbs": { "style": "query", "path": "/doc/single/page/breadcrumbs" },
    "versionAnnouncement": { "path": "/bulletins/front/nvod", "paramName": "bulletinsType", "bulletinType": 5 },
    "versionTree": { "style": "query", "path": "/doc/version/new/tree" },
  },
  "degradations": {
    // 降级策略
    "check_compatibility": null, // null = 不降级
    "popular_docs": "local_config", // 字符串 = 降级方式
  },
}

开发

# 构建
pnpm build

# 开发模式 — stdio（tsx 热运行）
pnpm dev

# 开发模式 — HTTP（默认端口 3200）
pnpm dev:http

# 生产运行 — HTTP
pnpm start:http

# 运行测试
pnpm test

# 测试覆盖率
pnpm test:coverage

# 监听模式
pnpm test:watch

技术栈

• Node.js ≥18（推荐≥24） / TypeScript / ESM
• @modelcontextprotocol/sdk — MCP 协议实现（stdio + StreamableHTTP 双传输）
• express + @hono/node-server — HTTP 传输层（StreamableHTTPServerTransport）
• zod — 参数校验与类型安全
• turndown — HTML→Markdown 转换
• vite — 构建 / vitest — 测试