agent-method 1.5.12 → 1.5.15

package/lib/mcp-server.js

@@ -14,7 +14,7 @@
  * Uses @modelcontextprotocol/sdk McpServer with stdio transport.
  */
 
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -29,7 +29,25 @@ import {
   resolveCascade,
   validateEntryPoint,
   detectProjectType,
+  routeByQueryType,
 } from "./pipeline.js";
+import { loadDocGraph, resolveDocsMapPath } from "./boundaries.js";
+import { orderByDependencies } from "./dependencies.js";
+
+// Shared CLI helpers for reusing status/scan logic without shelling out
+import {
+  findEntryPoint,
+  readMethodVersion,
+  basename_of,
+  pkg,
+  getPipeline,
+  loadRegistryData,
+} from "./cli/helpers.js";
+import { runCasestudy } from "./cli/casestudy.js";
+import { initProject } from "./init.js";
+import { runClose } from "./cli/close.js";
+import { runAdd } from "./cli/add.js";
+import { runRecord } from "./cli/record.js";
 
 // ---------------------------------------------------------------------------
 // Registry singleton (loaded once at startup)
@@ -230,6 +248,314 @@ export function createServer(registryPath) {
     }
   );
 
+  // -------------------------------------------------------------------------
+  // Helper: parse DOCS-MAP.md for docs_coverage (mirrors cli/docs.js)
+  // -------------------------------------------------------------------------
+
+  function parseDocsMapForMcp(content, projectDir) {
+    const inventory = [];
+    const mappings = [];
+    const scaffolding = [];
+
+    // Docs inventory
+    const invSection = content.match(
+      /## Docs inventory\s*\n[\s\S]*?\n\|[^\n]+\n\|[-| :]+\n((?:\|[^\n]+\n)*)/
+    );
+    if (invSection) {
+      for (const row of invSection[1].trim().split("\n")) {
+        const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+        if (cols.length >= 3 && !cols[0].startsWith("<!--")) {
+          const path = cols[0];
+          const exists = existsSync(join(projectDir, path));
+          inventory.push({
+            path,
+            purpose: cols[1],
+            sources: cols[2],
+            status: cols[3] || (exists ? "active" : "missing"),
+            exists,
+          });
+        }
+      }
+    }
+
+    // Component-to-docs mapping
+    const mapSection = content.match(
+      /## Component-to-docs mapping\s*\n[\s\S]*?\n\|[^\n]+\n\|[-| :]+\n((?:\|[^\n]+\n)*)/
+    );
+    if (mapSection) {
+      for (const row of mapSection[1].trim().split("\n")) {
+        const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+        if (cols.length >= 3 && !cols[0].startsWith("<!--")) {
+          mappings.push({
+            component: cols[0],
+            documentedIn: cols[1],
+            trigger: cols[2],
+          });
+        }
+      }
+    }
+
+    // Scaffolding rules
+    const scaffSection = content.match(
+      /## Scaffolding rules\s*\n[\s\S]*?\n\|[^\n]+\n\|[-| :]+\n((?:\|[^\n]+\n)*)/
+    );
+    if (scaffSection) {
+      for (const row of scaffSection[1].trim().split("\n")) {
+        const cols = row.split("|").map((c) => c.trim()).filter((c) => c);
+        if (cols.length >= 3 && !cols[0].startsWith("<!--")) {
+          scaffolding.push({
+            condition: cols[0],
+            proposedDoc: cols[1],
+            seedFrom: cols[2],
+          });
+        }
+      }
+    }
+
+    const existingDocs = inventory.filter((i) => i.exists).map((i) => i.path);
+    const missingDocs = inventory.filter((i) => !i.exists).map((i) => i.path);
+
+    // Docs on disk but not in inventory (simple heuristic)
+    const docsDir = join(projectDir, "docs");
+    const unmappedDocs = [];
+    if (existsSync(docsDir)) {
+      const inventoryPaths = new Set(inventory.map((i) => i.path));
+      const candidates = ["docs/index.md"];
+      for (const c of candidates) {
+        if (existsSync(join(projectDir, c)) && !inventoryPaths.has(c)) {
+          unmappedDocs.push(c);
+        }
+      }
+    }
+
+    const summary = {
+      totalDocs: inventory.length,
+      existingDocs: existingDocs.length,
+      missingDocs: missingDocs.length,
+      unmappedDocs: unmappedDocs.length,
+      mappedComponents: mappings.length,
+      scaffoldingRules: scaffolding.length,
+    };
+
+    return {
+      inventory,
+      mappings,
+      scaffolding,
+      summary,
+      existingDocs,
+      missingDocs,
+      unmappedDocs,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Tool 1d: docs_coverage — docs coverage + dependency summary (wwa docs --json)
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "docs_coverage",
+    "Show docs coverage report from .context/DOCS-MAP.md and doc-tokens.yaml (MCP equivalent of `wwa docs --json`).",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Project directory containing .context/DOCS-MAP.md"),
+    },
+    async ({ directory }) => {
+      const dir = resolve(directory || ".");
+      const docsMapPath = await resolveDocsMapPath(dir);
+
+      if (!existsSync(docsMapPath)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  error: "No .context/DOCS-MAP.md found",
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      const contentStr = readFileSync(docsMapPath, "utf-8");
+      const report = parseDocsMapForMcp(contentStr, dir);
+
+      // Enrich with dependency graph summary when available
+      const docGraph = await loadDocGraph(dir);
+      if (docGraph && docGraph.nodes && docGraph.edges) {
+        const nodes = docGraph.nodes.length;
+        const edges = docGraph.edges.length;
+        const edgesByType = {};
+        for (const e of docGraph.edges) {
+          edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+        }
+        // Orphans: docs with no edges
+        const connected = new Set();
+        for (const e of docGraph.edges) {
+          connected.add(e.from);
+          connected.add(e.to);
+        }
+        const orphans = docGraph.nodes
+          .filter((n) => !connected.has(n.path))
+          .map((n) => n.path);
+
+        report.dependencyGraph = {
+          nodeCount: nodes,
+          edgeCount: edges,
+          edgesByType,
+          orphanCount: orphans.length,
+          orphans,
+          lastScan: docGraph.last_scan || null,
+          defaultsApplied: docGraph.defaults_applied || null,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                directory: dir,
+                docsMapPath,
+                ...report,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+  // -------------------------------------------------------------------------
+  // Tool 1b: status — methodology version status (wwa status)
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "status",
+    "Check if the project entry point method_version matches the installed wwa version (MCP equivalent of `wwa status`).",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Project directory to scan for entry point"),
+    },
+    async ({ directory }) => {
+      const dir = resolve(directory || ".");
+      const ep = findEntryPoint(dir);
+      if (!ep) {
+        const msg =
+          `No entry point found in ${dir} (looked for CLAUDE.md, .cursorrules, AGENT.md).`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  status: "no_entry_point",
+                  error: msg,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      const epVersion = readMethodVersion(ep);
+      const installed = pkg.version;
+      const installedMajorMinor = installed.split(".").slice(0, 2).join(".");
+
+      let verStatus;
+      let message;
+      if (!epVersion) {
+        verStatus = "no_version";
+        message =
+          `Entry point ${basename_of(ep)} has no method_version setting. ` +
+          `Add 'method_version: ${installedMajorMinor}' to enable version tracking.`;
+      } else if (epVersion === installedMajorMinor) {
+        verStatus = "current";
+        message =
+          `Entry point ${basename_of(ep)} is current ` +
+          `(method_version: ${epVersion}, installed: ${installed}).`;
+      } else {
+        verStatus = "outdated";
+        message =
+          `Entry point ${basename_of(ep)} is outdated ` +
+          `(method_version: ${epVersion}, installed: ${installed}). ` +
+          `Run \`wwa upgrade ${dir}\` to update.`;
+      }
+
+      const result = {
+        directory: dir,
+        entry_point: ep,
+        entry_point_version: epVersion,
+        installed_version: installed,
+        status: verStatus,
+        message,
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 1c: scan_project — project type detection (wwa scan --json, simplified)
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "scan_project",
+    "Detect project type from directory contents (MCP equivalent of `wwa scan --json`, without side effects).",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Directory to analyze"),
+    },
+    async ({ directory }) => {
+      const dir = resolve(directory || ".");
+      const result = detectProjectType(dir);
+
+      const project_type = result.project_type || "general";
+      const friendlyMap = { analytical: "context", mixed: "mix" };
+      const friendly = friendlyMap[project_type] || project_type;
+      const init_command = `wwa init ${friendly}`;
+
+      const output = {
+        directory: dir,
+        project_type,
+        confidence: result.confidence || "unknown",
+        signals: result.signals || [],
+        suggested_init: init_command,
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(output, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
   // -------------------------------------------------------------------------
   // Helper: list_cli_commands — expose CLI command metadata to agents
   // -------------------------------------------------------------------------
@@ -381,6 +707,521 @@ export function createServer(registryPath) {
     }
   );
 
+  // -------------------------------------------------------------------------
+  // Helper: route_by_query_type_for_mcp — shared by routable workflow tools
+  // -------------------------------------------------------------------------
+
+  async function routeByQueryTypeForMcp({
+    queryType,
+    projectType,
+    stage,
+    firstSession,
+    registryPath,
+    directory,
+  }) {
+    const regData = await loadRegistryData(registryPath);
+    const dir = resolve(directory || ".");
+
+    const result = routeByQueryType(
+      queryType,
+      projectType,
+      stage,
+      regData,
+      firstSession || false
+    );
+
+    const docGraph = await loadDocGraph(dir);
+    if (docGraph && result.S4_compute?.read_set) {
+      const orderedReads = orderByDependencies(result.S4_compute.read_set, docGraph);
+      result.S4b_order = {
+        ordered_reads: orderedReads,
+        ordering_source: "doc_graph",
+      };
+    }
+
+    return {
+      directory: dir,
+      query_type: queryType,
+      project_type: projectType,
+      stage,
+      first_session: !!firstSession,
+      S1_classify: result.S1_classify || null,
+      S2_select: result.S2_select || null,
+      S3_resolve: result.S3_resolve || null,
+      S4_compute: result.S4_compute || null,
+      S4b_order: result.S4b_order || null,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Routable workflow tools (Phase 7p)
+  // -------------------------------------------------------------------------
+
+  const ROUTABLE_MCP_TOOLS = [
+    {
+      name: "project_discovery_route",
+      queryType: "project_discovery",
+      description:
+        "Route a project discovery workflow (MCP equivalent of `wwa project-discovery --json`).",
+    },
+    {
+      name: "context_refresh_route",
+      queryType: "context_refresh",
+      description:
+        "Route a context refresh workflow (MCP equivalent of `wwa context-refresh --json`).",
+    },
+    {
+      name: "phase_complete_route",
+      queryType: "phase_completion",
+      description:
+        "Route a phase completion workflow (MCP equivalent of `wwa phase-complete --json`).",
+    },
+    {
+      name: "backlog_route",
+      queryType: "backlog",
+      description:
+        "Route a backlog workflow (MCP equivalent of `wwa backlog --json`).",
+    },
+    {
+      name: "plan_create_route",
+      queryType: "planning",
+      description:
+        "Route a planning workflow (MCP equivalent of `wwa plan-create --json`).",
+    },
+    {
+      name: "dependency_analysis_route",
+      queryType: "dependency_analysis",
+      description:
+        "Route a dependency analysis workflow (MCP equivalent of `wwa dependency-analysis --json`).",
+    },
+    {
+      name: "debt_assessment_route",
+      queryType: "debt_assessment",
+      description:
+        "Route a debt assessment workflow (MCP equivalent of `wwa debt-assessment --json`).",
+    },
+    {
+      name: "docs_update_route",
+      queryType: "docs_update",
+      description:
+        "Route a docs update workflow (MCP equivalent of `wwa docs-update --json`).",
+    },
+    {
+      name: "cross_reference_route",
+      queryType: "cross_reference",
+      description:
+        "Route a cross-reference workflow (MCP equivalent of `wwa cross-reference --json`).",
+    },
+  ];
+
+  for (const { name, queryType, description } of ROUTABLE_MCP_TOOLS) {
+    server.tool(
+      name,
+      description,
+      {
+        project_type: z
+          .enum(["code", "data", "analytical", "mixed", "general"])
+          .default("general")
+          .describe(
+            "Project type: code, data, analytical/context, mixed, general (matches CLI project-type semantics)"
+          ),
+        stage: z
+          .string()
+          .default("scope")
+          .describe("Workflow stage: scope, act, verify (see registry workflows)"),
+        first_session: z
+          .boolean()
+          .default(false)
+          .describe("Force WF-04 bootstrap behavior (first-session workflows)"),
+        registry_path: z
+          .string()
+          .optional()
+          .describe(
+            "Optional path to feature-registry.yaml (defaults to discovery from project root)"
+          ),
+        directory: z
+          .string()
+          .default(".")
+          .describe(
+            "Project directory (used for dependency graph ordering and registry discovery)"
+          ),
+      },
+      async ({ project_type, stage, first_session, registry_path, directory }) => {
+        const routed = await routeByQueryTypeForMcp({
+          queryType,
+          projectType: project_type,
+          stage,
+          firstSession: first_session,
+          registryPath: registry_path,
+          directory,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(routed, null, 2),
+            },
+          ],
+        };
+      }
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Tool (write-safe): casestudy_generate — generate case study artifacts
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "casestudy_generate",
+    "Generate a structured case study from project methodology files (write-safe MCP analog of `wwa casestudy`). Writes only under case-studies/ using safeWriteFile.",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Project directory to analyze"),
+      name: z
+        .string()
+        .optional()
+        .describe("Optional project name override"),
+      yaml_only: z
+        .boolean()
+        .default(false)
+        .describe("If true, write only a .yaml case study (no markdown)"),
+      output: z
+        .string()
+        .optional()
+        .describe(
+          "Optional explicit output path for the primary artifact (YAML or markdown). Default is case-studies/<slug>.{md,yaml}"
+        ),
+      internal_registry: z
+        .boolean()
+        .default(false)
+        .describe("Include docs/internal/doc-registry.yaml data when available"),
+    },
+    async ({ directory, name, yaml_only, output, internal_registry }) => {
+      const dir = resolve(directory || ".");
+      try {
+        const result = await runCasestudy(dir, {
+          name,
+          yamlOnly: yaml_only,
+          output,
+          internalRegistry: internal_registry,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  mode: result.mode,
+                  markdown_path: result.markdownPath || null,
+                  yaml_path: result.yamlPath || null,
+                  sessions: result.sessions,
+                  warnings: result.warnings || [],
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (e) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  error: e.message || "Failed to generate case study",
+                  details: e.details || null,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool (write-safe): init_project — initialize methodology templates
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "init_project",
+    "Initialize a project with wwa methodology templates (write-safe analog of `wwa init` for methodology files). Writes only methodology artifacts plus entry points.",
+    {
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general"])
+        .describe("Project type to initialize"),
+      directory: z
+        .string()
+        .default(".")
+        .describe("Target project directory"),
+      tier: z
+        .enum(["starter", "full"])
+        .default("starter")
+        .describe("Template tier"),
+      runtime: z
+        .enum(["claude", "cursor", "all"])
+        .default("all")
+        .describe("Agent runtime (controls which entry points are kept)"),
+      profile: z
+        .enum(["lite", "standard", "full"])
+        .default("standard")
+        .describe("Integration profile"),
+      onboarding: z
+        .enum(["greenfield", "brownfield", "auto"])
+        .default("auto")
+        .describe("Onboarding scenario"),
+      registry_path: z
+        .string()
+        .optional()
+        .describe("Optional explicit path to feature-registry.yaml"),
+    },
+    async ({
+      project_type,
+      directory,
+      tier,
+      runtime,
+      profile,
+      onboarding,
+      registry_path,
+    }) => {
+      const dir = resolve(directory || ".");
+      try {
+        await initProject(project_type, dir, {
+          tier,
+          runtime,
+          profile,
+          onboarding,
+          registryPath: registry_path,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  project_type,
+                  tier,
+                  runtime,
+                  profile,
+                  onboarding,
+                  ok: true,
+                  note:
+                    "Templates and methodology files created/merged. Inspect entry point and .context/ before first session.",
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (e) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  project_type,
+                  ok: false,
+                  error: e.message || "Failed to initialize project",
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool (write-safe): close_session — run close checklist + write management
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "close_session",
+    "Run session close checklist, update management artifacts, and compute project snapshot (write-safe analog of `wwa close`).",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Project directory"),
+      internal_registry: z
+        .boolean()
+        .default(false)
+        .describe(
+          "Include docs/internal/doc-registry.yaml health when available (same as --internal-registry)"
+        ),
+    },
+    async ({ directory, internal_registry }) => {
+      const dir = resolve(directory || ".");
+      try {
+        const result = await runClose(dir, {
+          internalRegistry: internal_registry,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (e) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  error: e.message || "wwa close failed",
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tools (write-safe): add_* — append structured content via wwa add
+  // -------------------------------------------------------------------------
+
+  const ADD_MCP_TOOLS = [
+    { name: "add_backlog", type: "backlog" },
+    { name: "add_decision", type: "decision" },
+    { name: "add_finding", type: "finding" },
+    { name: "add_session", type: "session" },
+    { name: "add_summary", type: "summary" },
+  ];
+
+  for (const { name, type } of ADD_MCP_TOOLS) {
+    server.tool(
+      name,
+      `Append ${type} content to methodology files (write-safe analog of \`wwa add ${type}\`).`,
+      {
+        directory: z
+          .string()
+          .default(".")
+          .describe("Project directory"),
+        content: z
+          .string()
+          .describe(
+            type === "decision"
+              ? "Decision text; use 'Decision | Rationale' to include rationale"
+              : "Content to append"
+          ),
+        dry_run: z
+          .boolean()
+          .default(false)
+          .describe("If true, do not write — just return target and content"),
+      },
+      async ({ directory, content, dry_run }) => {
+        const dir = resolve(directory || ".");
+        try {
+          const result = await runAdd(type, content, {
+            directory: dir,
+            dryRun: dry_run,
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+              },
+            ],
+          };
+        } catch (e) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    directory: dir,
+                    type,
+                    error: e.message || "wwa add failed",
+                    code: e.code || null,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+          };
+        }
+      }
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Tool (write-safe): record_last_cli_run — append last CLI run to SESSION-LOG
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "record_last_cli_run",
+    "Record the last CLI run summary to SESSION-LOG.md (write-safe analog of `wwa record`).",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Project directory"),
+      dry_run: z
+        .boolean()
+        .default(false)
+        .describe("If true, do not write — just return target and block"),
+    },
+    async ({ directory, dry_run }) => {
+      const dir = resolve(directory || ".");
+      try {
+        const result = await runRecord(dir, { dryRun: dry_run });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (e) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  directory: dir,
+                  error: e.message || "wwa record failed",
+                  code: e.code || null,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    }
+  );
+
   // -------------------------------------------------------------------------
   // Tool 5: check_capability — model tier query
   // -------------------------------------------------------------------------