feat(mcp): register the pilot tools from the shared contract, and fix three drifted OpenAPI schemas

Both MCP servers now take the six pilot tools' input AND output schemas from
@loopover/contract instead of declaring them locally. The stdio server's
hand-mirrored shapes are gone for these tools, and four of them gain a real
outputSchema for the first time -- previously only loopover_local_status_structured
declared one anywhere in that package.

Fixes found while modelling the real payloads, all cases of the published spec
disagreeing with what the code actually returns:

- CollisionItemSchema's `type` enum omitted "recent_merged_pull_request", which
  buildCollisionReport genuinely emits (it is handed recent merged PRs). A client
  validating a real response against the spec rejected it. Its labels, linkedIssues,
  linkedIssueClaimedAt, changedFiles and body fields were missing too.
- QueueHealthSchema omitted draftPullRequests, slopFlaggedPullRequests and
  duplicateFlaggedPullRequests -- all required on the QueueHealth type and always
  emitted -- plus the optional rankedPullRequests array.

openapi.json is regenerated to match.

Refs #9517

Author: JSONbored

apps/loopover-ui/public/openapi.json

@@ -1417,15 +1417,27 @@
                   "sampled_cache",
                   "authoritative"
                 ]
+              },
+              "draftPullRequests": {
+                "type": "number"
+              },
+              "slopFlaggedPullRequests": {
+                "type": "number"
+              },
+              "duplicateFlaggedPullRequests": {
+                "type": "number"
               }
             },
             "required": [
               "openIssues",
               "openPullRequests",
               "unlinkedPullRequests",
               "stalePullRequests",
+              "draftPullRequests",
               "maintainerAuthoredPullRequests",
               "collisionClusters",
+              "slopFlaggedPullRequests",
+              "duplicateFlaggedPullRequests",
               "ageBuckets",
               "likelyReviewablePullRequests"
             ]
@@ -1435,6 +1447,32 @@
             "items": {
               "$ref": "#/components/schemas/Finding"
             }
+          },
+          "rankedPullRequests": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "number": {
+                  "type": "number"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "authorLogin": {
+                  "type": "string"
+                },
+                "recommendation": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "number",
+                "title",
+                "authorLogin",
+                "recommendation"
+              ]
+            }
           }
         },
         "required": [
@@ -1527,7 +1565,8 @@
             "type": "string",
             "enum": [
               "issue",
-              "pull_request"
+              "pull_request",
+              "recent_merged_pull_request"
             ]
           },
           "number": {
@@ -1543,6 +1582,32 @@
           "htmlUrl": {
             "type": "string",
             "nullable": true
+          },
+          "labels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "linkedIssues": {
+            "type": "array",
+            "items": {
+              "type": "number"
+            }
+          },
+          "linkedIssueClaimedAt": {
+            "type": "string",
+            "nullable": true
+          },
+          "changedFiles": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "body": {
+            "type": "string",
+            "nullable": true
           }
         },
         "required": [

package-lock.json

@@ -124,6 +124,7 @@
     "@asteasolutions/zod-to-openapi": "^8.5.0",
     "@cloudflare/puppeteer": "^1.1.0",
     "@hono/node-server": "^2.0.11",
+    "@loopover/contract": "^0.1.0",
     "@loopover/engine": "*",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@octokit/core": "^7.0.6",

package.json

@@ -40,6 +40,21 @@ import { buildProgressSnapshot } from "@loopover/engine";
 // #6755: the same pure bridge the remote MCP tool + /v1/loop/intake-idea both call.
 import { validateIdeaSubmission, buildTaskGraph, buildClaimPlan } from "@loopover/engine";
 import { z } from "zod";
+// #9517: pilot-tool schemas come from the shared contract, replacing shapes this file previously
+// hand-mirrored from src/mcp/server.ts. Output schemas arrive with them, so these tools stop
+// returning unschematized structured content.
+import {
+  GetPrReviewabilityInput,
+  GetPrReviewabilityOutput,
+  GetRepoContextInput,
+  GetRepoContextOutput,
+  LocalStatusStructuredInput,
+  LocalStatusStructuredOutput,
+  PredictGateInput,
+  PredictGateOutput,
+  PreflightPrInput,
+  PreflightPrOutput,
+} from "@loopover/contract/tools";
 import { buildBranchAnalysisPayload, collectLocalDiff, collectLocalBranchMetadata, probeLocalScorer, referenceScorePreviewExample, resolveScorePreviewCommand, resolveWorkspaceCwd, sanitizeLocalScorerStatus, setupGuidanceForLocalScorer, isTestFile } from "../lib/local-branch.js";
 import { formatTable } from "../lib/format-table.js";
 import { argsWantJson, describeCliError, reportCliFailure } from "../lib/cli-error.js";
@@ -1747,7 +1762,8 @@ registerStdioTool(
   "loopover_get_repo_context",
   {
     description: stdioToolDescription("loopover_get_repo_context"),
-    inputSchema: ownerRepoShape,
+    inputSchema: GetRepoContextInput.shape,
+    outputSchema: GetRepoContextOutput.shape,
   },
   async ({ owner, repo }: any) => {
     const prefix = `/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
@@ -1759,7 +1775,8 @@ registerStdioTool(
   "loopover_get_pr_reviewability",
   {
     description: stdioToolDescription("loopover_get_pr_reviewability"),
-    inputSchema: ownerRepoPullShape,
+    inputSchema: GetPrReviewabilityInput.shape,
+    outputSchema: GetPrReviewabilityOutput.shape,
   },
   async ({ owner, repo, number }: any) => {
     const prefix = `/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
@@ -1987,7 +2004,8 @@ registerStdioTool(
   "loopover_preflight_pr",
   {
     description: stdioToolDescription("loopover_preflight_pr"),
-    inputSchema: preflightShape,
+    inputSchema: PreflightPrInput.shape,
+    outputSchema: PreflightPrOutput.shape,
   },
   async (input: any) => toolResult("LoopOver PR preflight.", await apiPost("/v1/preflight/pr", input)),
 );
@@ -2294,7 +2312,8 @@ registerStdioTool(
   "loopover_predict_gate",
   {
     description: stdioToolDescription("loopover_predict_gate"),
-    inputSchema: predictGateShape,
+    inputSchema: PredictGateInput.shape,
+    outputSchema: PredictGateOutput.shape,
   },
   async (input: any) => {
     const body = {
@@ -2962,22 +2981,8 @@ registerStdioTool(
   "loopover_local_status_structured",
   {
     description: stdioToolDescription("loopover_local_status_structured"),
-    inputSchema: {
-      cwd: z.string().optional(),
-      baseRef: z.string().optional(),
-      repoFullName: z.string().min(3).optional(),
-    },
-    outputSchema: z.object({
-      apiUrl: z.string(),
-      package: z.object({ name: z.string(), version: z.string() }),
-      hasToken: z.boolean(),
-      profile: z.record(z.string(), z.unknown()),
-      authLogin: z.string().nullable(),
-      sessionExpiresAt: z.string().nullable(),
-      sourceUploadDefault: z.boolean(),
-      sourceUploadSupported: z.boolean(),
-      git: z.record(z.string(), z.unknown()),
-    }),
+    inputSchema: LocalStatusStructuredInput.shape,
+    outputSchema: LocalStatusStructuredOutput.shape,
   },
   async (input: any) => {
     let git = null;

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

@@ -45,6 +45,7 @@
     "build:verify": "node scripts/check-syntax.mjs"
   },
   "dependencies": {
+    "@loopover/contract": "^0.1.0",
     "@loopover/engine": "^3.15.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "posthog-node": "^5.46.1",

packages/loopover-mcp/package.json

@@ -4,6 +4,22 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { ElicitResultSchema, type ServerNotification, type ServerRequest } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+// #9517: the pilot tools' schemas come from the shared contract instead of being declared here.
+// `.shape` is what the MCP SDK's registerTool wants; the same ZodObject also drives the JSON Schema
+// the agent-tool specs and the contract validator read, so there is one definition per tool rather
+// than one per server.
+import {
+  AdminGetConfigInput,
+  AdminGetConfigOutput,
+  GetPrReviewabilityInput,
+  GetPrReviewabilityOutput,
+  GetRepoContextInput,
+  GetRepoContextOutput,
+  PredictGateInput,
+  PredictGateOutput,
+  PreflightPrInput,
+  PreflightPrOutput,
+} from "@loopover/contract/tools";
 import {
   MAX_FIND_OPPORTUNITIES_LANGUAGE_LENGTH,
   MAX_FIND_OPPORTUNITIES_LANGUAGES,
@@ -2180,8 +2196,8 @@ export class LoopoverMcp {
       "loopover_get_repo_context",
       {
         description: "Return LoopOver repo context: registration, lane, queue health, collisions, and config quality.",
-        inputSchema: ownerRepoShape,
-        outputSchema: repoContextOutputSchema,
+        inputSchema: GetRepoContextInput.shape,
+        outputSchema: GetRepoContextOutput.shape,
       },
       async (input) => this.toolResult(await this.getRepoContext(input)),
     );
@@ -2454,8 +2470,8 @@ export class LoopoverMcp {
       {
         description:
           "Predict whether a planned PR would pass the repo's LoopOver gate, from its PUBLIC .loopover.yml only — an agent-native pre-submission self-check that works on ANY repo (no Gittensor account). Under the oss-anti-slop pack the verdict applies to any author; self-scoped to the authenticated login.",
-        inputSchema: predictGateShape,
-        outputSchema: predictGateOutputSchema,
+        inputSchema: PredictGateInput.shape,
+        outputSchema: PredictGateOutput.shape,
       },
       async (input) => this.toolResult(await this.predictGate(input)),
     );
@@ -2650,8 +2666,8 @@ export class LoopoverMcp {
       "loopover_preflight_pr",
       {
         description: "Preflight a planned PR for lane correctness, duplicate risk, linked issues, and review burden.",
-        inputSchema: preflightShape,
-        outputSchema: preflightResultOutputSchema,
+        inputSchema: PreflightPrInput.shape,
+        outputSchema: PreflightPrOutput.shape,
       },
       async (input) => this.toolResult(await this.preflightPr(input)),
     );
@@ -2742,8 +2758,8 @@ export class LoopoverMcp {
       {
         description:
           "Return the cached or freshly-computed reviewability report for an open PR: how ready it is to review/merge, the blocking or advisory signals against it, and its lane/duplicate/linked-issue context. Metadata-only, repo-scoped, no GitHub writes.",
-        inputSchema: ownerRepoPullShape,
-        outputSchema: freshnessResponseOutputSchema,
+        inputSchema: GetPrReviewabilityInput.shape,
+        outputSchema: GetPrReviewabilityOutput.shape,
       },
       async (input) => this.toolResult(await this.getPrReviewability(input)),
     );
@@ -3298,8 +3314,8 @@ export class LoopoverMcp {
         {
           description:
             "Self-hosted-operator only. Read this instance's own private .loopover.yml config: the merged effective config for a repo (shared base + global default + per-repo override), or just the raw global-default layer, or just the raw per-repo layer. Requires LOOPOVER_MCP_ADMIN_TOKEN. Returns configured=false if LOOPOVER_REPO_CONFIG_DIR is unset.",
-          inputSchema: adminConfigScopeShape,
-          outputSchema: adminGetConfigOutputSchema,
+          inputSchema: AdminGetConfigInput.shape,
+          outputSchema: AdminGetConfigOutput.shape,
         },
         async (input) => this.toolResult(await this.adminGetConfig(input)),
       );

src/mcp/server.ts

@@ -265,13 +265,22 @@ export const LaneAdviceSchema = z
   })
   .openapi("LaneAdvice");
 
+// #9517: `recent_merged_pull_request` was missing from `type` even though buildCollisionReport is
+// handed recent merged PRs and emits items with exactly that discriminant -- so a client validating
+// a real response against the published spec rejected it. The remaining fields were absent too,
+// which understated what this endpoint actually returns.
 export const CollisionItemSchema = z
   .object({
-    type: z.enum(["issue", "pull_request"]),
+    type: z.enum(["issue", "pull_request", "recent_merged_pull_request"]),
     number: z.number(),
     title: z.string(),
     authorLogin: z.string().nullable().optional(),
     htmlUrl: z.string().nullable().optional(),
+    labels: z.array(z.string()).optional(),
+    linkedIssues: z.array(z.number()).optional(),
+    linkedIssueClaimedAt: z.string().nullable().optional(),
+    changedFiles: z.array(z.string()).optional(),
+    body: z.string().nullable().optional(),
   })
   .openapi("CollisionItem");
 
@@ -304,13 +313,20 @@ export const QueueHealthSchema = z
     burdenScore: z.number(),
     level: z.enum(["low", "medium", "high", "critical"]),
     summary: z.string(),
+    // #9517: draftPullRequests, slopFlaggedPullRequests and duplicateFlaggedPullRequests are all
+    // REQUIRED on the QueueHealth type and always emitted by buildQueueHealth, but were missing
+    // here -- the published spec understated the response. The two flagged counts are deliberately
+    // public-safe counts, carrying no score or ranking detail.
     signals: z.object({
       openIssues: z.number(),
       openPullRequests: z.number(),
       unlinkedPullRequests: z.number(),
       stalePullRequests: z.number(),
+      draftPullRequests: z.number(),
       maintainerAuthoredPullRequests: z.number(),
       collisionClusters: z.number(),
+      slopFlaggedPullRequests: z.number(),
+      duplicateFlaggedPullRequests: z.number(),
       ageBuckets: z.object({
         under7Days: z.number(),
         days7To30: z.number(),
@@ -321,6 +337,16 @@ export const QueueHealthSchema = z
       likelyReviewablePullRequestsSource: z.enum(["cache", "sampled_cache", "authoritative"]).optional(),
     }),
     findings: z.array(FindingSchema),
+    rankedPullRequests: z
+      .array(
+        z.object({
+          number: z.number(),
+          title: z.string(),
+          authorLogin: z.string(),
+          recommendation: z.string(),
+        }),
+      )
+      .optional(),
   })
   .openapi("QueueHealth");