feat(mcp): gittensory_explain_score_breakdown

[kiannidev]

Summary

• Adds explainScoreBreakdown as a pure projection over ScorePreviewResult that explains each multiplier (densityMultiplier, credibilityMultiplier, openPrMultiplier, issueMultiplier, review penalty, label bonus) with plain-English summaries and concrete improvement levers.
• Registers the private MCP tool gittensory_explain_score_breakdown in the HTTP MCP server and local MCP package, plus POST /v1/scoring/explain-breakdown for the bin client.
• Returns the single highest-leverage lever and sanitized gate highlights; includes unit and output-schema coverage.

Closes #547

Test plan

• npm run typecheck
• npm run build:mcp
• npm run test:coverage -- test/unit/score-breakdown.test.ts
• Full CI (npm run validate)

Made with Cursor

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#649 is no longer open.	No action.

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[ghost]

gittensory · advisory review

Reviewed 9 changed file(s) — two independent AI reviewers.

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
The PR introduces a new score‑breakdown service, registers a corresponding private tool and API endpoint, adds output schema, updates dependencies, and provides comprehensive unit and integration tests. The implementation sanitizes all public‑facing text, respects access controls, and the tests verify no forbidden language leaks.

Suggestions

• Consider tightening the scoreBreakdownOutputSchema to explicitly type components, gateHighlights, and highestLeverageLever instead of using z.unknown.
• If the newly added ws dependency is not used elsewhere in the project, remove it to keep the bundle lean.
• Add a test case for the error path when contributorLogin is omitted to ensure the proper error is thrown.

Worth double-checking

• Duplicate registration of the tool name (in both CLI bin and server) follows existing patterns, but verify that the registration order does not cause runtime conflicts.
• The lax output schema could allow unexpected shapes; ensure downstream consumers handle the data safely.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds a new MCP tool 'gittensory_explain_score_breakdown' that explains private context multipliers in plain English while respecting the public/private boundary. It includes a new service file, MCP tool registration, API route, and comprehensive unit tests. The implementation properly sanitizes outputs to avoid forbidden terms, enforces access controls, and integrates cleanly with existing scoring logic.

Suggestions

• Add a comment in src/services/score-breakdown.ts explaining the leverageScore calculation rationale (or note they are heuristic) for future maintainability.
• Verify the ws dependency in package.json is intentionally a production dependency (it appears dev-only in lockfile but listed without dev flag). If only used in dev/testing, move to devDependencies.

Worth double-checking

• Hard-coded leverageScore values may require updates if scoring model changes, but are encapsulated and test-covered.
• Relies on internal buildScorePreview function; ensure future changes to scoring logic don't break this tool's assumptions.

[kiannidev]

Hi, @JSONbored
I resolved conflicts.
Please review PR again

Thanks

[JSONbored]

PR #649 — feat(mcp): gittensory_explain_score_breakdown
Author: kiannidev | CI: ✅ pass | Status: Approve
ACTION: Merge

Highlights:

• Endpoint correctly contributor-scoped (requireContributorAccess + requireRepoAccess in both API route and MCP handler).
• Output run through sanitizePublicComment; tests assert no wallet/hotkey/payout/raw-trust leakage.
• Pure deterministic projection over existing ScorePreviewResult; behavior genuinely tested (bands, highest-leverage selection, blocked/reduced branches).