agent-method 1.5.12

package/lib/mcp-server.js

@@ -0,0 +1,612 @@
+/**
+ * MCP server — exposes methodology pipeline and registry as agent-callable tools.
+ *
+ * 8 tools:
+ *   route_query          S1-S5  End-to-end query routing
+ *   validate_entry_point S7     Entry point validation
+ *   detect_project       S8     Project type detection
+ *   resolve_cascade      S5     Cascade chain resolution
+ *   check_capability     Registry  Model tier capability check
+ *   lookup_feature       Registry  Feature lookup by ID or keyword
+ *   list_workflows       Registry  List available workflows
+ *   refactor_markdown    CTX-06    Markdown scale analysis
+ *
+ * Uses @modelcontextprotocol/sdk McpServer with stdio transport.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { loadRegistry, getFeatures, getWorkflows, getVersion } from "./registry.js";
+import {
+  classify,
+  selectWorkflow,
+  resolveFeatures,
+  computeFileSets,
+  resolveCascade,
+  validateEntryPoint,
+  detectProjectType,
+} from "./pipeline.js";
+
+// ---------------------------------------------------------------------------
+// Registry singleton (loaded once at startup)
+// ---------------------------------------------------------------------------
+
+let _registry = null;
+
+function registry(registryPath) {
+  if (!_registry) {
+    _registry = loadRegistry(registryPath || undefined);
+  }
+  return _registry;
+}
+
+// ---------------------------------------------------------------------------
+// Capability tiers — maps model tiers to supported feature domains
+// ---------------------------------------------------------------------------
+
+const TIER_CAPABILITIES = {
+  lite: {
+    supported_domains: ["CTX", "QRY", "STT"],
+    max_features: 12,
+    notes: "Haiku-class models. Core context and query routing only.",
+  },
+  standard: {
+    supported_domains: ["CTX", "QRY", "STT", "TSK", "HAI", "TPL"],
+    max_features: 24,
+    notes: "Sonnet-class models. Full methodology minus exploration/discovery.",
+  },
+  full: {
+    supported_domains: ["CTX", "QRY", "STT", "TSK", "HAI", "TPL", "EXP", "SCAN"],
+    max_features: 32,
+    notes: "Opus-class models. Complete methodology surface area.",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Markdown analysis helpers (CTX-06 scale management)
+// ---------------------------------------------------------------------------
+
+const SCALE_THRESHOLD = 300;
+
+function analyzeMarkdown(filePath) {
+  const absPath = resolve(filePath);
+  let content;
+  try {
+    content = readFileSync(absPath, "utf-8");
+  } catch {
+    return { error: `File not found: ${filePath}` };
+  }
+
+  const lines = content.split("\n");
+  const lineCount = lines.length;
+  const overThreshold = lineCount > SCALE_THRESHOLD;
+
+  // Parse sections by headings
+  const sections = [];
+  let currentSection = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^(#{1,4})\s+(.+)/);
+    if (match) {
+      if (currentSection) {
+        currentSection.end_line = i;
+        currentSection.line_count = currentSection.end_line - currentSection.start_line;
+        sections.push(currentSection);
+      }
+      currentSection = {
+        level: match[1].length,
+        title: match[2].trim(),
+        start_line: i + 1,
+        end_line: null,
+        line_count: 0,
+      };
+    }
+  }
+  if (currentSection) {
+    currentSection.end_line = lines.length;
+    currentSection.line_count = currentSection.end_line - currentSection.start_line;
+    sections.push(currentSection);
+  }
+
+  const result = {
+    file: filePath,
+    line_count: lineCount,
+    threshold: SCALE_THRESHOLD,
+    over_threshold: overThreshold,
+    sections,
+  };
+
+  // Generate split plan only if over threshold
+  if (overThreshold) {
+    const topSections = sections.filter((s) => s.level <= 2);
+    const splitCandidates = topSections
+      .filter((s) => s.line_count > 30)
+      .sort((a, b) => b.line_count - a.line_count);
+
+    result.split_plan = {
+      strategy: "index_plus_components",
+      description:
+        "Split into index file (navigation + active content) and components subdirectory (archived sections grouped by semantic boundary).",
+      candidates: splitCandidates.map((s) => ({
+        section: s.title,
+        lines: s.line_count,
+        recommendation: s.line_count > 100 ? "extract to component" : "consider extracting",
+      })),
+      estimated_index_lines: lineCount - splitCandidates.reduce((sum, s) => sum + s.line_count, 0),
+    };
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// CLI command metadata helper (docs/internal/cli-commands.yaml)
+// ---------------------------------------------------------------------------
+
+function loadCliCommandsMetadata() {
+  try {
+    // Use require here to avoid converting this file to ESM.
+    // eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
+    const yaml = require("js-yaml");
+    const cliPath = join(process.cwd(), "docs", "internal", "cli-commands.yaml");
+    const raw = readFileSync(cliPath, "utf-8");
+    const parsed = yaml.load(raw);
+    if (!parsed || !Array.isArray(parsed.cli_commands)) {
+      return { error: "cli-commands.yaml missing cli_commands array" };
+    }
+    return { version: parsed.version || null, commands: parsed.cli_commands };
+  } catch (e) {
+    return { error: `Unable to load CLI command metadata: ${e.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server creation
+// ---------------------------------------------------------------------------
+
+export function createServer(registryPath) {
+  const reg = registry(registryPath);
+  const version = getVersion(reg);
+
+  const server = new McpServer({
+    name: "wwa",
+    version: version,
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool 1: route_query — end-to-end pipeline (S1-S5)
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "route_query",
+    "Route a natural language query through the methodology pipeline (S1-S5). Returns query classification, workflow selection, resolved features, and computed read/write file sets.",
+    {
+      query: z.string().describe("The natural language query to route"),
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general"])
+        .default("general")
+        .describe("Project type for context-aware routing"),
+      stage: z
+        .string()
+        .default("scope")
+        .describe("Pipeline stage: scope, act, or verify"),
+    },
+    async ({ query, project_type, stage }) => {
+      const classification = classify(query, project_type, reg);
+      const selection = selectWorkflow(classification.query_type, project_type);
+      const resolution = resolveFeatures(selection.workflow_id, stage, reg);
+      const fileSets = computeFileSets(resolution.features, classification.query_type, reg);
+      const cascade = resolveCascade([], null, project_type === "general" ? "universal" : project_type);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                query,
+                project_type,
+                stage,
+                query_type: classification.query_type,
+                confidence: classification.confidence,
+                matched: classification.matched,
+                workflow: selection,
+                features: resolution.features,
+                feature_source: resolution.source,
+                read_set: fileSets.read_set,
+                write_set: fileSets.write_set,
+                cascade: cascade,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Helper: list_cli_commands — expose CLI command metadata to agents
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "list_cli_commands",
+    "List wwa CLI commands from docs/internal/cli-commands.yaml so agents can safely discover and use them.",
+    {
+      category: z
+        .enum([
+          "setup",
+          "workflow",
+          "routable",
+          "add",
+          "analysis",
+          "pipeline",
+          "server",
+          "completion",
+          "any",
+        ])
+        .default("any")
+        .describe("Filter commands by category (or 'any' for all)."),
+      safe_only: z
+        .boolean()
+        .default(true)
+        .describe("If true, only return commands marked safe_for_agent."),
+    },
+    async ({ category, safe_only }) => {
+      const meta = loadCliCommandsMetadata();
+      if (meta.error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: meta.error }, null, 2),
+            },
+          ],
+        };
+      }
+
+      let commands = meta.commands;
+      if (category !== "any") {
+        commands = commands.filter((c) => c.category === category);
+      }
+      if (safe_only) {
+        commands = commands.filter((c) => c.safe_for_agent);
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                version: meta.version,
+                count: commands.length,
+                commands,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 2: validate_entry_point — S7 validation
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "validate_entry_point",
+    "Validate an entry point file (CLAUDE.md, .cursorrules, AGENT.md) against the methodology registry. Checks scoping coverage, cascade completeness, convention coverage, workflow references, and scale management.",
+    {
+      file_path: z.string().describe("Path to the entry point file"),
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general"])
+        .default("general")
+        .describe("Project type for validation context"),
+    },
+    async ({ file_path, project_type }) => {
+      const result = validateEntryPoint(file_path, project_type, reg);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 3: detect_project — S8 detection
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "detect_project",
+    "Detect project type from directory contents. Analyzes file patterns, extensions, and directory structure to classify a project as code, data, analytical, mixed, or general.",
+    {
+      directory: z
+        .string()
+        .default(".")
+        .describe("Directory to analyze"),
+    },
+    async ({ directory }) => {
+      const result = detectProjectType(directory);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 4: resolve_cascade — S5 cascade resolution
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "resolve_cascade",
+    "Resolve the dependency cascade chain for a given trigger. Returns which files need updating when a specific change occurs (e.g., phase_completion, requirements_change, file_split).",
+    {
+      trigger: z
+        .string()
+        .describe(
+          "Cascade trigger: phase_completion, requirements_change, new_decision, open_question_resolved, project_structure, new_domain, file_exceeds_300_lines, file_split, database_schema, api_route, new_module, schema_change, pipeline_stage, etc."
+        ),
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "universal"])
+        .default("universal")
+        .describe("Project type determines which cascade tables are included"),
+    },
+    async ({ trigger, project_type }) => {
+      const cascadeContext = project_type === "general" ? "universal" : project_type;
+      const result = resolveCascade([], trigger, cascadeContext);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                trigger,
+                project_type,
+                cascade_chain: result.cascade_files,
+                depth: result.depth,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 5: check_capability — model tier query
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "check_capability",
+    "Check whether a model tier supports a specific feature. Returns support status and recommendations for the given model tier (lite/standard/full).",
+    {
+      model_tier: z
+        .enum(["lite", "standard", "full"])
+        .describe("Model tier: lite (Haiku), standard (Sonnet), full (Opus)"),
+      feature_id: z
+        .string()
+        .describe("Feature ID to check (e.g., CTX-01, EXP-03, SCAN-02)"),
+    },
+    async ({ model_tier, feature_id }) => {
+      const tier = TIER_CAPABILITIES[model_tier];
+      const features = getFeatures(reg);
+      const feature = features[feature_id];
+
+      if (!feature) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  feature_id,
+                  error: `Feature not found: ${feature_id}`,
+                  available_features: Object.keys(features),
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      const domain = feature_id.split("-")[0];
+      const supported = tier.supported_domains.includes(domain);
+
+      const recommendations = [];
+      if (!supported) {
+        recommendations.push(
+          `Feature ${feature_id} (domain: ${domain}) is not supported at ${model_tier} tier.`
+        );
+        const requiredTier = Object.entries(TIER_CAPABILITIES).find(([, t]) =>
+          t.supported_domains.includes(domain)
+        );
+        if (requiredTier) {
+          recommendations.push(`Minimum tier required: ${requiredTier[0]}`);
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                feature_id,
+                feature_name: feature.name,
+                domain,
+                model_tier,
+                supported,
+                tier_info: tier,
+                recommendations,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 6: lookup_feature — registry feature lookup
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "lookup_feature",
+    "Look up a feature by ID or search by keyword. Returns the full feature specification including domain, reads, writes, and dependencies.",
+    {
+      query: z
+        .string()
+        .describe("Feature ID (e.g., CTX-01) or keyword to search for"),
+    },
+    async ({ query }) => {
+      const features = getFeatures(reg);
+      const queryUpper = query.toUpperCase();
+
+      // Direct ID match
+      if (features[queryUpper]) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { match: "exact", feature: features[queryUpper] },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      // Keyword search
+      const queryLower = query.toLowerCase();
+      const matches = [];
+      for (const [id, feat] of Object.entries(features)) {
+        const searchable = `${id} ${feat.name || ""} ${feat.domain || ""}`.toLowerCase();
+        if (searchable.includes(queryLower)) {
+          matches.push({ id, ...feat });
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                match: matches.length > 0 ? "keyword" : "none",
+                query,
+                results: matches,
+                total_features: Object.keys(features).length,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 7: list_workflows — registry workflow listing
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "list_workflows",
+    "List all available methodology workflows, optionally filtered by project type. Returns workflow IDs, names, steps, and applicability.",
+    {
+      project_type: z
+        .enum(["code", "data", "analytical", "mixed", "general", "all"])
+        .default("all")
+        .describe("Filter workflows by project type, or 'all' for complete list"),
+    },
+    async ({ project_type }) => {
+      const workflows = getWorkflows(reg);
+      let filtered = workflows;
+
+      if (project_type !== "all") {
+        filtered = workflows.filter((wf) => {
+          const types = wf.project_types || ["universal"];
+          return (
+            types.includes("universal") ||
+            types.includes(project_type) ||
+            project_type === "mixed"
+          );
+        });
+      }
+
+      const result = filtered.map((wf) => ({
+        id: wf.id,
+        name: wf.name,
+        project_types: wf.project_types || ["universal"],
+        steps: (wf.steps || []).map((s) => ({
+          stage: s.stage,
+          action: s.action,
+          features: s.features || [],
+        })),
+      }));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                project_type,
+                workflow_count: result.length,
+                workflows: result,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  );
+
+  // -------------------------------------------------------------------------
+  // Tool 8: refactor_markdown — CTX-06 scale analysis
+  // -------------------------------------------------------------------------
+
+  server.tool(
+    "refactor_markdown",
+    "Analyze a markdown file for scale management (CTX-06). Reports line count, whether it exceeds the 300-line threshold, section breakdown, and a split plan if refactoring is needed. Advisory only — does not modify the file.",
+    {
+      file_path: z.string().describe("Path to the markdown file to analyze"),
+    },
+    async ({ file_path }) => {
+      const result = analyzeMarkdown(file_path);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// Standalone entry point — starts stdio transport
+// ---------------------------------------------------------------------------
+
+export async function startServer(registryPath) {
+  const server = createServer(registryPath);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}