x-readiness-mcp 0.3.0 → 0.5.0

package/server.js

@@ -1,169 +1,107 @@
 // mcp/server.js
-// X-Readiness MCP Server
-//
-// Tools:
-//   1) planner           → Generate checklist + persist plan file
-//   2) execute_checklist → Load plan file + execute checks ONLY after explicit user approval code
-//
-// Why approval code?
-// - Copilot/agents may auto-call tools without asking.
-// - A user-provided approvalCode forces explicit human permission (copy/paste).
-
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod";
-
-import fs from "node:fs/promises";
-import path from "node:path";
 import crypto from "node:crypto";
 
-import { generateChecklist } from "./tools/planning.js";
-import { executionTool } from "./tools/execution.js";
-
-const server = new McpServer(
-  { name: "x-readiness-mcp", version: "0.3.0" },
-  { capabilities: { tools: {} } }
-);
-
-// -----------------------------
-// Plan persistence helpers
-// -----------------------------
-const PLAN_DIR = path.resolve(process.cwd(), ".xreadiness", "plan");
-
-async function ensurePlanDir() {
-  await fs.mkdir(PLAN_DIR, { recursive: true });
-}
-
-async function savePlanToDisk(plan) {
-  await ensurePlanDir();
-
-  const planId =
-    (typeof plan?.checklist_id === "string" && plan.checklist_id.trim()) ||
-    `plan_${crypto.randomUUID()}`;
-
-  // Sanitize filename for Windows (replace colons with hyphens)
-  const sanitizedPlanId = planId.replace(/:/g, "-");
-
-  const planPath = path.join(PLAN_DIR, `${sanitizedPlanId}.json`);
-  await fs.writeFile(planPath, JSON.stringify(plan, null, 2), "utf8");
-
-  return { planId, planPath };
-}
-
-async function loadPlanFromDisk(planPath) {
-  const raw = await fs.readFile(planPath, "utf8");
-  return JSON.parse(raw);
-}
-
-function countRulesFromPlan(plan) {
-  if (Array.isArray(plan?.features)) {
-    return plan.features.reduce((acc, f) => acc + (f?.rules?.length ?? 0), 0);
-  }
-  if (Array.isArray(plan?.rules)) return plan.rules.length;
-  return 0;
-}
+import { planTool } from "./tools/planning.js";
+import { executeTool } from "./tools/execution.js";
+import { autoFixTool } from "./tools/autofix.js";
 
 // -----------------------------
-// Explicit permission mechanism
+// Approval gate (in-memory)
 // -----------------------------
-// In-memory approvals keyed by (repoPath + planPath). Resets on server restart.
 const approvals = new Map(); // key -> { code, createdAt }
-const APPROVAL_TTL_MS = 10 * 60 * 1000; // 10 minutes
-
-function approvalKey(repoPath, planPath) {
-  return `${repoPath}||${planPath}`;
-}
+const APPROVAL_TTL_MS = 10 * 60 * 1000;
 
 function newApprovalCode() {
-  // 6-digit numeric code (easy to copy/paste)
   return String(Math.floor(100000 + Math.random() * 900000));
 }
-
-function getOrCreateApproval(repoPath, planPath) {
-  const key = approvalKey(repoPath, planPath);
+function approvalKey(kind, repoPath, ref) {
+  return `${kind}||${repoPath}||${ref}`;
+}
+function getOrCreateApproval(kind, repoPath, ref) {
+  const key = approvalKey(kind, repoPath, ref);
   const existing = approvals.get(key);
   const now = Date.now();
-
-  if (existing && now - existing.createdAt <= APPROVAL_TTL_MS) {
-    return { key, ...existing };
-  }
-
-  const code = newApprovalCode();
-  const createdAt = now;
-  approvals.set(key, { code, createdAt });
-  return { key, code, createdAt };
-}
-
-function clearApproval(repoPath, planPath) {
-  approvals.delete(approvalKey(repoPath, planPath));
+  if (existing && now - existing.createdAt <= APPROVAL_TTL_MS) return existing;
+  const rec = { code: newApprovalCode(), createdAt: now };
+  approvals.set(key, rec);
+  return rec;
 }
-
-function isApprovalValid(repoPath, planPath, providedCode) {
-  const key = approvalKey(repoPath, planPath);
+function isApprovalValid(kind, repoPath, ref, code) {
+  const key = approvalKey(kind, repoPath, ref);
   const rec = approvals.get(key);
   if (!rec) return false;
   if (Date.now() - rec.createdAt > APPROVAL_TTL_MS) {
     approvals.delete(key);
     return false;
   }
-  return String(providedCode) === String(rec.code);
+  return String(code) === String(rec.code);
+}
+function clearApproval(kind, repoPath, ref) {
+  approvals.delete(approvalKey(kind, repoPath, ref));
 }
 
-// ============================================================================
-// TOOL 1: planner (Planning Tool)
-// ============================================================================
+const server = new McpServer(
+  { name: "x-readiness-mcp", version: "0.4.0" },
+  { capabilities: { tools: {} } }
+);
+
+// -----------------------------
+// TOOL: plan
+// -----------------------------
 server.registerTool(
-  "planner",
+  "plan",
   {
     description:
-      "Planning Tool - Generate X-API readiness checklist and store it in mcp/plan as a JSON plan file. Returns plan_id and plan_path.",
+      "Planning Tool: Generate a high-level X-Readiness plan with rule checklist based on scope and developer intent. Creates plan files in mcp/plan folder. This is Step 1 - after generating the plan, you'll need to get approval before executing it.",
     inputSchema: z.object({
+      repoPath: z.string().describe("Path to repo/workspace root to analyze"),
       scope: z
+        .enum(["x_api_readiness", "pagination_ready", "security_ready", "error_handling_ready", "versioning_ready"])
+        .describe("Which readiness scope to plan for"),
+      developerPrompt: z
         .string()
-        .describe(
-          "Readiness scope: 'x_api_readiness', 'pagination_ready', 'security_ready', etc."
-        ),
-      format: z
-        .enum(["json", "markdown", "both"])
-        .optional()
-        .describe("Output format (default: 'json')"),
-      intent: z
-        .string()
-        .optional()
-        .describe("Optional intent/context string to store with the plan")
+        .describe("Developer intent: what to focus on, specific requirements, or keywords (e.g., 'pagination', 'error handling')"),
+      outputFormat: z.enum(["markdown", "json", "both"]).optional().default("markdown")
     })
   },
-  async ({ scope, format = "json", intent }) => {
-    try {
-      const checklist = await generateChecklist(scope, format);
-
-      if (intent) checklist.intent = intent;
-
-      const { planId, planPath } = await savePlanToDisk(checklist);
-
-      const featuresCount = Array.isArray(checklist?.features)
-        ? checklist.features.length
-        : 0;
-
-      const rulesCount = countRulesFromPlan(checklist);
+  async (input) => {
+    const result = await planTool(input);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
 
+// -----------------------------
+// TOOL: execute (gated)
+// -----------------------------
+server.registerTool(
+  "execute",
+  {
+    description:
+      "Execution Tool: Execute a saved plan against source code, checking each rule systematically. Generates detailed violation report with file/line references. Step 2 - REQUIRES APPROVAL. You will receive an approval code that must be provided to proceed with execution.",
+    inputSchema: z.object({
+      repoPath: z.string().describe("Path to repo/workspace root"),
+      planPath: z.string().describe("Path to the plan JSON file (from plan tool output)"),
+      approvalCode: z.string().optional().describe("6-digit approval code (will be provided when first called without code)")
+    })
+  },
+  async ({ repoPath, planPath, approvalCode }) => {
+    if (!approvalCode || !isApprovalValid("execute", repoPath, planPath, approvalCode)) {
+      const { code } = getOrCreateApproval("execute", repoPath, planPath);
       return {
         content: [
           {
             type: "text",
             text: JSON.stringify(
               {
-                plan_id: planId,
-                plan_path: planPath,
-                summary: {
-                  scope: checklist.scope ?? scope,
-                  template_version: checklist.template_version,
-                  template_last_updated: checklist.template_last_updated,
-                  features: featuresCount,
-                  rules: rulesCount
-                },
-                next_step:
-                  "To execute, call execute_checklist with repoPath, planPath, and the approvalCode (you will be prompted for it)."
+                status: "CONFIRMATION_REQUIRED",
+                message:
+                  "⚠️ APPROVAL REQUIRED: Execution will scan your source code and check against all rules in the plan.\n\nTo proceed, call the 'execute' tool again with the same parameters and include the approvalCode below.",
+                approvalCode: code,
+                expires_in_minutes: Math.floor(APPROVAL_TTL_MS / 60000),
+                next_action: "Re-run execute tool with approvalCode parameter"
               },
               null,
               2
@@ -171,114 +109,66 @@ server.registerTool(
           }
         ]
       };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Planning Error: ${error?.message ?? String(error)}\n${
-              error?.stack ?? ""
-            }`
-          }
-        ],
-        isError: true
-      };
     }
+
+    clearApproval("execute", repoPath, planPath);
+    const result = await executeTool({ repoPath, planPath });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   }
 );
 
-// ============================================================================
-// TOOL 2: execute_checklist (Execution Tool)
-// ============================================================================
-// - Loads plan JSON from disk (planPath)
-// - Requires approvalCode to proceed
-// - If approvalCode missing/wrong, returns CONFIRMATION_REQUIRED (no execution)
-// ============================================================================
+// -----------------------------
+// TOOL: auto_fix (gated)
+// -----------------------------
 server.registerTool(
-  "execute_checklist",
+  "auto_fix",
   {
     description:
-      "Execution Tool - Loads a stored plan from mcp/plan and checks a repository. Requires explicit approvalCode to execute.",
+      "Auto-fix Tool: Generate fixes for violations found in the execution report. Step 3 - REQUIRES APPROVAL. Can propose fixes or apply them directly.",
     inputSchema: z.object({
-      repoPath: z
-        .string()
-        .describe("Path to the repository or source code to check"),
-      planPath: z
-        .string()
-        .describe("Path to the saved plan JSON file (from planner output)"),
-      approvalCode: z
-        .string()
-        .optional()
-        .describe(
-          "User approval code required to run. If omitted, the tool returns a code and stops."
-        )
+      repoPath: z.string().describe("Path to repo/workspace root"),
+      runId: z.string().describe("run_id from execute output"),
+      mode: z.enum(["propose", "apply"]).default("propose").describe("'propose' shows fixes without applying, 'apply' applies fixes to source code"),
+      approvalCode: z.string().optional().describe("6-digit approval code (will be provided when first called without code)")
     })
   },
-  async ({ repoPath, planPath, approvalCode }) => {
-    try {
-      // Permission gate: do not execute unless approvalCode matches
-      if (!approvalCode || !isApprovalValid(repoPath, planPath, approvalCode)) {
-        const { code } = getOrCreateApproval(repoPath, planPath);
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  status: "CONFIRMATION_REQUIRED",
-                  message:
-                    "Execution not started. Please confirm you want to run analysis by re-running execute_checklist with the approvalCode below.",
-                  approvalCode: code,
-                  expires_in_minutes: Math.floor(APPROVAL_TTL_MS / 60000),
-                  next_call_example: {
-                    tool: "execute_checklist",
-                    input: { repoPath, planPath, approvalCode: code }
-                  }
-                },
-                null,
-                2
-              )
-            }
-          ]
-        };
-      }
-
-      // If we’re here, permission is confirmed
-      clearApproval(repoPath, planPath);
-
-      const checklist = await loadPlanFromDisk(planPath);
-      const results = await executionTool(repoPath, checklist);
-
-      // Optional: make "all skipped" clearer so it isn't interpreted as 0% failure
-      const rs = results?.readiness_summary;
-      if (rs && rs.total_rules_checked === 0 && (rs.rules_skipped ?? 0) > 0) {
-        rs.status = "NOT_EVALUATED";
-        rs.message =
-          "No rules were evaluated (all skipped). Score is not meaningful without detectable API signals.";
-        rs.score = "N/A";
-      }
-
-      return {
-        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
-      };
-    } catch (error) {
+  async ({ repoPath, runId, mode, approvalCode }) => {
+    const ref = `${runId}||${mode}`;
+    if (!approvalCode || !isApprovalValid("auto_fix", repoPath, ref, approvalCode)) {
+      const { code } = getOrCreateApproval("auto_fix", repoPath, ref);
       return {
         content: [
           {
             type: "text",
-            text: `Execution Error: ${error?.message ?? String(error)}`
+            text: JSON.stringify(
+              {
+                status: "CONFIRMATION_REQUIRED",
+                message:
+                  "⚠️ APPROVAL REQUIRED: Auto-fix will analyze violations and " +
+                  (mode === "apply" ? "MODIFY your source code files." : "propose changes to your source code.") +
+                  "\n\nTo proceed, call the 'auto_fix' tool again with the same parameters and include the approvalCode below.",
+                approvalCode: code,
+                expires_in_minutes: Math.floor(APPROVAL_TTL_MS / 60000),
+                next_action: "Re-run auto_fix tool with approvalCode parameter"
+              },
+              null,
+              2
+            )
           }
-        ],
-        isError: true
+        ]
       };
     }
+
+    clearApproval("auto_fix", repoPath, ref);
+    const result = await autoFixTool({ repoPath, runId, mode });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   }
 );
 
-// ============================================================================
+// -----------------------------
 // START SERVER
-// ============================================================================
+// -----------------------------
 console.error("x-readiness-mcp: starting (stdio)...");
 const transport = new StdioServerTransport();
 await server.connect(transport);
+

package/tools/autofix.js

@@ -0,0 +1,151 @@
+// mcp/tools/autofix.js
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function reportsPath(repoPath, runId) {
+  return path.resolve(repoPath, ".xreadiness", "reports", `${runId}.json`);
+}
+function patchesDir(repoPath) {
+  return path.resolve(repoPath, ".xreadiness", "patches");
+}
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function gitIsClean(repoPath) {
+  try {
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain"], { cwd: repoPath });
+    return stdout.trim().length === 0;
+  } catch {
+    // If git isn't available, be conservative
+    return false;
+  }
+}
+
+async function getGitDiff(repoPath) {
+  try {
+    const { stdout } = await execFileAsync("git", ["diff", "--stat"], { cwd: repoPath });
+    const { stdout: diffContent } = await execFileAsync("git", ["diff"], { cwd: repoPath });
+    return { stat: stdout, diff: diffContent };
+  } catch (err) {
+    return { stat: "Error getting git diff", diff: err.message };
+  }
+}
+
+function buildPatchFromViolations(report) {
+  // For v1, only generate a patch if violations include a ready-to-apply patch chunk.
+  // You can extend your rule checkers to attach suggestedFixUnifiedDiff per violation.
+  const diffs = report.violations
+    .map(v => v.suggested_patch)
+    .filter(Boolean);
+
+  return diffs.join("\n");
+}
+
+/**
+ * Auto-fix tool with 2-stage approval:
+ * - mode="suggest": Shows proposed patches/diffs without applying
+ * - mode="apply": Applies patches to source code (requires clean git state)
+ */
+export async function autoFixTool({ repoPath, runId, mode = "suggest" }) {
+  const reportFile = reportsPath(repoPath, runId);
+  
+  let reportData;
+  try {
+    const raw = await fs.readFile(reportFile, "utf8");
+    reportData = JSON.parse(raw);
+  } catch (err) {
+    return {
+      status: "ERROR",
+      message: `Failed to load report file: ${reportFile}. Error: ${err.message}`
+    };
+  }
+
+  const patch = buildPatchFromViolations(reportData);
+  if (!patch) {
+    return {
+      status: "NO_AUTOFIX_AVAILABLE",
+      message: "No violations contain auto-fix patches yet. Implement suggested_patch in rule checkers first.",
+      violations_count: reportData.violations?.length || 0,
+      note: "Auto-fix requires rule checkers to provide suggested_patch field for each violation"
+    };
+  }
+
+  await ensureDir(patchesDir(repoPath));
+  const patchPath = path.join(patchesDir(repoPath), `${runId}.patch`);
+  await fs.writeFile(patchPath, patch, "utf8");
+
+  // SUGGEST mode: just show the proposed changes
+  if (mode === "suggest") {
+    const violationsWithFixes = reportData.violations.filter(v => v.suggested_patch);
+    const filesImpacted = [...new Set(violationsWithFixes.map(v => v.file_path))];
+    
+    return {
+      status: "PATCH_PROPOSED",
+      mode: "suggest",
+      patch_path: patchPath,
+      patch_preview: patch.substring(0, 2000) + (patch.length > 2000 ? "\n... (truncated)" : ""),
+      files_impacted: filesImpacted,
+      violations_with_fixes: violationsWithFixes.length,
+      total_violations: reportData.violations?.length || 0,
+      applied: false,
+      message: `✅ Auto-fix analysis complete!\n\n📊 Summary:\n- ${violationsWithFixes.length} violations have suggested fixes\n- ${filesImpacted.length} files will be modified\n\n📄 Patch saved to: ${patchPath}\n\n⚠️ NEXT STEP:\n- Review the patch file carefully\n- To apply fixes, call 'auto_fix' tool again with mode='apply'\n- Application requires approval code and clean git state`,
+      risk_notes: [
+        "Patches are auto-generated and may need manual review",
+        "Always commit your changes before applying auto-fixes",
+        "Test thoroughly after applying fixes"
+      ],
+      next_action: "Review patch, then call auto_fix with mode='apply' and approvalCode"
+    };
+  }
+
+  // APPLY mode: actually modify files
+  const clean = await gitIsClean(repoPath);
+  if (!clean) {
+    return {
+      status: "REQUIRES_CLEAN_GIT",
+      message: "⚠️ Git repository has uncommitted changes.\n\nBefore applying auto-fixes:\n1. Commit your current changes: git commit -am 'your message'\n2. Or stash changes: git stash\n3. Then call auto_fix again with mode='apply'",
+      patch_path: patchPath,
+      applied: false,
+      instruction: "Clean your git working directory before applying patches"
+    };
+  }
+
+  // Apply patch via git apply
+  try {
+    await execFileAsync("git", ["apply", patchPath], { cwd: repoPath });
+  } catch (err) {
+    return {
+      status: "PATCH_FAILED",
+      message: `Failed to apply patch: ${err.message}`,
+      patch_path: patchPath,
+      applied: false,
+      suggestion: "Review the patch file manually and apply fixes by hand, or check for conflicts"
+    };
+  }
+
+  // Get git diff summary after applying
+  const { stat, diff } = await getGitDiff(repoPath);
+  const modifiedFiles = stat.split("\n").filter(line => line.trim()).slice(0, -1); // Remove summary line
+
+  return {
+    status: "PATCH_APPLIED",
+    mode: "apply",
+    patch_path: patchPath,
+    applied: true,
+    files_modified: modifiedFiles,
+    git_diff_stat: stat,
+    git_diff_preview: diff.substring(0, 3000) + (diff.length > 3000 ? "\n... (truncated, use git diff for full output)" : ""),
+    message: `✅ Auto-fixes applied successfully!\n\n📊 Changes:\n${stat}\n\n⚠️ IMPORTANT:\n1. Review the changes: git diff\n2. Test your application thoroughly\n3. Commit if satisfied: git commit -am 'Applied X-Readiness auto-fixes'\n4. Or revert if needed: git checkout .`,
+    next_steps: [
+      "Review git diff output",
+      "Run tests to verify fixes",
+      "Commit changes if satisfied",
+      "Re-run execution to verify compliance"
+    ]
+  };
+}