feat(mcp): add REST route, CLI command, and stdio tool for loopover_plan_repo_issues (#7890)

loopover_plan_repo_issues (generateIssuePlanDrafts) shipped only as a remote MCP
tool and never got the REST + CLI + local-stdio mirror surfaces its repo-scoped,
requireRepoManageAccess-gated siblings all have. Mirrors
loopover_generate_contributor_issue_drafts exactly: a POST
/v1/repos/:owner/:repo/issue-plan-drafts/generate route (same gate), a
maintain plan-issues CLI command calling it, and a loopover_plan_repo_issues
stdio tool. generateIssuePlanDrafts and the remote tool are unchanged.

Closes #7764

Author: xfodev

apps/loopover-ui/public/openapi.json

@@ -19030,6 +19030,58 @@
           }
         ]
       }
+    },
+    "/v1/repos/{owner}/{repo}/issue-plan-drafts/generate": {
+      "post": {
+        "summary": "AI-plan repo issue drafts from a maintainer goal",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "owner",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "repo",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "AI-plan a small set of GitHub issue drafts from a maintainer-supplied planning goal (dry-run by default)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "nullable": true
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request or explicit create without dryRun false"
+          },
+          "403": {
+            "description": "Insufficient role"
+          }
+        },
+        "security": [
+          {
+            "LoopOverBearer": []
+          },
+          {
+            "LoopOverSessionCookie": []
+          }
+        ]
+      }
     }
   },
   "servers": [

packages/loopover-mcp/bin/loopover-mcp.ts

@@ -2,9 +2,10 @@
 // Phase 3 of #7291 / #7330 — design decision: single-file 1:1 JS→TS conversion (not a split).
 // Seams exist, but splitting would be a separate refactor; this PR only routes the CLI through tsc.
 import { createHash } from "node:crypto";
-import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { buildFeasibilityVerdict, buildPrTextLint, buildGateDispositions, buildPublicPrBodyDraft } from "@loopover/engine";
@@ -72,6 +73,27 @@ const decisionPackCacheMaxBytes = 512 * 1024;
 const cliTextFileMaxBytes = 1024 * 1024;
 const changelogPath = new URL("../CHANGELOG.md", import.meta.url);
 const cliArgs = process.argv.slice(2);
+
+// #7764: true only when this file is the process entrypoint (`node .../loopover-mcp.js`, incl. via the npm
+// `.bin` symlink -- realpathSync resolves it), false when it is imported in-process (e.g. by a vitest unit
+// test that exercises the CLI dispatcher + stdio tools directly). The two top-level side effects below -- the
+// CLI dispatch and the stdio `server.connect()` -- are gated on it so an in-process importer neither hijacks
+// the test runner's argv into runCli() nor binds a StdioServerTransport to the shared stdin. This is the same
+// "testable-export refactor" path bin/loopover-miner-mcp.ts's createMinerMcpServer already took (see
+// codecov.yml's CLI-dispatcher note); subprocess invocation is unchanged (argv[1] is this file, so it stays
+// true) and every mcp-cli-*.test.ts harness run continues to hit the real dispatcher.
+function isProcessEntrypoint() {
+  const entry = process.argv[1];
+  /* v8 ignore next -- argv[1] is always populated for a spawned Node process; the guard is belt-and-suspenders */
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    /* v8 ignore next -- defensive: a realpath failure (renamed/removed entry) just means "not the launched CLI" */
+    return false;
+  }
+}
+const runAsCliEntrypoint = isProcessEntrypoint();
 const defaultProfileName = "default";
 // Single source of truth for shell-completion: top-level command -> its subcommands (if any).
 const CLI_COMMAND_SPEC = {
@@ -107,7 +129,7 @@ const CLI_COMMAND_SPEC = {
   profile: ["list", "create", "switch", "remove"],
   cache: ["status", "clear", "list"],
   agent: ["plan", "status", "explain", "packet"],
-  maintain: ["status", "queue", "propose", "approve", "reject", "pause", "resume", "set-level", "precision", "outcome-calibration", "onboarding-pack", "audit-feed", "automation-state", "refresh-docs", "generate-issue-drafts"],
+  maintain: ["status", "queue", "propose", "approve", "reject", "pause", "resume", "set-level", "precision", "outcome-calibration", "onboarding-pack", "audit-feed", "automation-state", "refresh-docs", "generate-issue-drafts", "plan-issues"],
 };
 const COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell"];
 const AGENT_PROFILE_IDS = ["miner-planner", "miner-auto-dev", "maintainer-triage", "repo-owner-intake"];
@@ -921,6 +943,20 @@ const gatePrecisionShape = {
   windowDays: z.number().int().positive().optional(),
 };
 
+// #7764: mirrors the remote loopover_plan_repo_issues tool's input (src/mcp/server.ts's planRepoIssuesShape),
+// minus the create-only `milestone` which this proxy (and the `maintain plan-issues` CLI) does not expose --
+// forwarded to POST /v1/repos/:owner/:repo/issue-plan-drafts/generate. `goal` is the required maintainer
+// planning goal; dryRun/create carry the route's create-safety (create alone is rejected there). `limit` is
+// capped at 10, matching the route, because every draft costs real LLM spend.
+const planRepoIssuesShape = {
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  goal: z.string().min(1).max(2000),
+  dryRun: z.boolean().optional().default(true),
+  create: z.boolean().optional().default(false),
+  limit: z.number().int().min(1).max(10).optional().default(5),
+};
+
 // Single source of truth for stdio tool name + one-line description (#2233).
 // Registration and `loopover-mcp tools` both read this list.
 const STDIO_TOOL_DESCRIPTORS = [
@@ -1307,6 +1343,12 @@ const STDIO_TOOL_DESCRIPTORS = [
     category: "maintainer",
     description: "Return per-gate-type false-positive precision for a repo's recorded gate blocks — blocked / blocked-then-merged counts and false-positive rates with low-sample guards. Optionally bounded by windowDays. Maintainer-authenticated; measurement only.",
   },
+  {
+    name: "loopover_plan_repo_issues",
+    category: "maintainer",
+    description:
+      "AI-plan a small set of concrete GitHub issue drafts for a repo from a maintainer-supplied free-form goal, same as `loopover-mcp maintain plan-issues --goal ...`. Dry-run BY DEFAULT: only previews the drafted title/body/labels unless the caller passes BOTH create:true and dryRun:false, so it can never silently open issues. Maintainer access required.",
+  },
   {
     name: "loopover_open_pr",
     category: "agent",
@@ -1378,7 +1420,9 @@ function stdioToolDescription(name: any) {
   return tool.description;
 }
 
-if (cliArgs[0] && cliArgs[0] !== "--stdio") {
+/* v8 ignore next 8 -- the CLI dispatch runs only in the launched process (runAsCliEntrypoint); an in-process
+   unit importer keeps it false and drives runCli/maintainCli directly instead (mcp-cli-plan-issues.test.ts). */
+if (runAsCliEntrypoint && cliArgs[0] && cliArgs[0] !== "--stdio") {
   try {
     const exitCode = await runCli(cliArgs);
     process.exit(typeof exitCode === "number" ? exitCode : 0);
@@ -1387,7 +1431,7 @@ if (cliArgs[0] && cliArgs[0] !== "--stdio") {
   }
 }
 
-const server = new McpServer({
+export const server = new McpServer({
   name: "loopover-local",
   version: packageVersion,
 });
@@ -2643,6 +2687,25 @@ registerStdioTool(
     return toolResult(`Gate precision for ${owner}/${repo}.`, payload);
   },
   );
+
+registerStdioTool(
+  "loopover_plan_repo_issues",
+  {
+    description: stdioToolDescription("loopover_plan_repo_issues"),
+    inputSchema: planRepoIssuesShape,
+  },
+  async ({ owner, repo, goal, dryRun, create, limit }: any) => {
+    // #7764: proxies POST {repoBase}/issue-plan-drafts/generate (the REST mirror of this same tool id). The
+    // route re-applies its own explicit_create_requires_dry_run_false guard, so forwarding the schema-defaulted
+    // dryRun/create verbatim keeps the create-safety exact: `create` alone (dryRun still true) is rejected;
+    // only an explicit {create:true, dryRun:false} reaches the write path.
+    const payload = await apiPost(`${toolRepoBase(owner, repo)}/issue-plan-drafts/generate`, { goal, dryRun, create, limit });
+    return toolResult(
+      `Issue plan for ${owner}/${repo} (status=${payload.status}, dryRun=${payload.dryRun}): ${payload.proposed ?? 0} proposed, ${payload.created ?? 0} created.`,
+      payload,
+    );
+  },
+);
 // ── Write-tools (#6149): pure LOCAL-execution spec builders. loopover NEVER performs the write -- each tool
 // returns a spec the caller runs with its OWN gh creds. Brings the local stdio server to parity with the
 // miner-auto-dev profile's recommendedTools, using the same @loopover/engine builders as the remote server.
@@ -3187,7 +3250,10 @@ server.registerPrompt(
   }),
 );
 
-await server.connect(new StdioServerTransport());
+// #7764: only bind the shared stdin/stdout transport when actually launched as the CLI/stdio process. An
+// in-process unit-test importer holds the exported `server` and connects it to an in-memory transport instead.
+/* v8 ignore next -- only the launched stdio process binds the real transport; unit tests connect in-memory. */
+if (runAsCliEntrypoint) await server.connect(new StdioServerTransport());
 
 async function withClientWorkspaceRoots(input: any) {
   return withWorkspaceRoots(input, await clientWorkspaceRoots());
@@ -3248,6 +3314,9 @@ function printMaintainHelp() {
       "  generate-issue-drafts        Preview contributor issue drafts (dry-run). Never creates without --create.",
       "             [--create]        Actually open the drafted issues (requires repo write access).",
       "             [--limit N]       Cap the drafts generated (1-20, default 5).",
+      '  plan-issues --goal "..."     AI-plan issue drafts from a free-form goal (dry-run). Never creates without --create.',
+      "             [--create]        Actually open the drafted issues (requires repo write access).",
+      "             [--limit N]       Cap the drafts generated (1-10, default 5).",
       "",
       "Pass --json for machine-readable output.",
     ].join("\n") + "\n",
@@ -3256,7 +3325,7 @@ function printMaintainHelp() {
 
 // #784 maintainer CLI controls — thin proxies over the agent approval-queue API (#779) and the maintainer
 // settings kill-switch (#130). The API enforces maintainer authorization; the CLI never decides locally.
-async function maintainCli(args: any) {
+export async function maintainCli(args: any) {
   const subcommand = args[0];
   if (!subcommand || subcommand === "--help" || subcommand === "help") return printMaintainHelp();
   const positional = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
@@ -3485,8 +3554,32 @@ async function maintainCli(args: any) {
     emit(payload, lines.join("\n"));
     return;
   }
+  if (subcommand === "plan-issues") {
+    // #7764: session-authenticated mirror of POST {repoBase}/issue-plan-drafts/generate (and the remote
+    // loopover_plan_repo_issues tool). Requires --goal (the maintainer's free-form planning goal). Dry-run BY
+    // DEFAULT — only a bare `--create` opts into the write path, forwarded as {create:true, dryRun:false}, the
+    // exact shape the route's explicit_create_requires_dry_run_false guard demands. A plain `plan-issues` can
+    // never create.
+    const goal = typeof options.goal === "string" ? options.goal.trim() : "";
+    if (!goal) throw new Error('Pass the planning goal: loopover-mcp maintain plan-issues --repo owner/repo --goal "...".');
+    const create = options.create === true;
+    const parsedLimit = Number(options.limit);
+    const body = { goal, create, dryRun: !create, ...(Number.isFinite(parsedLimit) ? { limit: parsedLimit } : {}) };
+    const payload = await apiPost(`${repoBase}/issue-plan-drafts/generate`, body);
+    const mode = payload.dryRun ? "dry-run" : "create";
+    const lines = [
+      `Issue plan for ${repoFullName} (${mode}, status=${sanitizePlainTextTerminalOutput(payload.status)}): ${payload.proposed ?? 0} proposed, ${payload.created ?? 0} created, ${payload.skippedDuplicate ?? 0} duplicate, ${payload.skippedDeclined ?? 0} declined, ${payload.skippedUnsafe ?? 0} unsafe, ${payload.skippedCreateFailed ?? 0} create-failed.`,
+      // draft.title/body are AI-generated free text, so the plain-text path is sanitized (#6261).
+      ...(payload.drafts ?? []).map((draft: any) => {
+        const ref = draft.issue ? ` -> #${draft.issue.number} ${draft.issue.url}` : "";
+        return `- [${sanitizePlainTextTerminalOutput(draft.status)}] ${sanitizePlainTextTerminalOutput(draft.title)}${sanitizePlainTextTerminalOutput(ref)}`;
+      }),
+    ];
+    emit(payload, lines.join("\n"));
+    return;
+  }
   throw new Error(
-    `Unknown maintain subcommand: ${subcommand}. Use status | queue | propose <action-class> <pull-number> | approve <id> | reject <id> | pause | resume | set-level <action> <level> | precision | outcome-calibration | onboarding-pack | audit-feed | automation-state | refresh-docs | generate-issue-drafts.`,
+    `Unknown maintain subcommand: ${subcommand}. Use status | queue | propose <action-class> <pull-number> | approve <id> | reject <id> | pause | resume | set-level <action> <level> | precision | outcome-calibration | onboarding-pack | audit-feed | automation-state | refresh-docs | generate-issue-drafts | plan-issues.`,
   );
 }
 

src/api/routes.ts

@@ -320,6 +320,7 @@ import { resolveRepositorySettings } from "../settings/repository-settings";
 import { loadPublicRepoFocusManifest, loadRepoFocusManifest, upsertRepoFocusManifest } from "../signals/focus-manifest-loader";
 import { buildRepoOnboardingPackPreviewForRepo } from "../services/repo-onboarding-pack";
 import { generateContributorIssueDrafts } from "../services/contributor-issue-draft";
+import { generateIssuePlanDrafts } from "../services/issue-plan-draft";
 import { buildRepoSettingsPreview, PUBLIC_SURFACE_SKIP_REASONS, skippedPrAuditRemediation } from "../signals/settings-preview";
 import {
   buildGittensorConfigRecommendation,
@@ -954,6 +955,17 @@ const contributorIssueDraftGenerateSchema = z.object({
   limit: z.number().int().min(1).max(20).optional().default(5),
 });
 
+// #7764: REST mirror of the loopover_plan_repo_issues MCP tool (src/mcp/server.ts's planRepoIssuesShape).
+// Unlike the contributor-issue-draft schema above, `goal` is a REQUIRED maintainer-supplied free-form string
+// and `limit` is capped lower (10, not 20): every draft here costs real LLM spend, unlike that tool's zero-cost
+// static signals. dryRun/create keep the same create-safety contract (create alone is rejected below).
+const issuePlanDraftGenerateSchema = z.object({
+  goal: z.string().trim().min(1).max(2000),
+  dryRun: z.boolean().optional().default(true),
+  create: z.boolean().optional().default(false),
+  limit: z.number().int().min(1).max(10).optional().default(5),
+});
+
 const settingsPreviewSchema = z.object({
   sample: z
     .object({
@@ -2793,6 +2805,43 @@ export function createApp() {
     );
   });
 
+  // #7764: REST mirror of the loopover_plan_repo_issues MCP tool (src/mcp/server.ts) and the
+  // `maintain plan-issues` CLI. Gated EXACTLY like the sibling contributor-issue-drafts route above
+  // (requireAppRole maintainer/owner/operator, then per-repo requireSessionRepoAccess for sessions), and it
+  // preserves the same create-safety: dry-run by default, and the write path is entered only when the caller
+  // passes BOTH create:true and dryRun:false -- which additionally requires live repo write access. The
+  // required `goal` is a maintainer-supplied free-form planning goal the service turns into issue drafts.
+  app.post("/v1/repos/:owner/:repo/issue-plan-drafts/generate", async (c) => {
+    const fullName = `${c.req.param("owner")}/${c.req.param("repo")}`;
+    const forbidden = await requireAppRole(c, ["maintainer", "owner", "operator"]);
+    if (forbidden) return forbidden;
+    const identity = await authenticateRequestIdentity(c);
+    const repo = await getRepository(c.env, fullName);
+    if (identity?.kind === "session") {
+      const repoForbidden = await requireSessionRepoAccess(c, identity, fullName, repo);
+      if (repoForbidden) return repoForbidden;
+    }
+    const body = await c.req.json().catch(() => null);
+    if (body === null) return c.json({ error: "invalid_json" }, 400);
+    const parsed = issuePlanDraftGenerateSchema.safeParse(body);
+    if (!parsed.success) return c.json({ error: "invalid_issue_plan_draft_request", issues: parsed.error.issues }, 400);
+    if (parsed.data.create && parsed.data.dryRun !== false) {
+      return c.json({ error: "explicit_create_requires_dry_run_false" }, 400);
+    }
+    if (parsed.data.create && parsed.data.dryRun === false) {
+      const writeForbidden = await requireRepoWriteAccess(c, fullName);
+      if (writeForbidden instanceof Response) return writeForbidden;
+    }
+    return c.json(
+      await generateIssuePlanDrafts(c.env, fullName, parsed.data.goal, {
+        dryRun: parsed.data.dryRun,
+        create: parsed.data.create,
+        limit: parsed.data.limit,
+        requestedBy: identity?.kind === "session" ? identity.actor : "api",
+      }),
+    );
+  });
+
   // Repo loopover settings (gate config, AI-review mode/provider/model — NON-secret; the BYOK key is
   // never here). Maintainer DATA: session callers must be a verified maintainer of THIS repo (per-repo
   // scope), so a maintainer of repo A cannot read repo B's config. Server-to-server tokens are exempt.
@@ -6393,6 +6442,7 @@ function canSessionAccessPath(env: Env, identity: Extract<AuthIdentity, { kind:
   if (isRepoAgentPendingActionsPath(path)) return true; // list (GET, requireRepoMaintainer) + propose (POST, requireRepoWriteAccess); decision POSTs on /:id/:decision require server tokens
   if (isRepoIncidentReportsPath(path)) return true; // #5672: route's requireRepoMaintainer enforces per-repo authority (contributors → 403)
   if (isRepoContributorIssueDraftGeneratePath(path)) return true;
+  if (isRepoIssuePlanDraftGeneratePath(path)) return true;
   if (path === OPPORTUNITIES_FIND_PATH) return true;
   if (path === ISSUE_RAG_RETRIEVE_PATH) return true;
   if (path === LINT_PR_TEXT_PATH || path === VALIDATE_FOCUS_MANIFEST_PATH || path === LINT_SLOP_RISK_PATH || path === LINT_ISSUE_SLOP_PATH) return true;
@@ -6442,6 +6492,12 @@ function isRepoContributorIssueDraftGeneratePath(path: string): boolean {
   return /^\/v1\/repos\/[^/]+\/[^/]+\/contributor-issue-drafts\/generate$/.test(path);
 }
 
+// #7764: coarse path admission for the issue-plan-drafts generate route -- the route's own requireAppRole +
+// requireSessionRepoAccess gate enforces real per-repo maintainer authority, exactly like the sibling above.
+function isRepoIssuePlanDraftGeneratePath(path: string): boolean {
+  return /^\/v1\/repos\/[^/]+\/[^/]+\/issue-plan-drafts\/generate$/.test(path);
+}
+
 function isRepoCheckBeforeStartPath(path: string): boolean {
   return /^\/v1\/repos\/[^/]+\/[^/]+\/check-before-start$/.test(path);
 }