x-readiness-mcp 0.3.0

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "../server.js";
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "x-readiness-mcp",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Clean, deterministic X-Readiness verification using MCP with Planning and Execution tools",
+  "main": "server.js",
+  "bin": {
+  "x-readiness-mcp": "bin/cli.js"
+},
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x-readiness",
+    "api-verification",
+    "rest-api",
+    "conformance"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "cheerio": "^1.2.0",
+    "glob": "^13.0.0"
+  }
+}

package/server.js

@@ -0,0 +1,284 @@
+// 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;
+}
+
+// -----------------------------
+// Explicit permission mechanism
+// -----------------------------
+// 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}`;
+}
+
+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);
+  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));
+}
+
+function isApprovalValid(repoPath, planPath, providedCode) {
+  const key = approvalKey(repoPath, planPath);
+  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);
+}
+
+// ============================================================================
+// TOOL 1: planner (Planning Tool)
+// ============================================================================
+server.registerTool(
+  "planner",
+  {
+    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.",
+    inputSchema: z.object({
+      scope: 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")
+    })
+  },
+  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);
+
+      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)."
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Planning Error: ${error?.message ?? String(error)}\n${
+              error?.stack ?? ""
+            }`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+
+// ============================================================================
+// 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)
+// ============================================================================
+server.registerTool(
+  "execute_checklist",
+  {
+    description:
+      "Execution Tool - Loads a stored plan from mcp/plan and checks a repository. Requires explicit approvalCode to execute.",
+    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."
+        )
+    })
+  },
+  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) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Execution Error: ${error?.message ?? String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+
+// ============================================================================
+// START SERVER
+// ============================================================================
+console.error("x-readiness-mcp: starting (stdio)...");
+const transport = new StdioServerTransport();
+await server.connect(transport);