harmonyos-best-practices-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # HarmonyOS 最佳实践 MCP 服务器
 
-把鸿蒙应用开发最佳实践资料(452 篇文档 + 186 个示例仓库)通过 MCP 暴露为检索工具,供 Claude Code / Cursor / Cline 等 MCP 客户端在开发时动态调用。
+把鸿蒙应用开发最佳实践资料通过 MCP 暴露为检索工具,供 Claude Code / Cursor / Cline 等 MCP 客户端在开发时动态调用。
 
 **文档(9MB)随包发布,装包即用、零配置。** 代码(8GB)不随包,按需配置本地路径(见下)。
 
@@ -10,7 +10,7 @@
 |------|------|
 | `search_best_practices({query, limit?})` | 全文检索文档(中文友好),返回相关度排序的文档列表(含主题、是否有代码、代码仓库名) |
 | `get_doc({name})` | 读取指定文档(docId)的完整 Markdown 正文 |
-| `get_code_example({docName})` | 返回文档关联的参考代码:本地仓库绝对路径、远程 URL、入口 `.ets/.ts` 文件 |
+| `get_code_example({docName})` | 返回文档关联的参考代码:本地仓库绝对路径、远程 URL、README 简介、入口 `.ets/.ts` 文件(带用途注释) |
 | `list_by_topic({topic?})` | 按大类浏览(稳定性/性能/媒体/功耗/一多…);省略参数返回所有大类及文档数 |
 
 ## 安装(最终用户)
@@ -18,10 +18,10 @@
 无需 clone 本仓库。直接用 npx 或全局安装:
 
 ```bash
-# 方式一:一次性运行(推荐)
-npx harmonyos-best-practices-mcp
+# 方式一:一次性运行(推荐,每次自动拉最新版)
+npx -y harmonyos-best-practices-mcp
 
-# 方式二:全局安装
+# 方式二:全局安装(需手动更新)
 npm install -g harmonyos-best-practices-mcp
 ```
 
@@ -90,6 +90,33 @@ Claude Code 配置加 env:
 | `BP_INDEX` | 包内 `data/index.md` | 索引文件(一般无需改) |
 | `BP_CODE_DIR` | 空 | 本地代码根目录;为空时 `get_code_example` 只给 URL |
 
+## 更新
+
+文档和服务器会持续更新(版本号见 `package.json`)。
+
+**更新服务器**:
+
+```bash
+# npx -y 方式:无需手动操作,每次启动自动拉最新版
+# 全局安装方式:手动更新
+npm update -g harmonyos-best-practices-mcp
+# 或锁定最新版
+npm install -g harmonyos-best-practices-mcp@latest
+```
+
+更新后**重启 AI 客户端**(Claude Code / Cursor / Cline 等),让新进程加载新版 MCP。
+
+**更新文档**:文档随包内置(`data/docs/`),更新 npm 包即同步更新 452 篇文档,无需单独操作。
+
+**更新代码包**(仅当启用了本地代码读取):GitHub Release 有新版 `harmonyos-best-practices-code.tar.gz` 时,重新下载解压覆盖 `BP_CODE_DIR` 指向的目录即可。
+
+**查看版本**:
+```bash
+npm view harmonyos-best-practices-mcp version   # 最新发布版
+npm ls -g harmonyos-best-practices-mcp          # 本地已装版本
+```
+或看客户端 MCP 面板里服务器的 `version` 字段。
+
 ## 开发与发布(维护者)
 
 ```bash

package/dist/data.js

@@ -67,6 +67,8 @@ function parseIndex(indexFile) {
                 subtitle: "",
                 codeRefs: [],
                 hasCode: false,
+                readmeDigest: "",
+                headings: "",
             };
             continue;
         }
@@ -134,6 +136,8 @@ function parseCrawlLog(docsDir, docs) {
                 subtitle,
                 codeRefs: [],
                 hasCode: false,
+                readmeDigest: "",
+                headings: "",
             });
         }
     }
@@ -158,9 +162,141 @@ export function getStore() {
         arr.push(meta.docId);
         topics.set(meta.topic, arr);
     }
+    // Preload a short README digest for each cloned repo, used for search scoring.
+    // Only read when codeDir is configured; otherwise leave empty (search still works on doc text).
+    if (codeDir) {
+        for (const meta of docs.values()) {
+            if (!meta.hasCode)
+                continue;
+            const digests = [];
+            for (const ref of meta.codeRefs) {
+                if (ref.status !== "cloned" || !ref.localPath)
+                    continue;
+                const repoAbs = resolveCodePath(codeDir, ref.localPath);
+                const intro = readReadmeIntro(repoAbs);
+                if (intro)
+                    digests.push(intro);
+            }
+            meta.readmeDigest = digests.join(" \n ");
+        }
+    }
+    // Preload all markdown headings for each doc — rich section-level signal for search.
+    for (const meta of docs.values()) {
+        meta.headings = extractHeadings(docsDir, meta.docId);
+    }
     _store = { docs, topics, docsDir, codeDir };
     return _store;
 }
+/** Extract all markdown heading texts from a doc, joined by space. Light & full-text. */
+export function extractHeadings(docsDir, docId) {
+    const file = path.join(docsDir, `${docId}.md`);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+    const heads = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
+        if (m) {
+            // strip inline markdown noise (**bold**, `code`, links)
+            const clean = m[1]
+                .replace(/\*\*/g, "")
+                .replace(/`([^`]+)`/g, "$1")
+                .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+                .trim();
+            if (clean)
+                heads.push(clean);
+        }
+    }
+    return heads.join("  ");
+}
+/** Read the intro section (project overview) of a repo's README.md, ~300 chars. */
+export function readReadmeIntro(repoAbs) {
+    const file = path.join(repoAbs, "README.md");
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+    // Try to isolate the "项目简介/Overview/简介" section: from that heading up to the
+    // next section (效果预览/使用说明/How to Use/Effect/工程目录...).
+    const startMatch = text.match(/(?:^|\n)#+\s*(项目简介|简介|Overview|Project Overview|介绍)\s*\n/i);
+    let body;
+    if (startMatch) {
+        const after = text.slice((startMatch.index ?? 0) + startMatch[0].length);
+        const endMatch = after.match(/\n#+\s*(效果预览|使用说明|工程目录|Project Directory|How to Use|Effect|具体实现|相关概念|目录结构)/i);
+        body = endMatch ? after.slice(0, endMatch.index) : after;
+    }
+    else {
+        // No intro heading: take everything before the first ## section after the title.
+        const lines = text.split(/\r?\n/);
+        body = lines.slice(1, 40).join("\n");
+    }
+    const cleaned = body
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, " ")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/^#+\s*/gm, "")
+        .replace(/[*_`>]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    return cleaned.slice(0, 300);
+}
+/** Read a repo's README.md full text (for get_code_example). Null if missing. */
+export function readRepoReadme(repoAbs) {
+    const file = path.join(repoAbs, "README.md");
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the "工程目录 / Project Directory" tree from a README, returning a map of
+ * basename -> purpose comment (e.g. "VideoList.ets" -> "视频列表组件").
+ * Returns empty map if no tree found.
+ */
+export function parseReadmeTree(readme) {
+    const out = new Map();
+    if (!readme)
+        return out;
+    // Find the directory-tree code block: usually after "工程目录"/"Project Directory"/"目录结构".
+    const marker = readme.match(/(工程目录|Project Directory|目录结构|目录说明)[^\n]*\n/i);
+    let start = marker ? marker.index + marker[0].length : -1;
+    let block = "";
+    if (start >= 0) {
+        // Take the fenced ``` ... ``` block that follows, or indented tree lines.
+        const after = readme.slice(start);
+        const fence = after.match(/```[\s\S]*?```/);
+        if (fence) {
+            block = fence[0].replace(/```/g, "");
+        }
+        else {
+            // fallback: lines that look like tree (contain ├── or │ or //)
+            const lines = after.split(/\r?\n/).filter((l) => /^[│├└\s]*[─-]/.test(l) || l.includes("//"));
+            block = lines.join("\n");
+        }
+    }
+    if (!block)
+        return out;
+    // Each tree line: optional tree chars, a path/file, optional "// purpose"
+    for (const line of block.split(/\r?\n/)) {
+        const m = line.match(/([A-Za-z0-9_\-./]+\.(?:ets|ts))\s*\/\/\s*(.+?)\s*$/);
+        if (m) {
+            const base = m[1].split("/").pop().trim();
+            out.set(base, m[2].trim());
+        }
+    }
+    return out;
+}
 /** Read a doc's full markdown body. Returns null if missing. */
 export function readDoc(docsDir, docId) {
     const file = path.join(docsDir, `${docId}.md`);

package/dist/index.js

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { getStore, readDoc, resolveCodePath } from "./data.js";
+import { getStore, readDoc, resolveCodePath, readRepoReadme, readReadmeIntro, parseReadmeTree, } from "./data.js";
 import { search } from "./search.js";
 const store = getStore();
 const server = new McpServer({
@@ -79,11 +79,20 @@ function formatCodeRef(ref) {
     const exists = fs.existsSync(abs);
     lines.push(`  本地: ${abs}${exists ? "" : "  ⚠️ 路径在磁盘上不存在(检查 BP_CODE_DIR 或自行克隆该仓库)"}`);
     if (exists) {
+        // README 简介 + 工程目录树(若有),帮助快速理解仓库用途与文件分工.
+        const intro = readReadmeIntro(abs);
+        if (intro)
+            lines.push(`  简介: ${intro}`);
+        const readme = readRepoReadme(abs);
+        const tree = readme ? parseReadmeTree(readme) : new Map();
         const entries = listEntryFiles(abs);
         if (entries.length) {
             lines.push(`  入口文件:`);
-            for (const e of entries)
-                lines.push(`    - ${e}`);
+            for (const e of entries) {
+                const base = path.basename(e);
+                const purpose = tree.get(base);
+                lines.push(purpose ? `    - ${e}  // ${purpose}` : `    - ${e}`);
+            }
         }
     }
     return lines.join("\n");
@@ -91,50 +100,102 @@ function formatCodeRef(ref) {
 function statusText(s) {
     return s === "cloned" ? "✅ 已克隆" : s === "skipped" ? "⏭️ 核心仓跳过" : "❌ 缺失";
 }
-/** Find up to 8 entry source files (.ets/.ts) in a repo, preferring pages/. */
+/**
+ * Find up to 8 entry source files (.ets/.ts) in a repo.
+ * Strategy: try a list of well-known source dirs (pages > view/components > ets),
+ * each scanned recursively; if none yield files, walk the whole repo (skipping
+ * noise dirs) so unusual module layouts (library/, features/, products/) still work.
+ */
 function listEntryFiles(repoAbs) {
+    const LIMIT = 8;
+    // Ordered: prefer pages/, then view/components, then the ets root of each module.
+    // Covers entry/, library/, features/<x>/, products/<phone>/ style layouts.
     const candidates = [
         "entry/src/main/ets/pages",
+        "entry/src/main/ets/view",
+        "entry/src/main/ets/views",
+        "entry/src/main/ets/components",
         "entry/src/main/ets",
+        "library/src/main/ets/pages",
+        "library/src/main/ets",
     ];
     for (const c of candidates) {
-        const dir = path.join(repoAbs, c.replace(/\//g, path.sep));
-        if (fs.existsSync(dir)) {
-            const files = listDirFiles(dir, [".ets", ".ts"], 8);
+        const dir = path.join(repoAbs, c);
+        if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+            const files = listDirFiles(dir, [".ets", ".ts"], LIMIT);
             if (files.length)
                 return files;
         }
     }
-    // fallback: shallow walk under entry/src (skip resources/build/oh_modules)
-    const entrySrc = path.join(repoAbs, "entry", "src");
-    if (fs.existsSync(entrySrc)) {
-        return walkSources(entrySrc, 8, 3);
-    }
-    return [];
+    // Fallback: walk the whole repo, skipping noise. Deep enough for multi-module layouts.
+    return walkSources(repoAbs, LIMIT, 8);
+}
+/** True for config/test/build noise files we don't want as "entry" examples. */
+function isNoiseFile(name) {
+    const lower = name.toLowerCase();
+    if (lower.startsWith("hvigorfile"))
+        return true;
+    if (lower.endsWith(".test.ts") || lower.endsWith(".test.ets"))
+        return true;
+    if (lower === "build-profile.ts")
+        return true;
+    if (lower === "oh-package.json5.ts")
+        return true;
+    return false;
 }
+/** Rank: pages/ > view/components > Index.ets > other .ets > .ts. Lower = better. */
+function fileRank(fullPath) {
+    const norm = fullPath.replace(/\\/g, "/").toLowerCase();
+    if (norm.includes("/pages/"))
+        return 0;
+    if (norm.includes("/view/") || norm.includes("/views/"))
+        return 1;
+    if (norm.includes("/components/"))
+        return 2;
+    if (norm.endsWith("/index.ets"))
+        return 3;
+    if (norm.endsWith(".ets"))
+        return 4;
+    return 5; // .ts
+}
+/** Recursively collect .ets/.ts source files under dir, skipping noise dirs/files. */
 function listDirFiles(dir, exts, limit) {
-    let ents;
-    try {
-        ents = fs.readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
     const out = [];
-    for (const name of ents.sort()) {
-        if (exts.some((e) => name.endsWith(e))) {
-            out.push(path.join(dir, name));
-            if (out.length >= limit)
-                break;
+    const visit = (d) => {
+        if (out.length >= 64)
+            return; // collect a pool then rank+trim
+        let ents;
+        try {
+            ents = fs.readdirSync(d, { withFileTypes: true });
         }
-    }
-    return out;
+        catch {
+            return;
+        }
+        for (const e of ents) {
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                visit(path.join(d, e.name));
+            }
+            else if (e.isFile() && exts.some((x) => e.name.endsWith(x)) && !isNoiseFile(e.name)) {
+                out.push(path.join(d, e.name));
+            }
+        }
+    };
+    visit(dir);
+    out.sort((a, b) => fileRank(a) - fileRank(b) || a.localeCompare(b));
+    return out.slice(0, limit);
 }
-const SKIP_DIRS = new Set(["resources", "build", "oh_modules", "node_modules", ".git", ".cxx", "cpp", "libs"]);
+const SKIP_DIRS = new Set([
+    "resources", "build", "oh_modules", "node_modules", ".git", ".cxx",
+    "cpp", "libs", "rawfile", "media", "drawable", "element",
+    "test", "ohosTest", "testrunner", ".test", ".hvigor", ".idea",
+    "commons", "hvigor", "scripts",
+]);
 function walkSources(dir, limit, maxDepth) {
     const out = [];
     const visit = (d, depth) => {
-        if (out.length >= limit || depth > maxDepth)
+        if (out.length >= 64 || depth > maxDepth)
             return;
         let ents;
         try {
@@ -144,20 +205,19 @@ function walkSources(dir, limit, maxDepth) {
             return;
         }
         for (const e of ents) {
-            if (out.length >= limit)
-                return;
             if (e.isDirectory()) {
                 if (SKIP_DIRS.has(e.name))
                     continue;
                 visit(path.join(d, e.name), depth + 1);
             }
-            else if (e.isFile() && (e.name.endsWith(".ets") || e.name.endsWith(".ts"))) {
+            else if (e.isFile() && (e.name.endsWith(".ets") || e.name.endsWith(".ts")) && !isNoiseFile(e.name)) {
                 out.push(path.join(d, e.name));
             }
         }
     };
     visit(dir, 0);
-    return out;
+    out.sort((a, b) => fileRank(a) - fileRank(b) || a.localeCompare(b));
+    return out.slice(0, limit);
 }
 /* ------------------------------------------------------------------ *
  * Tool 4: list_by_topic

package/dist/search.js

@@ -58,6 +58,10 @@ export function search(store, query, limit = 8) {
         score += scoreAgainst(qTf, tokenize(meta.title), 5);
         score += scoreAgainst(qTf, tokenize(meta.subtitle), 3);
         score += scoreAgainst(qTf, tokenize(meta.topic), 2);
+        // All markdown headings — section-level signal, covers full doc (not just first 200 lines).
+        score += scoreAgainst(qTf, tokenize(meta.headings), 3);
+        // README intro of associated repos — rich signal (APIs used, what it does).
+        score += scoreAgainst(qTf, tokenize(meta.readmeDigest), 2);
         // Body scan (first ~200 lines) for recall. Lazy-read per candidate doc.
         const bodyScore = scanBody(store.docsDir, meta.docId, qTf, 200);
         score += bodyScore;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "harmonyos-best-practices-mcp",
-  "version": "0.1.0",
-  "description": "MCP server exposing HarmonyOS best-practices docs (452) + reference code (186 repos) for retrieval during development.",
+  "version": "0.2.0",
+  "description": "MCP server exposing HarmonyOS best-practices docs + reference code for retrieval during development.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {