feat(mcp): gittensory_explain_score_breakdown (#649)

* feat(mcp): add gittensory_explain_score_breakdown tool

Expose a private multiplier-by-multiplier score breakdown with concrete improvement levers so miners can see what is holding a preview back.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(mcp): raise score breakdown branch coverage

Add multiplier edge-case and MCP tool-call tests so CI branch coverage stays above the 97% threshold.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(deps): override ws and refresh lockfile for npm audit

New advisories for ws, tar, and js-yaml caused CI audit step to fail.
Pin ws via overrides and refresh the lockfile so npm audit --audit-level=moderate passes.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: kiannidev

package-lock.json

@@ -96,7 +96,8 @@
     },
     "vite": {
       "esbuild": "^0.28.1"
-    }
+    },
+    "ws": "^8.21.0"
   },
   "main": "index.js",
   "directories": {

package.json

@@ -410,6 +410,54 @@ server.registerTool(
   async (input) => toolResult("Gittensory private local PR scoring preview.", await previewLocalScore(await withClientWorkspaceRoots(input))),
 );
 
+server.registerTool(
+  "gittensory_explain_score_breakdown",
+  {
+    description: "Explain a private score preview multiplier-by-multiplier with plain-English levers and the highest-impact improvement.",
+    inputSchema: localScoreShape,
+  },
+  async (input) => {
+    const workspaceInput = await withClientWorkspaceRoots(input);
+    const contributorLogin = workspaceInput.contributorLogin ?? activeProfile.session?.login;
+    if (!contributorLogin) throw new Error("contributorLogin is required for score breakdown.");
+    const workspace = resolveWorkspaceCwd(workspaceInput);
+    const diff = collectLocalDiff(workspace.cwd, workspaceInput.baseRef, workspaceInput.workspaceRoots);
+    const branchPayload = buildBranchAnalysisPayload({
+      ...workspaceInput,
+      login: contributorLogin,
+      cwd: workspace.cwd,
+      repoFullName: workspaceInput.repoFullName,
+      baseRef: workspaceInput.baseRef,
+    });
+    const upstreamPreview = branchPayload.localScorerStatus;
+    const estimatedSourceLines = workspaceInput.sourceLines ?? Math.max(1, diff.changedLineCount - diff.testFiles.length);
+    const body = {
+      repoFullName: workspaceInput.repoFullName,
+      targetType: "local_diff",
+      targetKey: workspaceInput.targetKey ?? localDiffTargetKey(branchPayload, workspaceInput.baseRef),
+      contributorLogin,
+      labels: workspaceInput.labels,
+      linkedIssueMode: workspaceInput.linkedIssueMode,
+      sourceTokenScore: workspaceInput.sourceTokenScore ?? estimatedSourceLines,
+      sourceLines: estimatedSourceLines,
+      totalTokenScore: workspaceInput.totalTokenScore ?? diff.changedLineCount,
+      testTokenScore: diff.testFiles.length,
+      openPrCount: workspaceInput.openPrCount,
+      credibility: workspaceInput.credibility,
+      changesRequestedCount: workspaceInput.changesRequestedCount,
+      pendingMergedPrCount: workspaceInput.pendingMergedPrCount,
+      pendingClosedPrCount: workspaceInput.pendingClosedPrCount,
+      approvedPrCount: workspaceInput.approvedPrCount,
+      expectedOpenPrCountAfterMerge: workspaceInput.expectedOpenPrCountAfterMerge,
+      projectedCredibility: workspaceInput.projectedCredibility,
+      scenarioNotes: workspaceInput.scenarioNotes,
+      branchEligibility: workspaceInput.branchEligibility,
+      metadataOnly: !upstreamPreview.ok,
+    };
+    return toolResult("Gittensory private score breakdown.", await apiPost("/v1/scoring/explain-breakdown", body));
+  },
+);
+
 server.registerTool(
   "gittensory_get_decision_pack",
   {

packages/gittensory-mcp/bin/gittensory-mcp.js

@@ -131,6 +131,7 @@ import {
   preflightBranchWithAgent,
   startAgentRun,
 } from "../services/agent-orchestrator";
+import { explainScoreBreakdown } from "../services/score-breakdown";
 import { buildMcpClientTelemetry } from "../services/client-telemetry";
 import {
   buildAndPersistContributorDecisionPack,
@@ -1458,6 +1459,22 @@ export function createApp() {
     return c.json(record);
   });
 
+  app.post("/v1/scoring/explain-breakdown", async (c) => {
+    const body = await c.req.json().catch(() => null);
+    const parsed = scorePreviewSchema.safeParse(body);
+    if (!parsed.success) return c.json({ error: "invalid_scoring_preview_request", issues: parsed.error.issues }, 400);
+    if (!parsed.data.contributorLogin) return c.json({ error: "contributor_login_required" }, 400);
+    const unauthorized = await requireContributorAccess(c, parsed.data.contributorLogin);
+    if (unauthorized) return unauthorized;
+    const [repo, snapshot, evidence] = await Promise.all([
+      getRepository(c.env, parsed.data.repoFullName),
+      getOrCreateScoringModelSnapshot(c.env),
+      getContributorEvidence(c.env, parsed.data.contributorLogin),
+    ]);
+    const preview = buildScorePreview({ input: parsed.data, repo, snapshot, contributorEvidence: evidence });
+    return c.json(explainScoreBreakdown(preview));
+  });
+
   app.get("/v1/sync/status", async (c) => {
     const [snapshot, scoringSnapshot, repositories, segments, totals, detailStates, installations, rateLimits, signalSnapshots, bounties, upstreamDrift] = await Promise.all([
       getLatestRegistrySnapshot(c.env),

src/api/routes.ts

@@ -52,6 +52,7 @@ import {
 } from "../services/agent-orchestrator";
 import { loadContributorDecisionPackForServing, repoDecisionFromPack } from "../services/decision-pack";
 import { buildPublicPrBodyDraft } from "../services/pr-body-draft";
+import { explainScoreBreakdown } from "../services/score-breakdown";
 import { loadOrComputeIssueQualityResponse } from "../services/issue-quality";
 import { loadOrComputeBurdenForecastResponse } from "../services/burden-forecast";
 import { buildMcpClientTelemetry } from "../services/client-telemetry";
@@ -532,6 +533,15 @@ const checkBeforeStartOutputSchema = {
   report: z.unknown().optional(),
 };
 
+const scoreBreakdownOutputSchema = {
+  repoFullName: z.string().optional(),
+  scoreabilityStatus: z.string().optional(),
+  effectiveEstimatedScore: z.number().optional(),
+  components: z.unknown().optional(),
+  gateHighlights: z.unknown().optional(),
+  highestLeverageLever: z.unknown().optional(),
+};
+
 const lintPrTextOutputSchema = {
   verdict: z.string().optional(),
   score: z.number().optional(),
@@ -977,6 +987,17 @@ export class GittensoryMcp {
       async (input) => this.toolResult(await this.previewScore(input)),
     );
 
+    server.registerTool(
+      "gittensory_explain_score_breakdown",
+      {
+        description:
+          "Explain a private score preview multiplier-by-multiplier with plain-English levers and the single highest-impact improvement. Login and repo scoped; no new computation beyond the preview projection.",
+        inputSchema: scorePreviewShape,
+        outputSchema: scoreBreakdownOutputSchema,
+      },
+      async (input) => this.toolResult(await this.explainScoreBreakdown(input)),
+    );
+
     server.registerTool(
       "gittensory_explain_review_risk",
       {
@@ -1689,6 +1710,23 @@ export class GittensoryMcp {
     };
   }
 
+  private async explainScoreBreakdown(input: z.infer<z.ZodObject<typeof scorePreviewShape>>): Promise<ToolPayload> {
+    if (!input.contributorLogin) throw new Error("contributorLogin is required for score breakdown.");
+    this.requireContributorAccess(input.contributorLogin);
+    await this.requireRepoAccess(input.repoFullName);
+    const [repo, snapshot, evidence] = await Promise.all([
+      getRepository(this.env, input.repoFullName),
+      getOrCreateScoringModelSnapshot(this.env),
+      getContributorEvidence(this.env, input.contributorLogin),
+    ]);
+    const preview = buildScorePreview({ input, repo, snapshot, contributorEvidence: evidence });
+    const breakdown = explainScoreBreakdown(preview);
+    return {
+      summary: `Private Gittensory score breakdown for ${input.contributorLogin} in ${input.repoFullName}. Highest leverage: ${breakdown.highestLeverageLever.component}.`,
+      data: breakdown as unknown as Record<string, unknown>,
+    };
+  }
+
   private async explainReviewRisk(input: z.infer<z.ZodObject<typeof preflightShape>>): Promise<ToolPayload> {
     if (input.contributorLogin) this.requireContributorAccess(input.contributorLogin);
     await this.requireRepoAccess(input.repoFullName);