harmonyos-best-practices-mcp 0.2.1 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -15
- package/dist/index.js +20 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,10 +18,12 @@
|
|
|
18
18
|
|
|
19
19
|
| 工具 | 作用 |
|
|
20
20
|
|------|------|
|
|
21
|
-
| `search_best_practices({query, limit?})` | 全文检索文档(
|
|
21
|
+
| `search_best_practices({query, limit?})` | 全文检索文档(BM25 + CJK 权重 + 同义词扩展,中文友好),返回相关度排序的文档列表(含主题、是否有代码、代码仓库名) |
|
|
22
22
|
| `get_doc({name})` | 读取指定文档(docId)的完整 Markdown 正文 |
|
|
23
23
|
| `get_code_example({docName})` | 返回文档关联的参考代码:本地仓库绝对路径、远程 URL、README 简介、入口 `.ets/.ts` 文件(带用途注释) |
|
|
24
|
-
| `list_by_topic({topic?})` |
|
|
24
|
+
| `list_by_topic({topic?})` | 按分类路径浏览(稳定性/性能/媒体/功耗/一多…),支持多级下钻(如 `媒体 / 音频和视频`);省略参数返回所有大类及文档数 |
|
|
25
|
+
|
|
26
|
+
**检索算法**:BM25 排序(TF 饱和 + 文档长度归一化 + IDF)→ CJK 单字×0.3 / 双字 bigram×0.5 降权(抑制跨词边界噪声)→ 域内同义词软 OR 扩展(`data/synonyms.json` 驱动)。同义词词典数据驱动,编辑 JSON 即可扩展,无需改代码。
|
|
25
27
|
|
|
26
28
|
## 四者并列使用
|
|
27
29
|
|
|
@@ -32,20 +34,20 @@
|
|
|
32
34
|
"mcp": {
|
|
33
35
|
"harmonyos-best-practices": {
|
|
34
36
|
"type": "local",
|
|
35
|
-
"command": ["npx", "-y", "harmonyos-best-practices-mcp"],
|
|
37
|
+
"command": ["npx", "-y", "harmonyos-best-practices-mcp@latest"],
|
|
36
38
|
"environment": { "BP_CODE_DIR": "/abs/path/to/best_practices_code" }
|
|
37
39
|
},
|
|
38
40
|
"harmonyos-guides": {
|
|
39
41
|
"type": "local",
|
|
40
|
-
"command": ["npx", "-y", "harmonyos-guides-mcp"]
|
|
42
|
+
"command": ["npx", "-y", "harmonyos-guides-mcp@latest"]
|
|
41
43
|
},
|
|
42
44
|
"harmonyos-api-references": {
|
|
43
45
|
"type": "local",
|
|
44
|
-
"command": ["npx", "-y", "harmonyos-api-references-mcp"]
|
|
46
|
+
"command": ["npx", "-y", "harmonyos-api-references-mcp@latest"]
|
|
45
47
|
},
|
|
46
48
|
"harmonyos-ui-design-guides": {
|
|
47
49
|
"type": "local",
|
|
48
|
-
"command": ["npx", "-y", "harmonyos-ui-design-guides-mcp"]
|
|
50
|
+
"command": ["npx", "-y", "harmonyos-ui-design-guides-mcp@latest"]
|
|
49
51
|
}
|
|
50
52
|
}
|
|
51
53
|
}
|
|
@@ -58,20 +60,20 @@
|
|
|
58
60
|
"mcpServers": {
|
|
59
61
|
"harmonyos-best-practices": {
|
|
60
62
|
"command": "npx",
|
|
61
|
-
"args": ["-y", "harmonyos-best-practices-mcp"],
|
|
63
|
+
"args": ["-y", "harmonyos-best-practices-mcp@latest"],
|
|
62
64
|
"env": { "BP_CODE_DIR": "/abs/path/to/best_practices_code" }
|
|
63
65
|
},
|
|
64
66
|
"harmonyos-guides": {
|
|
65
67
|
"command": "npx",
|
|
66
|
-
"args": ["-y", "harmonyos-guides-mcp"]
|
|
68
|
+
"args": ["-y", "harmonyos-guides-mcp@latest"]
|
|
67
69
|
},
|
|
68
70
|
"harmonyos-api-references": {
|
|
69
71
|
"command": "npx",
|
|
70
|
-
"args": ["-y", "harmonyos-api-references-mcp"]
|
|
72
|
+
"args": ["-y", "harmonyos-api-references-mcp@latest"]
|
|
71
73
|
},
|
|
72
74
|
"harmonyos-ui-design-guides": {
|
|
73
75
|
"command": "npx",
|
|
74
|
-
"args": ["-y", "harmonyos-ui-design-guides-mcp"]
|
|
76
|
+
"args": ["-y", "harmonyos-ui-design-guides-mcp@latest"]
|
|
75
77
|
}
|
|
76
78
|
}
|
|
77
79
|
}
|
|
@@ -89,7 +91,7 @@
|
|
|
89
91
|
|
|
90
92
|
```bash
|
|
91
93
|
# 方式一:一次性运行(推荐,每次自动拉最新版)
|
|
92
|
-
npx -y harmonyos-best-practices-mcp
|
|
94
|
+
npx -y harmonyos-best-practices-mcp@latest
|
|
93
95
|
|
|
94
96
|
# 方式二:全局安装(需手动更新)
|
|
95
97
|
npm install -g harmonyos-best-practices-mcp
|
|
@@ -104,13 +106,15 @@ npm install -g harmonyos-best-practices-mcp
|
|
|
104
106
|
"mcpServers": {
|
|
105
107
|
"harmonyos-best-practices": {
|
|
106
108
|
"command": "npx",
|
|
107
|
-
"args": ["-y", "harmonyos-best-practices-mcp"]
|
|
109
|
+
"args": ["-y", "harmonyos-best-practices-mcp@latest"]
|
|
108
110
|
}
|
|
109
111
|
}
|
|
110
112
|
}
|
|
111
113
|
```
|
|
112
114
|
|
|
113
|
-
|
|
115
|
+
> `@latest` 每次启动联网拉最新版;也可固定版本如 `@0.2.1` 避免版本漂移与启动联网。
|
|
116
|
+
|
|
117
|
+
**Cursor / Cline / 其他 stdio 客户端**:同上,指向 `npx -y harmonyos-best-practices-mcp@latest`。
|
|
114
118
|
|
|
115
119
|
### (可选)启用本地代码读取
|
|
116
120
|
|
|
@@ -145,7 +149,7 @@ Claude Code 配置加 env:
|
|
|
145
149
|
"mcpServers": {
|
|
146
150
|
"harmonyos-best-practices": {
|
|
147
151
|
"command": "npx",
|
|
148
|
-
"args": ["-y", "harmonyos-best-practices-mcp"],
|
|
152
|
+
"args": ["-y", "harmonyos-best-practices-mcp@latest"],
|
|
149
153
|
"env": { "BP_CODE_DIR": "/abs/path/to/best_practices_code" }
|
|
150
154
|
}
|
|
151
155
|
}
|
|
@@ -157,9 +161,23 @@ Claude Code 配置加 env:
|
|
|
157
161
|
| 变量 | 默认 | 说明 |
|
|
158
162
|
|------|------|------|
|
|
159
163
|
| `BP_DOCS_DIR` | 包内 `data/docs` | 文档目录(一般无需改) |
|
|
160
|
-
| `BP_INDEX` | 包内 `data/
|
|
164
|
+
| `BP_INDEX` | 包内 `data/code_list.md` | 文档↔代码仓库映射索引(机器读,一般无需改) |
|
|
165
|
+
| `BP_LOG` | 包内 `data/index_log.txt` | 分类日志(驱动文档分类,缺失会报错;一般无需改) |
|
|
161
166
|
| `BP_CODE_DIR` | 空 | 本地代码根目录;为空时 `get_code_example` 只给 URL |
|
|
162
167
|
|
|
168
|
+
> `data/synonyms.json` 为同义词词典(随包),缺失时检索退化为无同义词扩展,不影响正常使用。`data/INDEX.md` 是人读文档索引(代码不读)。
|
|
169
|
+
|
|
170
|
+
### 数据布局(包内 `data/`)
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
data/
|
|
174
|
+
├── docs/ # 纯 .md 文档(452 篇)
|
|
175
|
+
├── index_log.txt # 分类日志(机器读,驱动分类)
|
|
176
|
+
├── code_list.md # 文档↔代码仓库映射(机器读)
|
|
177
|
+
├── synonyms.json # 同义词词典(检索用,可编辑扩展)
|
|
178
|
+
└── INDEX.md # 人读文档索引(按 29 大类分组,代码不读)
|
|
179
|
+
```
|
|
180
|
+
|
|
163
181
|
## 更新
|
|
164
182
|
|
|
165
183
|
文档和服务器会持续更新(版本号见 `package.json`)。
|
package/dist/index.js
CHANGED
|
@@ -12,6 +12,19 @@ const server = new McpServer({
|
|
|
12
12
|
version: "0.1.0",
|
|
13
13
|
});
|
|
14
14
|
const SEP = " / ";
|
|
15
|
+
/**
|
|
16
|
+
* Normalize a category path for tolerant prefix matching: strip full/half-width
|
|
17
|
+
* parenthetical qualifiers from each segment, e.g.
|
|
18
|
+
* "媒体 / Media Kit（媒体服务）" -> "媒体 / Media Kit".
|
|
19
|
+
* Lets users drill down without knowing the exact parenthetical suffix.
|
|
20
|
+
*/
|
|
21
|
+
function normPath(p) {
|
|
22
|
+
return p
|
|
23
|
+
.split(SEP)
|
|
24
|
+
.map((seg) => seg.replace(/[(（][^)）]*[)）]/g, "").trim())
|
|
25
|
+
.join(SEP)
|
|
26
|
+
.trim();
|
|
27
|
+
}
|
|
15
28
|
/* ------------------------------------------------------------------ *
|
|
16
29
|
* Tool 1: search_best_practices
|
|
17
30
|
* ------------------------------------------------------------------ */
|
|
@@ -241,12 +254,19 @@ server.tool("list_by_topic", "按主题分类浏览最佳实践文档(Browse bes
|
|
|
241
254
|
}
|
|
242
255
|
// Prefix match on full path: path === topic OR path startsWith "topic / ".
|
|
243
256
|
// Supports multi-level drill-down, e.g. "媒体" or "媒体 / Audio".
|
|
257
|
+
// Prefix match: path === topic OR path startsWith "topic / ".
|
|
258
|
+
// Tolerant of parenthetical qualifiers (Media Kit（媒体服务） -> Media Kit),
|
|
259
|
+
// so users can drill down without the exact parenthetical suffix.
|
|
244
260
|
const prefix = topic.trim();
|
|
261
|
+
const normPrefix = normPath(prefix);
|
|
245
262
|
const matched = [];
|
|
246
263
|
for (const meta of store.docs.values()) {
|
|
247
264
|
if (meta.path === prefix || meta.path.startsWith(prefix + SEP)) {
|
|
248
265
|
matched.push(meta);
|
|
249
266
|
}
|
|
267
|
+
else if (normPrefix && (normPath(meta.path) === normPrefix || normPath(meta.path).startsWith(normPrefix + SEP))) {
|
|
268
|
+
matched.push(meta);
|
|
269
|
+
}
|
|
250
270
|
}
|
|
251
271
|
if (matched.length === 0) {
|
|
252
272
|
return text(`未找到路径 "${prefix}"。可用大类: ${[...store.topics.keys()].sort().join("、")}`);
|
package/package.json
CHANGED