harmony-build 0.2.0

package/README.md

@@ -0,0 +1,265 @@
+# HarmonyOS Toolchain MCP（鸿蒙工具链 MCP 套件 / harmony-build）
+
+> 让 AI Agent（Claude Code / Cursor / Codex / 自研）**真正能操作鸿蒙工程**。
+> 这是 [`提案四-鸿蒙工具链MCP-Server化.md`](../../proposals/提案四-鸿蒙工具链MCP-Server化.md) 的代码实现。
+
+## Changelog
+
+### v0.2.0 (2026-05-21)
+
+- ✅ 新增聚合入口 `harmony-build` MCP Server：一进程、一个 stdio 连接，聚合 7 个子能力包共 **31 个工具**
+- ✅ 工具名加 `<namespace>_` 前缀，避免不同子包重名（如 `hdc_list_devices` / `hvigor_build_hap` / `dev_run_app`）
+- ✅ 提供 `npx harmony-build` 一行启动；支持配置到 Claude Code / Cursor / JoyCode 的 mcpServers 中
+- ✅ 发布到 npm 官方源，包名 `harmony-build`
+
+---
+
+## 快速接入（v0.2.0）
+
+```json
+{
+  "mcpServers": {
+    "harmony-build": {
+      "command": "npx",
+      "args": ["-y", "harmony-build"]
+    }
+  }
+}
+```
+
+---
+
+## 包总览
+
+| 包 | 作用 | 主要 Tool/Resource |
+|---|---|---|
+| **`@harmony-mcp/all`** ⭐ | **聚合包：一进程提供下面所有能力（推广首选）** | 自动给每个工具加 `<ns>_` 前缀，共 31 个工具 |
+| `@harmony-mcp/hdc` | 设备 / 安装 / 截屏 / 日志 | `list_devices`、`install_hap`、`uninstall`、`start_ability`、`stop_ability`、`hilog_capture`、`screencap` |
+| `@harmony-mcp/hvigor` | 构建 / 清理 / 签名 / 日志解析 | `build_hap`、`clean`、`sign_hap`、`parse_build_log`、`run_task` |
+| `@harmony-mcp/profiler` | 性能 trace 抓取 + 分析（最高价值） | `capture_trace`、`analyze_trace`、`capture_and_analyze`、`cold_start_breakdown` |
+| `@harmony-mcp/arkanalyzer` | ArkTS 静态分析 / 影响面 | `find_references`、`impact_analysis`、`list_components`、`count_state_vars` |
+| `@harmony-mcp/arkcheck` | 高性能编码规则（内置 10 条） | `lint_file`、`lint_project`、`explain_rule`、`list_rules` |
+| `@harmony-mcp/knowledge` | RAG 知识库（公司 SOP / 最佳实践） | `search_kb`、`read_doc` + `harmony-kb://` Resources |
+| `@harmony-mcp/dev` | DevEco Run 等价编排 | `run_app`、`start_log_stream`、`read_log_stream`、`stop_log_stream`、`list_log_streams` |
+| `@harmony-mcp/common` | 公共：安全 shell、沙箱、日志、MCP 脚手架 | — |
+
+---
+
+## 30 秒开跑
+
+```bash
+cd scripts/mcp
+npm install
+npm run build
+npm run demo          # 跑端到端验证（不需要鸿蒙设备）
+```
+
+`demo` 会启动三个 MCP server 子进程，用真实 MCP 协议跑：
+- `arkcheck` 扫一段故意写错的 ArkTS → 命中 4 条规则
+- `arkanalyzer` 在本仓库跑组件统计
+- `knowledge` 在 `docs/` + `proposals/` 里搜关键字
+
+---
+
+---
+
+## 接入 JoyCode（一键脚本）
+
+### 推荐：聚合模式（一个 server 装下所有）
+
+```bash
+cd scripts/mcp
+npm run install:joycode               # 默认 = 聚合模式，沙箱根 = 本仓库根目录
+# 指定一个鸿蒙工程作为沙箱根：
+npm run install:joycode -- --project-dir /ABS/PATH/TO/your/harmony/project
+```
+
+脚本会：
+1. 自动备份 `~/.joycode/joycode-mcp.json` 到 `*.bak-<时间戳>`
+2. 注册 **1 个** `harmony-mcp` server（聚合 7 个子能力，共 31 个工具）
+3. 重启 JoyCode 后即可使用
+
+聚合模式下，工具名带 namespace 前缀：`hdc_list_devices` / `hvigor_build_hap` / `dev_run_app` / `arkcheck_lint_project` ……
+
+试一下：
+> "用 hdc_list_devices 看看连了什么设备"
+> "用 dev_run_app 把工程 /XX 跑到设备上，盯 10 秒日志"
+
+### 多 server 模式（需要单独禁用某能力时）
+
+```bash
+npm run install:joycode -- --multi     # 装 7 个独立 harmony-* server
+```
+
+适合：需要在 JoyCode UI 里单独关掉某个能力（如不让 AI 跑 hvigor）；或要求强进程隔离（一个工具崩不影响其他）。
+
+**两种模式不能并存**：要切换的话先手动从 `~/.joycode/joycode-mcp.json` 删掉旧的 `harmony-*` 条目再重装，或加 `--force`。
+
+---
+
+## 接入 Claude Code
+
+把下面内容粘进 `~/.config/claude-code/mcp_servers.json`（或工程内 `.mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "harmony-hdc": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/scripts/mcp/packages/hdc-mcp/dist/index.js"]
+    },
+    "harmony-hvigor": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/scripts/mcp/packages/hvigor-mcp/dist/index.js"]
+    },
+    "harmony-profiler": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/scripts/mcp/packages/profiler-mcp/dist/index.js"]
+    },
+    "harmony-arkanalyzer": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/scripts/mcp/packages/arkanalyzer-mcp/dist/index.js"]
+    },
+    "harmony-arkcheck": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/scripts/mcp/packages/arkcheck-mcp/dist/index.js"]
+    },
+    "harmony-knowledge": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/scripts/mcp/packages/harmony-knowledge-mcp/dist/index.js"],
+      "env": {
+        "HARMONY_KB_ROOTS": "/ABS/PATH/TO/docs:/ABS/PATH/TO/proposals"
+      }
+   }
+  }
+}
+```
+
+## 接入 Cursor
+
+`~/.cursor/mcp.json`（全局）或工程根 `.cursor/mcp.json`（项目级）格式同上。
+
+---
+
+## 环境变量约定
+
+| 变量 | 默认 | 作用 |
+|---|---|---|
+| `HARMONY_MCP_ALLOWED_ROOTS` | **空（推荐留空）** | 额外允许的工程根目录白名单（多个用 PATH 分隔符）。**v0.2 起非必填**：sandbox 会从工具入参里的 `project_dir` / `file_path` 自动向上寻找 `hvigorw` / `hvigorfile.ts` / `oh-package.json5` / `build-profile.json5` 等鸿蒙工程标志文件并加入白名单，切换工程**无需任何配置或重启**。只有当你想给非鸿蒙工程的目录预先开通访问权限，或者希望显式收紧白名单时才需要设置。 |
+| `HARMONY_MCP_LOG_LEVEL` | `info` | 日志等级：debug/info/warn/error |
+| `HDC_BIN` | `hdc` | hdc 可执行路径 |
+| `HDC_TARGET` | — | 默认设备序列号 |
+| `HVIGOR_BIN` | `hvigorw` | hvigor 可执行路径 |
+| `HARMONY_KB_ROOTS` | `./docs:./proposals` | knowledge MCP 暴露的知识库根 |
+| `HARMONY_ARKANALYZER_JAR` | — | 预留：外部 ArkAnalyzer JAR 接入（本期未启用） |
+
+### 沙箱自动识别机制（v0.2）
+
+- `harmony-hvigor`（要执行 shell 的工具）：只允许操作"看起来是鸿蒙工程"的目录——即向上能找到 `hvigorw` / `hvigorfile.ts` / `build-profile.json5` / `oh-package.json5` 之一。这一限制不能被关闭，避免 Agent 误把 hvigor 跑到非工程目录。
+- `harmony-arkcheck` / `harmony-arkanalyzer`（只读静态分析）：拿到 `project_dir` / `file_path` 时优先按上面的规则识别工程根；若识别不到，会把传入的目录本身作为合法根加入沙箱，方便扫描任意 TS / ArkTS 目录。
+- `harmony-hdc` / `harmony-profiler` / `harmony-knowledge`：本身不依赖工程沙箱（操作的是设备 / 临时 trace 文件 / 文档资源），与该变量无关。
+
+> ⚠️ 如果只在某次终端里 `export HARMONY_MCP_ALLOWED_ROOTS=...`，重启 IDE 或新终端会失效。**推荐做法是直接什么都不设**，让自动识别工作；要持久化才考虑写进 `~/.zshrc` / IDE 的 MCP 配置 `env` 块。
+
+---
+
+## 一个典型 Agent 工作流
+
+> 用户：在 Cursor 里说"帮我修首页冷启动卡顿"
+
+Agent 自动编排：
+
+```
+1. harmony-arkanalyzer  list_components      → 找到 EntryAbility / IndexPage
+2. harmony-hdc          list_devices         → 选第一台设备
+3. harmony-profiler     cold_start_breakdown → force-stop → start → 抓 5s trace → 分析
+4. (Agent 推理：发现 main 线程 readFileSync 耗时 230ms)
+5. harmony-arkcheck     explain_rule ARK004  → 拿到修复建议文案
+6. harmony-knowledge    search_kb "异步 IO"   → 找到公司性能 SOP
+7. (Agent 修改源码：readFileSync → await fs.read)
+8. harmony-hvigor       build_hap            → 编译验证
+9. harmony-hdc          install_hap          → 装回设备复测
+10. harmony-profiler    cold_start_breakdown → 复验，确认 jank 消失
+```
+
+**全程无人工 IDE 操作。**
+
+---
+
+## 安全模型
+
+- **沙箱**：所有"读写工程文件"的工具都受 `HARMONY_MCP_ALLOWED_ROOTS` 限制，无法逃逸。
+- **shell 白名单**：`hdc shell` 只允许调用约定子命令（aa / hilog / hitrace / snapshot_display 等），杜绝任意命令注入。
+- **超时强制**：每条命令都有上限（默认 60s，trace 类按 duration+15s 计算），子进程 kill -9 兜底。
+- **stdout 协议保留**：日志统一写 stderr，stdout 仅放 MCP 协议消息。
+- **本地化**：所有 server 在本机进程执行，**不向公网/任意第三方发送数据**。
+
+---
+
+## 内置 ArkCheck 规则（first pass）
+
+| ID | 严重度 | 标题 |
+|---|---|---|
+| ARK001 | warning | 高频 build() 中使用 console.log |
+| ARK002 | warning | ForEach 缺少 key 生成器 |
+| ARK003 | info | 长列表使用 ForEach 而非 LazyForEach |
+| ARK004 | error | 主线程同步 IO（readSync 等） |
+| ARK005 | warning | 组件中 new 大对象未做缓存 |
+| ARK006 | info | 嵌套 Stack/Column 过深（>6 层） |
+| ARK007 | warning | Worker/TaskPool 选择不当 |
+| ARK008 | error | 明文权限/敏感字符串硬编码 |
+| ARK009 | info | setInterval 未在 aboutToDisappear 清理 |
+| ARK010 | info | Image 未指定大小，整图解码 |
+
+参考：华为《2025 HarmonyOS 高性能规则检测创新实践》、最佳实践文档。
+
+---
+
+## 与现有"四提案"的关系
+
+```
+提案一  AI MR 摘要        ← 调用 arkanalyzer.impact_analysis 自动带"影响面"
+提案二  AI Code Review    ← 调用 arkcheck + arkanalyzer 升级到"看语义"
+提案三  AI 单测生成        ← 调用 hvigor.build_hap 实现 Self-Refine 闭环
+新性能  Profiler AI 分析   ← 100% 基于 profiler-mcp
+```
+
+**MCP 化是 1+2+3 共同的底座。**
+
+---
+
+## 路线图
+
+- [x] **P0** `hdc-mcp` MVP + Claude Code 端到端验证
+- [x] **P1** `hvigor-mcp` + `profiler-mcp` 跑通"改→build→trace→分析"闭环
+- [x] **P2** `arkanalyzer-mcp` + `arkcheck-mcp`（内置版）
+- [x] **P3** `harmony-knowledge-mcp`（RAG）
+- [ ] **P4** SSE transport + 多用户共享部署
+- [ ] **P5** 接入官方 ArkAnalyzer JAR（替换内置 regex 版）
+- [ ] **P6** ArkCheck 二进制接入（同上）
+- [ ] **P7** profiler 升级为推理模型直读 .htrace 二进制
+
+---
+
+## 目录结构
+
+```
+scripts/mcp/
+├── package.json                          # npm workspaces 根
+├── tsconfig.base.json                    # 公共 TS 配置
+├── demo/run-demo.mjs                     # 端到端 demo（无需鸿蒙设备）
+└── packages/
+    ├── mcp-common/                       # 公共库
+    ├── hdc-mcp/
+    ├── hvigor-mcp/
+    ├── profiler-mcp/
+    ├── arkanalyzer-mcp/
+    ├── arkcheck-mcp/
+    └── harmony-knowledge-mcp/
+```
+
+---
+
+## License
+
+Apache-2.0

package/dist/packages/arkanalyzer-mcp/src/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { z } from "zod";
+import { ToolDef } from "@harmony-mcp/common";
+export declare const NAMESPACE = "arkanalyzer";
+export declare const tools: ToolDef<z.ZodObject<z.ZodRawShape>>[];

package/dist/packages/arkanalyzer-mcp/src/index.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * arkanalyzer-mcp: ArkTS 静态分析。
+ *
+ * 本期实现轻量版（纯 TS，无外部 JAR 依赖）：
+ *   - find_references     基于正则的符号引用查找
+ *   - impact_analysis     给定一组改动文件，反推受影响的 .ets 页面/组件
+ *   - list_components     列出工程内所有 @Component/@ComponentV2 声明
+ *   - count_state_vars    统计 V1/V2 状态装饰器使用情况
+ *
+ * 当 HARMONY_ARKANALYZER_JAR 环境变量配置时，会优先调用官方 ArkAnalyzer（预留接入点）。
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createLogger, isMainModule, PathSandbox, registerTools, } from "@harmony-mcp/common";
+const logger = createLogger("arkanalyzer-mcp");
+// v0.2: 允许零配置启动；首次收到 project_dir 时自动识别工程根并加白
+const allowedRoots = (process.env.HARMONY_MCP_ALLOWED_ROOTS ?? "")
+    .split(path.delimiter)
+    .filter(Boolean);
+const sandbox = new PathSandbox({ allowedRoots, autoDetectProjectRoot: true });
+const ProjectField = z.string().describe("鸿蒙工程根目录绝对路径（需在 allowedRoots 内）");
+const FindReferencesSchema = z.object({
+    project_dir: ProjectField,
+    symbol: z.string().describe("要查找的标识符名"),
+    file_glob: z.string().default("**/*.ets")
+        .describe("文件 glob；默认 **/*.ets"),
+});
+const ImpactAnalysisSchema = z.object({
+    project_dir: ProjectField,
+    changed_files: z.array(z.string()).describe("本次变更的文件相对/绝对路径列表"),
+});
+const ListComponentsSchema = z.object({
+    project_dir: ProjectField,
+});
+const CountStateVarsSchema = z.object({
+    project_dir: ProjectField,
+});
+// ---------- 文件遍历（极简 glob，仅支持 ** 和 *） ----------
+async function walk(dir, predicate) {
+    const out = [];
+    async function rec(d) {
+        const entries = await fs.readdir(d, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.name.startsWith(".") || e.name === "node_modules" || e.name === "build")
+                continue;
+            const full = path.join(d, e.name);
+            if (e.isDirectory())
+                await rec(full);
+            else if (predicate(full))
+                out.push(full);
+        }
+    }
+    await rec(dir);
+    return out;
+}
+function matchExt(file, exts) {
+    return exts.some((e) => file.endsWith(e));
+}
+// ---------- Tools ----------
+export const NAMESPACE = "arkanalyzer";
+export const tools = [
+    {
+        name: "find_references",
+        description: "在工程内查找指定标识符的引用（正则匹配，含定义与使用点）",
+        schema: FindReferencesSchema,
+        handler: async (a) => {
+            const root = sandbox.ensureReadOnlyRoot(a.project_dir);
+            const files = await walk(root, (p) => matchExt(p, [".ets", ".ts"]));
+            const re = new RegExp(`\\b${escapeRegex(a.symbol)}\\b`);
+            const hits = [];
+            for (const f of files) {
+                const text = await fs.readFile(f, "utf8");
+                const lines = text.split(/\r?\n/);
+                for (let i = 0; i < lines.length; i++) {
+                    if (re.test(lines[i])) {
+                        hits.push({ file: path.relative(root, f), line: i + 1, text: lines[i].trim() });
+                    }
+                }
+            }
+            return { symbol: a.symbol, hits: hits.slice(0, 500), total: hits.length };
+        },
+    },
+    {
+        name: "impact_analysis",
+        description: "基于符号引用反推：本次 changed_files 中导出的符号被哪些其他 .ets 文件引用",
+        schema: ImpactAnalysisSchema,
+        handler: async (a) => {
+            const root = sandbox.ensureReadOnlyRoot(a.project_dir);
+            // 1) 抽取每个 changed_file 的导出符号（极简：匹配 export class / export function / @Component struct Foo）
+            const exportedByFile = new Map();
+            for (const rel of a.changed_files) {
+                const abs = sandbox.resolve(path.isAbsolute(rel) ? rel : path.join(root, rel));
+                let text;
+                try {
+                    text = await fs.readFile(abs, "utf8");
+                }
+                catch {
+                    continue;
+                }
+                const symbols = extractExports(text);
+                exportedByFile.set(path.relative(root, abs), symbols);
+            }
+            // 2) 全仓搜引用
+            const files = await walk(root, (p) => matchExt(p, [".ets", ".ts"]));
+            const impactedSet = new Map(); // changedFile -> set of impactedFiles
+            for (const f of files) {
+                const rel = path.relative(root, f);
+                if (exportedByFile.has(rel))
+                    continue;
+                const text = await fs.readFile(f, "utf8");
+                for (const [changed, syms] of exportedByFile) {
+                    for (const sym of syms) {
+                        const re = new RegExp(`\\b${escapeRegex(sym)}\\b`);
+                        if (re.test(text)) {
+                            const set = impactedSet.get(changed) ?? new Set();
+                            set.add(rel);
+                            impactedSet.set(changed, set);
+                            break;
+                        }
+                    }
+                }
+            }
+            const result = Object.fromEntries([...impactedSet].map(([k, v]) => [k, [...v]]));
+            const allImpacted = new Set();
+            for (const v of impactedSet.values())
+                for (const f of v)
+                    allImpacted.add(f);
+            return {
+                exported_symbols: Object.fromEntries(exportedByFile),
+                per_file_impact: result,
+                all_impacted_files: [...allImpacted],
+                total_impacted: allImpacted.size,
+            };
+        },
+    },
+    {
+        name: "list_components",
+        description: "列出工程内所有 @Component / @ComponentV2 声明（struct 名）",
+        schema: ListComponentsSchema,
+        handler: async (a) => {
+            const root = sandbox.ensureReadOnlyRoot(a.project_dir);
+            const files = await walk(root, (p) => p.endsWith(".ets"));
+            const re = /@(Component|ComponentV2|Entry)\s*[\s\S]*?struct\s+(\w+)/g;
+            const components = [];
+            for (const f of files) {
+                const text = await fs.readFile(f, "utf8");
+                let m;
+                while ((m = re.exec(text)) !== null) {
+                    components.push({ file: path.relative(root, f), kind: m[1], name: m[2] });
+                }
+            }
+            return { count: components.length, components };
+        },
+    },
+    {
+        name: "count_state_vars",
+        description: "统计 V1 / V2 状态装饰器使用次数（@State/@Prop/@Link vs @Local/@Param/@Once）",
+        schema: CountStateVarsSchema,
+        handler: async (a) => {
+            const root = sandbox.ensureReadOnlyRoot(a.project_dir);
+            const files = await walk(root, (p) => p.endsWith(".ets"));
+            const counters = {};
+            const v1 = ["@State", "@Prop", "@Link", "@Provide", "@Consume", "@ObjectLink", "@Observed"];
+            const v2 = ["@Local", "@Param", "@Once", "@Event", "@Trace", "@ObservedV2"];
+            for (const f of files) {
+                const text = await fs.readFile(f, "utf8");
+                for (const k of [...v1, ...v2]) {
+                    const cnt = (text.match(new RegExp(escapeRegex(k) + "\\b", "g")) ?? []).length;
+                    counters[k] = (counters[k] ?? 0) + cnt;
+                }
+            }
+            const v1Total = v1.reduce((s, k) => s + (counters[k] ?? 0), 0);
+            const v2Total = v2.reduce((s, k) => s + (counters[k] ?? 0), 0);
+            return { per_decorator: counters, v1_total: v1Total, v2_total: v2Total };
+        },
+    },
+];
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractExports(text) {
+    const symbols = new Set();
+    const patterns = [
+        /export\s+(?:default\s+)?class\s+(\w+)/g,
+        /export\s+(?:default\s+)?function\s+(\w+)/g,
+        /export\s+(?:default\s+)?const\s+(\w+)/g,
+        /export\s+(?:default\s+)?interface\s+(\w+)/g,
+        /export\s+(?:default\s+)?enum\s+(\w+)/g,
+        /@(?:Component|ComponentV2|Entry)\s*[\s\S]*?struct\s+(\w+)/g,
+    ];
+    for (const re of patterns) {
+        let m;
+        while ((m = re.exec(text)) !== null)
+            symbols.add(m[1]);
+    }
+    return [...symbols];
+}
+async function main() {
+    if (process.env.HARMONY_ARKANALYZER_JAR) {
+        logger.info("external ArkAnalyzer JAR detected (not yet wired in this build)", {
+            jar: process.env.HARMONY_ARKANALYZER_JAR,
+        });
+    }
+    const server = new Server({ name: "harmony-arkanalyzer-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    registerTools(server, { ListToolsRequestSchema, CallToolRequestSchema }, tools);
+    await server.connect(new StdioServerTransport());
+    logger.info("arkanalyzer-mcp started", { allowedRoots });
+}
+if (isMainModule(import.meta.url)) {
+    main().catch((err) => {
+        logger.error("fatal", { err: String(err) });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/arkanalyzer-mcp/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/arkanalyzer-mcp/src/index.ts"],"names":[],"mappings":"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"}

package/dist/packages/arkcheck-mcp/src/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { z } from "zod";
+import { ToolDef } from "@harmony-mcp/common";
+export declare const NAMESPACE = "arkcheck";
+export declare const tools: ToolDef<z.ZodObject<z.ZodRawShape>>[];

package/dist/packages/arkcheck-mcp/src/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * arkcheck-mcp: HarmonyOS 高性能编码规则扫描。
+ *
+ * 工具：
+ *   - lint_file     扫描单个文件
+ *   - lint_project  扫描整个工程（默认仅 .ets）
+ *   - explain_rule  返回某条规则的解释 + 修复建议
+ *   - list_rules    列出全部规则元数据（供 Agent 自选启用）
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createLogger, HarmonyMcpError, isMainModule, PathSandbox, registerTools, } from "@harmony-mcp/common";
+import { BUILTIN_RULES, explainRule } from "./rules.js";
+const logger = createLogger("arkcheck-mcp");
+// v0.2: 允许零配置启动；lint_file/lint_project 收到路径时再自动识别工程根
+const allowedRoots = (process.env.HARMONY_MCP_ALLOWED_ROOTS ?? "")
+    .split(path.delimiter)
+    .filter(Boolean);
+const sandbox = new PathSandbox({ allowedRoots, autoDetectProjectRoot: true });
+function scanText(text, file, enabled) {
+    const findings = [];
+    const lines = text.split(/\r?\n/);
+    for (const rule of BUILTIN_RULES) {
+        if (enabled.size && !enabled.has(rule.id))
+            continue;
+        const m = rule.pattern.exec(text);
+        if (!m)
+            continue;
+        // 计算行号：取匹配起点
+        const upto = text.slice(0, m.index);
+        const lineNo = upto.split(/\r?\n/).length;
+        findings.push({
+            rule_id: rule.id,
+            severity: rule.severity,
+            title: rule.title,
+            file,
+            line: lineNo,
+            preview: (lines[lineNo - 1] ?? "").trim(),
+            suggestion: rule.suggestion,
+        });
+    }
+    return findings;
+}
+async function walkEts(dir) {
+    const out = [];
+    async function rec(d) {
+        const entries = await fs.readdir(d, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.name.startsWith(".") || e.name === "node_modules" || e.name === "build")
+                continue;
+            const full = path.join(d, e.name);
+            if (e.isDirectory())
+                await rec(full);
+            else if (full.endsWith(".ets") || full.endsWith(".ts"))
+                out.push(full);
+        }
+    }
+    await rec(dir);
+    return out;
+}
+const LintFileSchema = z.object({
+    file_path: z.string().describe("要扫描的文件绝对路径"),
+    rules: z.array(z.string()).optional().describe("仅启用这些规则 ID；省略=全部"),
+});
+const LintProjectSchema = z.object({
+    project_dir: z.string().describe("工程根目录"),
+    rules: z.array(z.string()).optional(),
+    max_findings: z.number().int().positive().max(2000).default(500),
+});
+const ExplainRuleSchema = z.object({
+    rule_id: z.string(),
+});
+const ListRulesSchema = z.object({});
+export const NAMESPACE = "arkcheck";
+export const tools = [
+    {
+        name: "lint_file",
+        description: "对单个文件运行内置规则集",
+        schema: LintFileSchema,
+        handler: async (a) => {
+            const abs = sandbox.ensureReadOnlyRoot(a.file_path);
+            const text = await fs.readFile(abs, "utf8");
+            const enabled = new Set(a.rules ?? []);
+            const findings = scanText(text, abs, enabled);
+            return { file: abs, findings, count: findings.length };
+        },
+    },
+    {
+        name: "lint_project",
+        description: "对整个工程运行规则集，返回前 N 条 findings",
+        schema: LintProjectSchema,
+        handler: async (a) => {
+            const root = sandbox.ensureReadOnlyRoot(a.project_dir);
+            const files = await walkEts(root);
+            const enabled = new Set(a.rules ?? []);
+            const all = [];
+            for (const f of files) {
+                const text = await fs.readFile(f, "utf8");
+                const rel = path.relative(root, f);
+                all.push(...scanText(text, rel, enabled));
+                if (all.length >= a.max_findings)
+                    break;
+            }
+            return {
+                scanned_files: files.length,
+                findings: all.slice(0, a.max_findings),
+                total: all.length,
+                by_severity: countBy(all, (x) => x.severity),
+                by_rule: countBy(all, (x) => x.rule_id),
+            };
+        },
+    },
+    {
+        name: "explain_rule",
+        description: "返回某条规则的解释、严重度与修复建议",
+        schema: ExplainRuleSchema,
+        handler: async (a) => {
+            const r = explainRule(a.rule_id);
+            if (!r)
+                throw new HarmonyMcpError("RULE_NOT_FOUND", `unknown rule_id: ${a.rule_id}`);
+            const { pattern, ...rest } = r;
+            return { ...rest, pattern_source: pattern.source };
+        },
+    },
+    {
+        name: "list_rules",
+        description: "列出全部内置规则元数据",
+        schema: ListRulesSchema,
+        handler: async () => BUILTIN_RULES.map(({ pattern, ...rest }) => ({ ...rest, pattern_source: pattern.source })),
+    },
+];
+function countBy(arr, key) {
+    const r = {};
+    for (const x of arr) {
+        const k = key(x);
+        r[k] = (r[k] ?? 0) + 1;
+    }
+    return r;
+}
+async function main() {
+    const server = new Server({ name: "harmony-arkcheck-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    registerTools(server, { ListToolsRequestSchema, CallToolRequestSchema }, tools);
+    await server.connect(new StdioServerTransport());
+    logger.info("arkcheck-mcp started", {
+        allowedRoots,
+        builtin_rules: BUILTIN_RULES.length,
+    });
+}
+if (isMainModule(import.meta.url)) {
+    main().catch((err) => {
+        logger.error("fatal", { err: String(err) });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map