Harmony-Fetch

Fetch HarmonyOS developer documentation from Huawei's official portal, via either the official HarmonyOS Knowledge MCP service (preferred) or public REST APIs with a local script.

When to Use

• ArkTS/ArkUI/ArkData API details not covered by local skills (arkts-helper, arkts-build, etc.)
• HarmonyOS NEXT feature documentation lookup
• DevEco Studio IDE, build tools, or command-line tools reference
• User asks "check Huawei docs" or references developer.huawei.com links
• Need to verify current API signatures, deprecated features, or new capabilities

Do not force this skill onto tasks the local offline docs already answer — see the coverage table and boundary below.

Boundary with Other Skills

This skill covers "fetching current official documentation online", not "answering from offline docs" or "writing/fixing code":

Local Documentation Coverage

Before calling the online API, check whether the following local skills already cover the needed content. Only use this skill to fetch online documentation when local docs are insufficient.

Decision flow: user question → check the corresponding skill's offline docs first → if docs are insufficient → use this skill to fetch from the Huawei developer portal.

Workflow (Follow Strictly)

Two retrieval paths are supported. Choose based on whether the AI client has the MCP service connected:

• Preferred - MCP service: If the client exposes HarmonyOS Knowledge MCP tools (tool-name prefix mcp__harmonyos_developer_knowledge__), call them directly. No script execution, no Windows encoding concerns, content stays in sync with the official site (delay <= 30 min).
• Fallback - local script + REST API: If the MCP service is not connected, use scripts/fetch_doc.py to call Huawei's documentPortal REST API.

Step 1: Use the MCP Service (Preferred)

MCP configuration

Add the following remote-server configuration to any MCP-capable AI client (e.g. DevEco Studio, ZCode):

{
  "mcpServers": {
    "harmonyos_developer_knowledge": {
      "url": "https://connect-api.cloud.huawei.com/api/developerknowledge/mcp",
      "type": "http"
    }
  }
}

Configuration paths differ across clients - refer to each client's MCP configuration documentation.

Tool call flow

Always search first; never hand-craft document identifiers.

1. Search - call searchDocuments with a non-empty query (搜索词). It returns resultList, where each entry contains exactly two fields: parent (document identifier) and content (matched text fragment). No title or uri is returned - judge relevance by the fragment text and the slug inside parent.

2. Fetch full content (if needed) - only if the fragments are too brief to answer the question, pass the relevant parent values verbatim as the names array of getDocumentsById (up to 10 per call). It returns complete Markdown documents with name, title, uri, and content.

searchDocuments(query="ArkTS 状态管理")
  -> resultList[0].parent = "document/cn/harmonyos-references/js-apis-statemanagement"

getDocumentsById(names=["document/cn/harmonyos-guides/arkts-state-management-overview"])
  -> resultList[0].title    = "状态管理概述"
     resultList[0].content  = "# 状态管理概述\n\n..."   (full Markdown)

Parameter definitions, verified response shapes, and calling rules: see MCP Service Reference.

Verify MCP availability

To confirm the service is reachable and inspect the current tool specifications, run the following curl outside the client:

curl --location 'https://connect-api.cloud.huawei.com/api/developerknowledge/mcp' \
     --header 'content-type: application/json' \
     --header 'accept: application/json, text/event-stream' \
     --data '{
          "method": "tools/list",
          "jsonrpc": "2.0",
          "id": 1
     }'

For the full MCP service reference (endpoint, tools, corpus scope, sync latency), see MCP Service Reference below.

Step 2: Use the Local Script (Fallback when MCP is unavailable)

Use this path only when the MCP service is not connected to the current client. Two-step workflow: Search -> Fetch.

Windows note: the examples below use python3; on Windows the interpreter is usually python (the python3 alias may be a non-functional Store stub). Use whichever python/py exists on the target machine.

Option A - User provides a URL: Parse the URL to extract the document slug.

URL pattern: https://developer.huawei.com/consumer/cn/doc/<catalog>-<version>/<slug>-<version>

Extract slug (without version suffix) as the objectId.

Option B - Browse catalog tree: Run the fetch script with --catalog to list sections:

python3 scripts/fetch_doc.py --catalog harmonyos-guides

Option C - Web search: Use WebSearch tool with site:developer.huawei.com/consumer/cn/doc/ <keywords> to find relevant doc URLs, then extract slugs from results.

Then fetch the document content:

python3 scripts/fetch_doc.py <objectId>

Where objectId is the document slug (e.g., arkts-state-management-overview).

Output is markdown-converted content. For raw HTML, add --html flag.

MCP Service Reference

The HarmonyOS Developer Knowledge MCP service (鸿蒙开发者知识MCP服务) is a remote MCP server based on the standard Model Context Protocol, providing real-time retrieval and full-text fetching of HarmonyOS official developer docs. Upstream doc: https://developer.huawei.com/consumer/cn/doc/start/hosknowledgemcp-0000002664603963

Client configuration

{
  "mcpServers": {
    "harmonyos_developer_knowledge": {
      "url": "https://connect-api.cloud.huawei.com/api/developerknowledge/mcp",
      "type": "http"
    }
  }
}

After adding the server, the client exposes two tools (exact name prefix depends on the client, e.g. mcp__harmonyos_developer_knowledge__searchDocuments and mcp__harmonyos_developer_knowledge__getDocumentsById).

Tool specification

The authoritative machine-readable specs come from the JSON-RPC tools/list method (verify availability). The tables below summarize them together with behavior verified against the live service (2026-08-27).

searchDocuments

Searches all HarmonyOS official docs (版本说明、API参考、开发指南、最佳实践、行业实践、FAQ、IDE指南、UX设计、应用上架、应用分发). Returns matched text chunks, not whole documents.

Input parameters:

Success response:

Verified sample (abbreviated):

{
  "code": 0,
  "message": "success",
  "resultList": [
    {
      "parent": "document/cn/harmonyos-references/js-apis-statemanagement",
      "content": "状态管理模块具备应用数据存储、持久化管理以及UIAbility..."
    }
  ]
}

Note: search results carry no title or uri. Pick relevant entries by reading the content snippet and the slug inside parent.

Note (direct JSON-RPC callers): although inputSchema declares the request wrapped under SearchDocumentsReq, the gateway actually requires flat arguments - {"query": "..."} at the top level of arguments. A nested payload reaches the gateway as a blank query and fails with code 99900001 (verified). MCP clients handle this wrapping internally; only raw tools/call requests need care. Note (WorkBuddy clients, verified 2026-09-09): WorkBuddy 的延迟加载 MCP 工具（mcp__harmonyos_developer_knowledge__searchDocuments / getDocumentsById）把嵌套 wrapper 暴露为真实参数 schema —— 必须按 {"SearchDocumentsReq": {"query": "..."}} / {"GetDocumentsByIdRequest": {"names": [...]}} 嵌套结构传参，平铺的顶层参数会被参数校验直接拒绝。调用前以 ToolSearch 返回的 schema 为准。

getDocumentsById

Fetches complete documents by identifier. One call retrieves one document or up to 10.

Input parameters:

Success response:

Notes:

• The identifier mirrors the portal URL: for https://developer.huawei.com/consumer/{lang}/doc/{catalog}/{slug} the equivalent identifier is document/{lang}/{catalog}/{slug} (e.g. URL path harmonyos-guides/arkts-state-management-overview → document/cn/harmonyos-guides/arkts-state-management-overview; verified on guides/references pages). This mapping is handy when the user pastes a portal link and only the body text is needed - otherwise always prefer identifiers from searchDocuments.
• Bare slugs identify the latest version. Historical-version pages (-V5 suffix etc.) are not targeted through this tool; use the local script path for those.
• Inline images appear as reference links inside content rather than directly viewable URLs; open the page via uri when the figure itself matters.

Calling conventions

Apply these rules to every MCP call, in order:

1. Local skills first - before any online fetch, confirm the local offline docs listed above do not already answer the question.
2. Search before you fetch - always run searchDocuments first; only escalate to getDocumentsById when the fragments cannot answer the question. This is the two-step flow prescribed by the official doc.
3. Never fabricate identifiers - every names[] entry must be copied from a previous searchDocuments result. Do not guess slugs, reuse remembered IDs across sessions without re-searching, or assemble them from URLs unless applying the verified URL→identifier mapping above.
4. Respect the batch limit - max 10 identifiers per getDocumentsById call; split into multiple calls beyond that.
5. Fetch selectively - request full content only for entries whose snippet is relevant to the question, not the entire result list.
6. Write queries well - the corpus is Chinese-first: prefer Chinese feature terms (「状态管理」,「转场动画」) or exact API/decorator names (@ObservedV2, LazyForEach). If a query returns nothing relevant, retry with different keywords or a narrower phrase instead of giving up.
7. Mind versions - identifiers without a version suffix resolve to the latest published docs (sync delay <= 30 min). For a specific historical version, fall back to the local script with its -V5-style slug.
8. Quote sources - when answering with fetched content, cite the page URL built from the result's uri (or document/... identifier) so the user can verify against the official site.

Errors

Gateway errors surface as {"code": 99900001, "message": "..."} in the structured response (structuredContent, mirrored as JSON text inside content[0].text). Verified cases:

API Reference

Catalog Tree API (no auth required)

POST https://developer.huawei.com/consumer/cn/documentPortal/getCatalogTree
Content-Type: application/json

{
  "catalogName": "harmonyos-guides",
  "language": "cn",
  "showHide": 0
}

Parameters:

• catalogName: catalog identifier (see catalog reference)
• language: "cn" | "en" | "ru"
• showHide: 0 (show all) | 1 (show hidden) | 2 (hide)

Returns a tree where each node has:

• nodeId: unique identifier
• nodeName: display title (Chinese)
• relateDocument: the slug used as objectId (leaf nodes only)
• isLeaf: whether it's a document page
• children: child nodes

Document Content API (no auth required)

POST https://developer.huawei.com/consumer/cn/documentPortal/getDocumentById
Content-Type: application/json

{
  "language": "cn",
  "objectId": "arkts-state-management-overview"
}

Returns:

• value.docId: internal ID
• value.title: document title
• value.version: document version (e.g., V85, V219)
• value.content.content: full HTML content
• value.anchorList: heading anchors with hierarchy
• value.businessName: product name (HarmonyOS)

objectId rules:

• Use the bare slug (no version suffix) for the latest version
• Append -V5 for the HarmonyOS NEXT DP1 version specifically
• Both forms work; prefer bare slug unless user asks for a specific version

Search (requires auth — use WebSearch instead)

The official search API requires login tokens. Always use WebSearch with site filter:

site:developer.huawei.com/consumer/cn/doc/ ArkTS Navigation

Catalog Quick Reference

Primary catalogs for HarmonyOS app development:

For full catalog list and doc tree structure, see doc-structure.md.

URL Parsing Examples

Error Handling

• "document not found" → objectId slug is wrong; try browsing the catalog tree
• "主仓不存在" → the center API catalog doesn't exist; use the standard API
• Empty response → network issue or rate limiting; retry after a short wait Garbled Chinese text or UnicodeEncodeError → Windows terminal uses GBK encoding by default; the script includes an automatic UTF-8 fix in main(). If it still fails, use the import mode described in Windows Environment Notes.

Pitfalls

• The documentation site is an Angular SPA - direct WebFetch on page URLs returns empty shells. Always use the MCP tools or the REST API endpoints, never try to scrape the HTML page directly.
• MCP tool names are client-specific: the prefix differs across clients (e.g. mcp__harmonyos_developer_knowledge__searchDocuments in ZCode). Call the tool by whatever name the client actually exposes.
• getDocumentsById accepts at most 10 document identifiers per call; batch the calls if more are needed.
• The parent field returned by MCP searchDocuments is the document's unique identifier - pass it directly as the names array element to getDocumentsById.
• searchDocuments results carry only parent and content - no title/URI. Estimate relevance from the fragment text and the slug inside parent; titles arrive only from getDocumentsById.
• For raw JSON-RPC tools/call requests against the MCP endpoint, send flat arguments (e.g. {"query": "..."} / {"names": [...]}). Despite inputSchema showing nested request wrappers (SearchDocumentsReq, GetDocumentsByIdRequest), a nested payload reaches the gateway as a blank parameter (99900001).
• Search APIs (REST) require authentication cookies. Use WebSearch with site: filter, or the MCP searchDocuments tool, as the search alternative.
• Image URLs in document content are CDN-hosted with time-limited signatures; they expire after 24 hours.
• The -V5 suffix on catalog names and document slugs refers to a specific version; the bare name fetches the latest version.

Windows Environment Notes

Windows terminals default to GBK encoding (CP936). Running fetch_doc.py directly may produce garbled Chinese output or throw a UnicodeEncodeError when encountering special Unicode characters (e.g., U+200C zero-width non-joiner). The script includes an automatic fix via sys.stdout.reconfigure(encoding='utf-8') in main(), but if issues persist (e.g., in certain terminal emulators or piped environments), use the Python import mode:

import sys, os
sys.path.insert(0, r'<skill-dir>/scripts')
from fetch_doc import fetch_document, html_to_markdown

result = fetch_document('some-doc-slug')
value = result.get('value', {})
title = value.get('title', 'Untitled')
html = value.get('content', {}).get('content', '')
md = html_to_markdown(html)

with open('output.md', 'w', encoding='utf-8') as f:
    f.write(f'# {title}\n\n{md}')

This bypasses terminal encoding issues by writing directly to a UTF-8 file, making it the most reliable approach on Windows. This mode is also recommended for batch-fetching multiple documents.