mcp-probe-kit 3.6.10 → 3.6.11

package/README.md

@@ -23,6 +23,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/mcp-probe-kit.svg)](https://www.npmjs.com/package/mcp-probe-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/mybolide/mcp-probe-kit.svg)](https://github.com/mybolide/mcp-probe-kit/stargazers)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/ce79a9e5-7422-4862-b235-bc3d65710397)
 
 > 🚀 AI-Powered Complete Development Toolkit - Covering the Entire Development Lifecycle
 
@@ -91,11 +92,16 @@ All hard quality rules live in one module (`src/lib/quality-constraints.ts`) and
 - Graph snapshots are persisted to `.mcp-probe-kit/graph-snapshots` (customizable via `MCP_GRAPH_SNAPSHOT_DIR`)
 - Tool responses include `_meta.graph` with snapshot URI and local JSON/Markdown file paths
 
-### 🐛 TBP 8-Step RCA for Bug Workflows
+### 🐛 SRC-8 Bug Root-Cause Workflow (TBP-Inspired)
 
-- `start_bugfix` defaults to Toyota-style TBP 8-step root-cause analysis before repair
-- `fix_bug` returns a structured TBP skeleton covering phenomenon, timeline, ruled-out paths, boundary, root cause, evidence, and repair plan
-- This makes bug, regression, anomaly, and "why didn't it work" investigations follow analyze-first discipline instead of patching symptoms
+- **[SRC-8 Methodology](docs/src8-methodology.md)** (中文: [src8-methodology.zh-CN.md](docs/src8-methodology.zh-CN.md)) — Software Root-Cause 8-step protocol inspired by Toyota TBP / PDCA, adapted for code and AI agents
+- `start_bugfix` runs graph narrowing, then **delegated SRC-8 plan** (`metadata.plan.steps` src8-1~8) before repair and tests
+- `fix_bug` returns **delegated plan** (src8-1~8), `src8Checklist`, **`rootCauseWorksheet`** (Step 4 core), and hard gates (no code change until root-cause worksheet is closed)
+- Highlights vs manufacturing TBP: **repro contract**, **attribution layers** (including `agent_behavior`), **contributing factors**, **memorize_asset** for cross-repo learning
+
+**Inherited from Toyota TBP:** gap thinking, Plan-before-Do, no skipping to root-cause analysis, fact-based investigation, countermeasures over symptoms, evaluate then standardize.
+
+**Our elevation:** genchi-genbutsu → read code/logs/repro; Step 4 worksheet; guidance-only MCP that forces discipline while the Agent executes.
 
 ### 🧠 Memory Retrieval
 
@@ -301,7 +307,7 @@ This mode performs 1-2 rounds of structured clarification before entering spec/f
 
 6 intelligent orchestration tools that automatically combine multiple basic tools for one-click complex development workflows:
 - `start_feature` - New feature development (Requirements → Design → Estimation)
-- `start_bugfix` - Bug fixing (TBP 8-step RCA → Fix → Testing)
+- `start_bugfix` - Bug fixing (SRC-8 RCA → Fix → Testing)
 - `start_onboard` - Project onboarding (Generate project context docs)
 - `start_ui` - UI development (Design system → Components → Code)
 - `start_product` - Product design (PRD → Prototype → Design system → HTML)
@@ -386,8 +392,8 @@ This ensures `start_ui` can generate professional-grade UI code even offline.
 |---------|-----------------|--------|
 | Develop new feature (complete flow) | `start_feature` | Auto-complete: spec→estimation |
 | Only need feature spec docs | `add_feature` | More lightweight, only generates docs |
-| Fix bug (complete flow) | `start_bugfix` | Root-cause-first flow: TBP RCA → fix → test |
-| Only need bug analysis | `fix_bug` | TBP 8-step RCA only, without full orchestration |
+| Fix bug (complete flow) | `start_bugfix` | Delegated SRC-8 plan (src8-1~8) → fix → test → memorize |
+| Only need bug analysis | `fix_bug` | Delegated SRC-8 plan + root-cause worksheet (methodology: [docs](docs/src8-methodology.md)) |
 | Generate design system | `ui_design_system` | Directly generate design specs |
 | Develop UI components | `start_ui` | Complete flow: design→components→code |
 | Product design (requirements to prototype) | `start_product` | One-click: PRD→prototype→HTML |

package/build/index.js

@@ -17,6 +17,12 @@ import { ensureMcpProbeKitBootstrapForToolCall, } from "./lib/workflow-skill-ins
 import { resolveWorkspaceRoot, resolveWorkspaceRootWithMeta } from "./lib/workspace-root.js";
 import { PROJECT_BOOTSTRAP_URI, discoverProjectResources, readProjectResourceContent, } from "./lib/project-mcp-resources.js";
 import { isAbortError, } from "./lib/tool-execution-context.js";
+/** 启动日志标识：用于确认 Cursor 是否加载了当前 build（非 npm/npx 缓存旧进程） */
+const MCP_BUILD_TAG = "progress-off-20260710";
+function isProgressNotificationEnabled() {
+    const raw = (process.env.MCP_PROGRESS_NOTIFICATIONS ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
 const EXTENSIONS_CAPABILITY_KEY = "io.github.mybolide/extensions";
 const MAX_UI_APP_RESOURCES = 30;
 const MAX_GRAPH_SNAPSHOTS = 20;
@@ -566,7 +572,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     if (shouldAutoEscalateToTask(name, Boolean(taskRequest))) {
         taskRequest = taskRequest ?? {};
     }
-    const emitProgress = async (progress, message) => {
+    const emitProgress = async (_progress, _message) => {
+        // Cursor Shared MCP 在工具响应返回后会立即注销 progressToken；
+        // 迟到的 notifications/progress 会导致整连接 error（unknown token）。
+        // 默认关闭；需要时可设 MCP_PROGRESS_NOTIFICATIONS=1。
+        if (!isProgressNotificationEnabled()) {
+            return;
+        }
         const progressToken = extra._meta?.progressToken;
         if (progressToken === undefined) {
             return;
@@ -576,9 +588,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
                 method: "notifications/progress",
                 params: {
                     progressToken,
-                    progress,
+                    progress: _progress,
                     total: 100,
-                    message,
+                    message: _message,
                     ...(traceMeta === undefined
                         ? {}
                         : {
@@ -634,7 +646,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         // 后台执行任务，不阻塞当前请求，立即返回 taskId 给客户端轮询。
         void (async () => {
             try {
-                await taskContext.reportProgress?.(5, `开始执行工具: ${name}`);
                 const { bootstrap, result: rawResult } = await executeTool(name, args, taskContext);
                 if (!rawResult || typeof rawResult !== "object") {
                     throw new Error(`工具 ${name} 返回了无效响应`);
@@ -689,23 +700,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     };
     try {
         ensureNotAborted();
-        await emitProgress(5, `开始执行工具: ${name}`);
         const { bootstrap, result: rawResult } = await executeTool(name, args, toolContext);
         if (!rawResult || typeof rawResult !== "object") {
             throw new Error(`工具 ${name} 返回了无效响应`);
         }
         ensureNotAborted();
         const result = decorateResult(name, args, rawResult, traceMeta, bootstrap);
-        await emitProgress(100, `工具执行完成: ${name}`);
         return result;
     }
     catch (error) {
-        if (extra.signal.aborted) {
-            await emitProgress(100, `工具执行已取消: ${name}`);
-        }
-        else {
-            await emitProgress(100, `工具执行失败: ${name}`);
-        }
         const errorMessage = error instanceof Error ? error.message : String(error);
         return withTraceMeta(makeToolError(errorMessage), traceMeta);
     }
@@ -1000,7 +1003,7 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const workspaceMeta = resolveWorkspaceRootWithMeta("");
-    console.error(`MCP Probe Kit v${VERSION} 已启动 | workspace=${workspaceMeta.root} | source=${workspaceMeta.source}`);
+    console.error(`MCP Probe Kit v${VERSION} 已启动 | build=${MCP_BUILD_TAG} | workspace=${workspaceMeta.root} | source=${workspaceMeta.source}`);
     if (workspaceMeta.warning) {
         console.error(`[MCP Probe Kit] ${workspaceMeta.warning}`);
     }

package/build/lib/__tests__/src8-guidance.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/src8-guidance.unit.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { ATTRIBUTION_LAYERS, buildRootCauseWorksheet, buildSrc8Checklist, buildSrc8DelegatedPlan, buildSrc8EvidenceFromInput, mergeBugfixOrchestrationPlan, renderSrc8GateRules, renderTbpInspirationSection, resolveAnalysisMode, } from "../../lib/src8-guidance.js";
+describe("src8-guidance 单元测试", () => {
+    test("buildSrc8Checklist 为 8 步且 Step 4 为 root_cause", () => {
+        const checklist = buildSrc8Checklist();
+        expect(checklist).toHaveLength(8);
+        expect(checklist[0].id).toBe("clarify_gap");
+        expect(checklist[3].id).toBe("root_cause");
+        expect(checklist[3].inspiredByTbpStep).toBe(4);
+        expect(checklist.every((item) => item.inspiredByTbpStep >= 1)).toBe(true);
+    });
+    test("buildRootCauseWorksheet 含 4a~4e 子步", () => {
+        const ws = buildRootCauseWorksheet({ hasComparisonSample: false });
+        expect(ws.substeps.map((s) => s.id)).toEqual(["4a", "4b", "4c", "4d", "4e"]);
+        expect(ws.template.evidenceGaps.length).toBeGreaterThan(0);
+    });
+    test("归因层含 agent_behavior", () => {
+        expect(ATTRIBUTION_LAYERS.some((l) => l.id === "agent_behavior")).toBe(true);
+    });
+    test("renderTbpInspirationSection 说明借鉴关系", () => {
+        const text = renderTbpInspirationSection();
+        expect(text).toMatch(/丰田 TBP/);
+        expect(text).toMatch(/不是.*逐字翻译/);
+    });
+    test("resolveAnalysisMode 兼容 tbp8 别名", () => {
+        expect(resolveAnalysisMode("tbp8")).toBe("src8");
+        expect(resolveAnalysisMode("src8")).toBe("src8");
+    });
+    test("renderSrc8GateRules 强调 Step 4 工作表", () => {
+        expect(renderSrc8GateRules()).toMatch(/rootCauseWorksheet|真因工作表/);
+    });
+    test("buildSrc8EvidenceFromInput 支持验收目标", () => {
+        const evidence = buildSrc8EvidenceFromInput({
+            error_message: "err",
+            verification_target: "test green",
+        });
+        expect(evidence.some((e) => e.source === "verification_target")).toBe(true);
+    });
+    test("buildSrc8DelegatedPlan 产出 8 步 delegated plan", () => {
+        const plan = buildSrc8DelegatedPlan({ error_message: "boom" });
+        expect(plan.mode).toBe("delegated");
+        expect(plan.steps.map((s) => s.id)).toEqual([
+            "src8-1",
+            "src8-2",
+            "src8-3",
+            "src8-4",
+            "src8-5",
+            "src8-6",
+            "src8-7",
+            "src8-8",
+        ]);
+        expect(plan.steps.find((s) => s.id === "src8-4")?.dependsOn).toContain("src8-3");
+    });
+    test("mergeBugfixOrchestrationPlan 可前置上下文步骤", () => {
+        const plan = mergeBugfixOrchestrationPlan({
+            src8Input: { error_message: "err" },
+            preambleSteps: [{ id: "context", tool: "init_project_context", outputs: [] }],
+        });
+        expect(plan.steps[0].id).toBe("context");
+        expect(plan.steps.some((s) => s.id === "src8-1")).toBe(true);
+    });
+});

package/build/lib/code-review-input.d.ts

@@ -0,0 +1,15 @@
+export type GuidanceCodeInput = {
+    code?: string;
+    filePath?: string;
+    projectRoot?: string;
+};
+export type GuidanceCodeResolved = {
+    code: string;
+    file?: string;
+    error?: string;
+};
+/** 解析指南型工具的代码输入：优先 inline code，否则从 file_path 读取 */
+export declare function resolveGuidanceCode(input: GuidanceCodeInput): GuidanceCodeResolved;
+export declare function resolveReviewCode(input: GuidanceCodeInput): GuidanceCodeResolved;
+export declare function trimCodeForPrompt(code: string, maxChars?: number, inputKey?: string): string;
+export declare function trimReviewCodeForPrompt(code: string, maxChars?: number): string;

package/build/lib/code-review-input.js

@@ -0,0 +1,47 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** 解析指南型工具的代码输入：优先 inline code，否则从 file_path 读取 */
+export function resolveGuidanceCode(input) {
+    return resolveReviewCode(input);
+}
+export function resolveReviewCode(input) {
+    const inline = input.code?.trim() ?? "";
+    if (inline) {
+        return { code: inline, file: input.filePath?.trim() || undefined };
+    }
+    const filePath = input.filePath?.trim();
+    if (!filePath) {
+        return { code: "" };
+    }
+    const resolved = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(input.projectRoot?.trim() || process.cwd(), filePath);
+    if (!fs.existsSync(resolved)) {
+        return { code: "", file: filePath, error: `文件不存在: ${resolved}` };
+    }
+    try {
+        const stat = fs.statSync(resolved);
+        if (!stat.isFile()) {
+            return { code: "", file: filePath, error: `不是文件: ${resolved}` };
+        }
+        return {
+            code: fs.readFileSync(resolved, "utf-8"),
+            file: filePath,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { code: "", file: filePath, error: `读取文件失败: ${message}` };
+    }
+}
+export function trimCodeForPrompt(code, maxChars = 24000, inputKey = "reviewInput") {
+    if (code.length <= maxChars) {
+        return code;
+    }
+    const head = Math.floor(maxChars * 0.7);
+    const tail = maxChars - head - 80;
+    return `${code.slice(0, head)}\n\n/* ... [已截断，完整内容见 structuredContent.${inputKey}.code] ... */\n\n${code.slice(-tail)}`;
+}
+export function trimReviewCodeForPrompt(code, maxChars = 24000) {
+    return trimCodeForPrompt(code, maxChars, "reviewInput");
+}

package/build/lib/src8-guidance.d.ts

@@ -0,0 +1,178 @@
+/**
+ * SRC-8（Software Root-Cause 8-step）
+ *
+ * 面向软件与 Agent 的真因分析协议，受丰田 TBP（Toyota Business Practice）八步法与 PDCA 启发，
+ * 但使用代码世界的语言（复现、分层、贡献因子、测试契约、记忆沉淀）。
+ *
+ * @see docs/src8-methodology.md
+ * @see docs/src8-methodology.zh-CN.md
+ */
+export declare const SRC8_METHODOLOGY: "src8";
+/** @deprecated 使用 src8；保留兼容旧调用方 */
+export declare const TBP8_ALIAS: "tbp8";
+export type Src8StepId = "clarify_gap" | "narrow_boundary" | "acceptance_contract" | "root_cause" | "countermeasures" | "implement" | "evaluate" | "standardize";
+export type PdcaPhase = "plan" | "do" | "check" | "act";
+export type AttributionLayer = "code" | "runtime" | "data_contract" | "integration" | "agent_behavior" | "environment";
+export declare const ATTRIBUTION_LAYERS: Array<{
+    id: AttributionLayer;
+    label: string;
+    hint: string;
+}>;
+export type Src8ChecklistItem = {
+    step: number;
+    id: Src8StepId;
+    title: string;
+    pdca: PdcaPhase;
+    status: "pending" | "agent_must_complete";
+    question: string;
+    techniques: string[];
+    antiPatterns: string[];
+    /** 借鉴自丰田 TBP 的对应步骤（1-8） */
+    inspiredByTbpStep: number;
+    schemaFields?: string[];
+};
+export declare const SRC8_STEPS: Omit<Src8ChecklistItem, "status">[];
+export declare const ROOT_CAUSE_WORKSHEET_GATES: {
+    readonly minHypotheses: 2;
+    readonly minRuledOutWithEvidence: 2;
+    readonly minWhyLevels: 3;
+    readonly requireEvidenceGapsIfNoComparison: true;
+    readonly blockCountermeasuresIfConfidenceLow: true;
+    readonly symptomOnlyPatterns: readonly [RegExp, RegExp, RegExp, RegExp];
+};
+export type RootCauseWorksheetSubstep = {
+    id: "4a" | "4b" | "4c" | "4d" | "4e";
+    title: string;
+    status: "agent_must_complete";
+    description: string;
+};
+export declare function buildSrc8Checklist(): Src8ChecklistItem[];
+export declare function buildRootCauseWorksheetSubsteps(): RootCauseWorksheetSubstep[];
+export declare function buildRootCauseWorksheet(input: {
+    hasComparisonSample: boolean;
+}): {
+    step: number;
+    title: string;
+    substeps: RootCauseWorksheetSubstep[];
+    gates: {
+        readonly minHypotheses: 2;
+        readonly minRuledOutWithEvidence: 2;
+        readonly minWhyLevels: 3;
+        readonly requireEvidenceGapsIfNoComparison: true;
+        readonly blockCountermeasuresIfConfidenceLow: true;
+        readonly symptomOnlyPatterns: readonly [RegExp, RegExp, RegExp, RegExp];
+    };
+    agentMustProduce: string;
+    template: {
+        mode: "simple" | "complex" | null;
+        attributionLayer: AttributionLayer | null;
+        hypotheses: Array<{
+            id: string;
+            statement: string;
+            attributionLayer?: AttributionLayer;
+            status: "ruled_out" | "pending" | "confirmed";
+            evidence: string[];
+            counterEvidence: string[];
+        }>;
+        forkPoint: string | null;
+        whyChain: Array<{
+            level: number;
+            observation: string;
+            why: string;
+            because: string;
+        }>;
+        primaryCause: string | null;
+        contributingFactors: string[];
+        rootCauseStatement: string | null;
+        confidence: "high" | "medium" | "low" | null;
+        evidenceGaps: string[];
+    };
+};
+export declare function renderTbpInspirationSection(): string;
+export declare function renderSrc8PdcaMap(): string;
+export declare function renderAttributionLayersMarkdown(): string;
+export declare function renderRootCauseWorksheetMarkdown(): string;
+/** Agent 用：可执行清单，不含 TBP 渊源长文（详见 docs/src8-methodology*.md） */
+export declare function renderSrc8AgentChecklistMarkdown(): string;
+/** 文档/完整版：含 TBP 步骤对照标注 */
+export declare function renderSrc8ChecklistMarkdown(): string;
+export declare function renderSrc8GateRules(): string;
+export declare function renderReproductionGate(): string;
+export declare function renderSrc8AgentOutputFormat(): string;
+export type Src8InputEvidence = {
+    type: "symptom" | "timeline" | "stack" | "code" | "comparison";
+    detail: string;
+    source: string;
+};
+export type Src8ExecutionPlanStep = {
+    id: string;
+    tool?: string;
+    action?: string;
+    args?: Record<string, unknown>;
+    outputs?: string[];
+    when?: string;
+    dependsOn?: string[];
+    note?: string;
+};
+export type Src8ExecutionPlan = {
+    mode: "delegated";
+    methodology: typeof SRC8_METHODOLOGY;
+    steps: Src8ExecutionPlanStep[];
+};
+export type BuildSrc8DelegatedPlanInput = {
+    error_message: string;
+    stack_trace?: string;
+    analysis_mode?: string;
+    code_context?: string;
+    project_root?: string;
+    file_path?: string;
+    /** 默认 true；start_bugfix 外层若单独编排可设为 false */
+    includeGentest?: boolean;
+    includeMemorize?: boolean;
+};
+export declare function buildSrc8DelegatedPlan(input: BuildSrc8DelegatedPlanInput): Src8ExecutionPlan;
+export type MergeBugfixOrchestrationPlanInput = {
+    src8Input: BuildSrc8DelegatedPlanInput;
+    preambleSteps?: Src8ExecutionPlanStep[];
+    appendSteps?: Src8ExecutionPlanStep[];
+    /** 为 true 时不在 src8 内嵌 memorize，由 appendSteps 提供 */
+    deferMemorize?: boolean;
+};
+/** start_bugfix / loop 外层：上下文步骤 + SRC-8 八步 + 可选闸门/记忆 */
+export declare function mergeBugfixOrchestrationPlan(input: MergeBugfixOrchestrationPlanInput): Src8ExecutionPlan;
+export declare function renderSrc8PlanSummaryMarkdown(plan: Src8ExecutionPlan): string;
+export declare function buildSrc8EvidenceFromInput(input: {
+    error_message: string;
+    stack_trace?: string;
+    code_context?: string;
+    steps_to_reproduce?: string;
+    expected_behavior?: string;
+    actual_behavior?: string;
+    success_sample?: string;
+    verification_target?: string;
+}): Src8InputEvidence[];
+export declare function renderFixBugAgentPromptBody(sections: {
+    error_message: string;
+    stack_trace_section: string;
+    reproduce_section: string;
+    behavior_section: string;
+    comparison_section: string;
+    verification_target_section: string;
+    code_context_section: string;
+    plan: Src8ExecutionPlan;
+}): string;
+/** @deprecated 使用 renderFixBugAgentPromptBody；完整 TBP 对照版见 docs */
+export declare function renderFixBugPromptBody(sections: Parameters<typeof renderFixBugAgentPromptBody>[0]): string;
+export declare function resolveAnalysisMode(raw?: string): typeof SRC8_METHODOLOGY;
+export declare const TBP8_STEPS: Omit<Src8ChecklistItem, "status">[];
+export type TbpStepId = Src8StepId;
+export type TbpChecklistItem = Src8ChecklistItem;
+export declare const buildTbpChecklist: typeof buildSrc8Checklist;
+export declare const buildTbpEvidenceFromInput: typeof buildSrc8EvidenceFromInput;
+export declare const renderTbpPdcaMap: typeof renderSrc8PdcaMap;
+export declare const renderTbpChecklistMarkdown: typeof renderSrc8ChecklistMarkdown;
+export declare const renderTbpGateRules: typeof renderSrc8GateRules;
+export declare const renderTbpReproductionGate: typeof renderReproductionGate;
+export declare const renderTbpAgentOutputFormat: typeof renderSrc8AgentOutputFormat;
+export declare const renderTbpFiveWhyTemplate: () => string;
+export declare const renderTbpBugInfoSections: typeof renderFixBugPromptBody;