@luckychen1993/pm-mcp 0.1.5 → 0.4.0

package/dist/tool-base.js

@@ -25,19 +25,21 @@ export function recordUsage(root, tool, kind, started, outcome) {
     }
 }
 /** 只读工具：跨 Agent/进程合并完全相同的并行请求，短窗复用结果。 */
-export function toolR(server, root, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema, annotations: { readOnlyHint: true } }, (async (args) => {
+export function toolR(server, root, name, description, schema, fn, presentation) {
+    server.registerTool(name, { description, inputSchema: schema, ...(presentation ? { outputSchema: presentation.outputSchema } : {}), annotations: { readOnlyHint: true } }, (async (args) => {
         const started = Date.now();
         try {
-            const result = await runCoalescedRead(root, name, args, fn);
+            const result = await runCoalescedRead(root, presentation ? `${name}:${presentation.cacheVersion ?? "structured-v1"}` : name, args, fn);
+            const decoded = presentation?.decode(result.text);
+            const text = decoded?.text ?? result.text;
             recordUsage(root, name, "read", started, {
                 ok: !result.pending,
-                text: result.text,
+                text: decoded ? text + JSON.stringify(decoded.data) : text,
                 replayed: result.replayed,
                 pending: result.pending,
                 uncertain: result.uncertain,
             });
-            return { content: [{ type: "text", text: result.text }] };
+            return { content: [{ type: "text", text }], ...(decoded ? { structuredContent: decoded.data } : {}) };
         }
         catch (error) {
             const message = error.message;

package/dist/types.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { normSep } from "./budget.js";
+import { ScanIgnoreSchema } from "./scan-policy.js";
+import { CompletionEvidenceSchema } from "./quality-evidence.js";
 export const now = () => new Date().toISOString();
 /** 文件清单字段：统一 / 分隔（Windows 反斜杠入库即规范化），缺省空数组 */
 const filesField = () => z.array(z.string()).default([]).transform((list) => list.map(normSep));
@@ -24,6 +26,8 @@ export const ProjectSchema = z.object({
     phase: z.string().default(""),
     /** 登记的模块名（用于复杂度账的"未登记目录"检测） */
     modules: z.array(z.string()).default([]),
+    scan_ignore: ScanIgnoreSchema.optional(),
+    completion_evidence: CompletionEvidenceSchema.optional(),
     /** 暴露面：local=本机工具 / network=内网服务 / public=公网服务，影响安全告警力度 */
     exposure: ExposureSchema.default("local"),
     /** 项目许可证（SPDX 或名称），用于依赖兼容性对账 */
@@ -118,6 +122,7 @@ export const SessionSchema = z.object({
     author: z.string().default(""),
     summary: z.string().trim().min(1),
     files: filesField(),
+    file_hashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),
     next_steps: z.array(z.string()).default([]),
 });
 export const SessionsFileSchema = z.object({

package/dist/ui.js

@@ -0,0 +1,191 @@
+import http from "node:http";
+import path from "node:path";
+import fs from "node:fs";
+import { isInitialized } from "./paths.js";
+import { loadProject, loadTasks, loadRoadmap, loadFeatures, loadSessions, loadSecurity } from "./store.js";
+import { milestoneStats } from "./roadmap.js";
+import { aggregates, ensureFresh, getIndex } from "./index-store.js";
+import { VERSION } from "./version.js";
+/**
+ * 本地只读 Web 仪表盘（零依赖 node:http）：
+ *   pm-mcp ui [--root <项目>] [--port <端口>]
+ *
+ * 安全边界：仅绑定 127.0.0.1、纯 GET 只读、未初始化 fail-closed、无外部资源、
+ * 所有插值经 HTML 转义（任务标题等用户内容不可注入）；响应 CSP 禁止脚本。
+ */
+const esc = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+function latestQualityRun(root) {
+    const dir = path.join(root, ".pm", "quality-runs");
+    try {
+        const latest = fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort().pop();
+        if (!latest)
+            return null;
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, latest), "utf8"));
+        const summary = raw.results?.[0]?.output_summary;
+        return { at: raw.run_at ?? "", ok: raw.ok === true, tests: summary ? `${summary.passed}/${summary.tests}` : "n/a" };
+    }
+    catch {
+        return null;
+    }
+}
+export function buildDashboardState(root) {
+    const absolute = path.resolve(root);
+    const project = loadProject(absolute);
+    const { tasks } = loadTasks(absolute);
+    const { milestones } = loadRoadmap(absolute);
+    const features = loadFeatures(absolute).features;
+    const security = loadSecurity(absolute).findings;
+    const sessions = loadSessions(absolute).sessions;
+    const byStatus = {};
+    for (const task of tasks)
+        byStatus[task.status] = (byStatus[task.status] ?? 0) + 1;
+    const recent = [...tasks]
+        .sort((a, b) => b.id.localeCompare(a.id))
+        .slice(0, 10)
+        .map((task) => ({ id: task.id, title: task.title, status: task.status, priority: task.priority ?? "" }));
+    let index = null;
+    try {
+        ensureFresh(absolute);
+        const agg = aggregates(getIndex(absolute));
+        index = { files: agg.totalFiles, loc: agg.totalLoc };
+    }
+    catch {
+        index = null;
+    }
+    const last = sessions.length > 0 ? sessions[sessions.length - 1] : null;
+    return {
+        name: project.name,
+        description: project.description,
+        phase: project.phase,
+        exposure: project.exposure,
+        version: VERSION,
+        milestones: milestones.map((milestone) => {
+            const stats = milestoneStats(tasks, milestone.id);
+            return { id: milestone.id, title: milestone.title, status: milestone.status, done: stats.done, total: stats.total, pct: stats.total === 0 ? 0 : stats.pct };
+        }),
+        tasks: { total: tasks.length, byStatus, recent },
+        features: {
+            total: features.length,
+            implemented: features.filter((f) => f.status === "implemented").length,
+            planned: features.filter((f) => f.status === "planned").length,
+            deprecated: features.filter((f) => f.status === "deprecated").length,
+        },
+        security: {
+            open: security.filter((f) => f.status === "open").length,
+            high: security.filter((f) => f.status === "open" && f.severity === "high").length,
+            accepted: security.filter((f) => f.status === "accepted").length,
+        },
+        sessions: {
+            count: sessions.length,
+            last: last ? { at: last.date, author: last.author, summary: last.summary } : null,
+        },
+        index,
+        quality: latestQualityRun(absolute),
+    };
+}
+export function renderDashboardHtml(state) {
+    const taskStatus = Object.entries(state.tasks.byStatus).map(([status, count]) => `${esc(status)} ${count}`).join(" · ") || "无";
+    const milestoneRows = state.milestones.map((m) => {
+        const statusIcon = m.status === "done" ? "✅" : m.status === "active" ? "▶" : "☐";
+        return `<tr><td>${esc(m.id)}</td><td>${statusIcon} ${esc(m.title)}</td><td>${m.done}/${m.total}</td>` +
+            `<td><div class="bar"><div class="fill" style="width:${Math.min(100, Math.max(0, m.pct))}%"></div></div>${m.pct}%</td></tr>`;
+    }).join("");
+    const taskRows = state.tasks.recent.map((task) => `<tr><td>${esc(task.id)}</td><td>${esc(task.title)}</td><td>${esc(task.status)}</td><td>${esc(task.priority)}</td></tr>`).join("");
+    const lastSession = state.sessions.last
+        ? `<p>最近：${esc(state.sessions.last.at)} · ${esc(state.sessions.last.author)} — ${esc(state.sessions.last.summary.slice(0, 160))}</p>`
+        : "<p>（无会话记录）</p>";
+    const quality = state.quality
+        ? `<span class="${state.quality.ok ? "ok" : "bad"}">${state.quality.ok ? "✅" : "🚩"} ${esc(state.quality.tests)}</span> @ ${esc(state.quality.at)}`
+        : "（暂无质量报告）";
+    return `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(state.name)} · pm-mcp</title>
+<style>
+body{font-family:system-ui,"Segoe UI",sans-serif;margin:0;background:#f6f7f9;color:#1c2733}
+main{max-width:960px;margin:0 auto;padding:24px}
+h1{font-size:22px}h2{font-size:16px;margin:28px 0 8px;border-bottom:1px solid #dde3ea;padding-bottom:6px}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px}
+.card{background:#fff;border:1px solid #dde3ea;border-radius:8px;padding:12px}
+.card b{display:block;font-size:20px}.card span{color:#5b6b7c;font-size:12px}
+table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #dde3ea}
+td,th{padding:6px 10px;border-bottom:1px solid #eef1f4;text-align:left;font-size:13px}
+.bar{background:#e8edf2;border-radius:6px;height:10px;min-width:80px;display:inline-block;vertical-align:middle;margin-right:6px}
+.fill{background:#3d7bd9;height:10px;border-radius:6px}
+.ok{color:#1a7f37}.bad{color:#c62828}
+footer{color:#8a97a5;font-size:12px;margin-top:24px}
+</style></head><body><main>
+<h1>${esc(state.name)} <small style="font-size:13px;color:#5b6b7c">pm-mcp v${esc(state.version)}</small></h1>
+<p>${esc(state.description || "（无描述）")} · 阶段：${esc(state.phase || "未设置")} · 暴露面：${esc(state.exposure)}</p>
+<h2>概览</h2>
+<div class="grid">
+<div class="card"><b>${state.tasks.total}</b><span>任务</span></div>
+<div class="card"><b>${state.features.implemented}</b><span>功能已实现 / 共 ${state.features.total}</span></div>
+<div class="card"><b class="${state.security.high > 0 ? "bad" : "ok"}">${state.security.open}</b><span>安全未处理（高危 ${state.security.high}）</span></div>
+<div class="card"><b>${state.sessions.count}</b><span>会话记录</span></div>
+<div class="card"><b>${state.index ? state.index.files : "—"}</b><span>索引文件${state.index ? ` / ${state.index.loc} 行` : ""}</span></div>
+<div class="card"><b>${quality}</b><span>最近质量门禁</span></div>
+</div>
+<h2>里程碑</h2>
+${milestoneRows ? `<table><tr><th>ID</th><th>标题</th><th>任务</th><th>进度</th></tr>${milestoneRows}</table>` : "<p>（无里程碑）</p>"}
+<h2>最近任务</h2>
+${taskRows ? `<table><tr><th>ID</th><th>标题</th><th>状态</th><th>优先级</th></tr>${taskRows}</table><p style="font-size:12px;color:#5b6b7c">状态分布：${esc(taskStatus)}</p>` : "<p>（无任务）</p>"}
+<h2>会话</h2>
+${lastSession}
+<footer>只读视图 · 仅绑定 127.0.0.1 · 数据来自 ${esc(state.name)} 的 .pm/ 台账 · ${new Date().toISOString()}</footer>
+</main></body></html>`;
+}
+const HEAD_405 = { allow: "GET, HEAD" };
+export async function startUiServer(root, options = {}) {
+    const absolute = path.resolve(root);
+    if (!isInitialized(absolute))
+        throw new Error(`目标不是已纳管项目（缺 .pm/）：${absolute}`);
+    const server = http.createServer((request, response) => {
+        response.setHeader("content-security-policy", "default-src 'none'; style-src 'unsafe-inline'");
+        response.setHeader("x-content-type-options", "nosniff");
+        response.setHeader("cache-control", "no-store");
+        try {
+            const url = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                response.writeHead(405, HEAD_405);
+                response.end("只读服务");
+                return;
+            }
+            if (url.pathname === "/healthz") {
+                response.writeHead(200, { "content-type": "text/plain" });
+                response.end("ok");
+                return;
+            }
+            if (url.pathname === "/api/state") {
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                response.end(JSON.stringify(buildDashboardState(absolute)));
+                return;
+            }
+            if (url.pathname === "/") {
+                response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                response.end(renderDashboardHtml(buildDashboardState(absolute)));
+                return;
+            }
+            response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            response.end("404");
+        }
+        catch (error) {
+            // fail-closed：不泄漏堆栈，只给一条简短原因
+            response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+            response.end(`500: ${error.message.slice(0, 200)}`);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        server.close();
+        throw new Error("UI 服务监听失败。");
+    }
+    return {
+        url: `http://127.0.0.1:${address.port}/`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))),
+    };
+}

package/dist/version.js

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+// src/ 与发布后的 dist/ 共用包根，避免服务端与安装器各自硬编码版本。
+const metadata = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const SERVER_NAME = "pm-mcp";
+export const VERSION = metadata.version;
+export const PACKAGE_SPEC = `${metadata.name}@${VERSION}`;
+export const RUNTIME_CONTRACT = "pagination-evidence-v1";
+// 服务器工具目录契约（doctor 与独立巡检 health-check 都以此核对）。
+// 新增/移除 MCP 工具时必须同步更新这里，并用 `pm-mcp probe` 实测复核。
+export const TOOL_CATALOG_SIZE = 52;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.5",
+  "version": "0.4.0",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",
@@ -32,12 +32,18 @@
   "engines": {
     "node": ">=22.18.0"
   },
+  "pm_mcp": {
+    "acceptance_baseline": {
+      "id": "pm-mcp-local-release",
+      "version": "1.1.0"
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
-    "test": "node --test \"test/*.test.ts\"",
-    "coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 --test-coverage-branches=85 --test-coverage-functions=90 --test \"test/*.test.ts\"",
+    "test": "node --test-concurrency=2 --test \"test/*.test.ts\"",
+    "coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 --test-coverage-branches=85 --test-coverage-functions=90 --test-concurrency=2 --test \"test/*.test.ts\"",
     "audit": "node scripts/health-check.mts",
     "benchmark": "node scripts/benchmark.mts",
     "benchmark:volume": "node scripts/benchmark-volume.mts",
@@ -45,7 +51,7 @@
     "quality:plan": "node scripts/quality-gate.mts --plan",
     "acceptance:evidence": "node scripts/collect-acceptance-evidence.mts --root .",
     "acceptance:prepare": "node scripts/create-pm-acceptance-evaluation.mts --root .",
-    "acceptance": "node scripts/acceptance-gate.mts --root . --baseline-id pm-mcp-local-release --baseline-version 1.0.0 --evaluation .pm/acceptance/evaluations/pm-mcp-local-release-1.0.0.json",
+    "acceptance": "node scripts/acceptance-cycle.mts --root .",
     "acceptance:cycle": "node scripts/acceptance-cycle.mts --root .",
     "gate": "npm run audit -- --root . && npm run quality && npm run acceptance:cycle",
     "start": "node dist/index.js",