feat(mcp): add remote + stdio surfaces for loopover_get_upstream_ruleset (#7921)

Mirror loopover_get_upstream_drift on both the remote MCP server and local
stdio wrapper. Cover found/not-found remotely and instrument the bin via the
#7764 in-process exported-server pattern so codecov/patch sees the new lines
(unlike bin-only #7855).

Closes #7807

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

Author: RealDiligent

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

@@ -1138,6 +1138,12 @@ const STDIO_TOOL_DESCRIPTORS = [
     category: "utility",
     description: "Return the latest cached Gittensor upstream ruleset drift status (stale/drift warnings) for MCP planning.",
   },
+  {
+    name: "loopover_get_upstream_ruleset",
+    category: "utility",
+    description:
+      "Return the latest cached upstream Gittensor ruleset snapshot (the raw current ruleset — active model, registry counts, and payload — not the drift report). Read-only; takes no parameters. Public/unauthenticated, same as GET /v1/upstream/ruleset.",
+  },
   {
     name: "loopover_get_bounty_advisory",
     category: "discovery",
@@ -2011,6 +2017,15 @@ registerStdioTool(
   async () => toolResult("LoopOver upstream drift status.", await apiGet("/v1/upstream/drift")),
 );
 
+registerStdioTool(
+  "loopover_get_upstream_ruleset",
+  {
+    description: stdioToolDescription("loopover_get_upstream_ruleset"),
+    inputSchema: {},
+  },
+  async () => toolResult("LoopOver upstream ruleset snapshot.", await apiGet("/v1/upstream/ruleset")),
+);
+
 registerStdioTool(
   "loopover_get_label_audit",
   {

src/mcp/server.ts

@@ -46,6 +46,7 @@ import {
   getPullRequest,
   getRepository,
   getRepositorySettings,
+  getLatestUpstreamRulesetSnapshot,
   isGlobalAgentFrozen,
   getRepoQueueTrendSnapshot,
   listAgentAuditEvents,
@@ -1436,6 +1437,22 @@ const upstreamDriftOutputSchema = {
   reports: z.unknown().optional(),
 };
 
+const upstreamRulesetOutputSchema = {
+  id: z.string().optional(),
+  sourceRepo: z.string().optional(),
+  sourceRef: z.string().optional(),
+  commitSha: z.string().optional(),
+  sourceSnapshotIds: z.unknown().optional(),
+  activeModel: z.string().optional(),
+  registryRepoCount: z.number().optional(),
+  totalEmissionShare: z.number().optional(),
+  semanticHash: z.string().optional(),
+  payload: z.unknown().optional(),
+  warnings: z.unknown().optional(),
+  generatedAt: z.string().optional(),
+  error: z.string().optional(),
+};
+
 const localStatusOutputSchema = {
   apiAvailable: z.boolean().optional(),
   sourceUploadDefault: z.boolean().optional(),
@@ -1867,6 +1884,7 @@ export const MCP_TOOL_CATEGORIES: Record<string, McpToolCategory> = {
   loopover_get_registry_changes: "utility",
   loopover_get_registry_snapshot: "utility",
   loopover_get_upstream_drift: "utility",
+  loopover_get_upstream_ruleset: "utility",
   loopover_get_issue_quality: "maintainer",
   loopover_get_pr_reviewability: "review",
   loopover_validate_linked_issue: "discovery",
@@ -2388,6 +2406,17 @@ export class LoopoverMcp {
       async () => this.toolResult(await this.getUpstreamDrift()),
     );
 
+    register(
+      "loopover_get_upstream_ruleset",
+      {
+        description:
+          "Return the latest cached upstream Gittensor ruleset snapshot (the raw current ruleset — active model, registry counts, and payload — not the drift report). Read-only; takes no parameters. Public/unauthenticated, same as GET /v1/upstream/ruleset.",
+        inputSchema: {},
+        outputSchema: upstreamRulesetOutputSchema,
+      },
+      async () => this.toolResult(await this.getUpstreamRuleset()),
+    );
+
     register(
       "loopover_get_issue_quality",
       {
@@ -4101,6 +4130,22 @@ export class LoopoverMcp {
     };
   }
 
+  private async getUpstreamRuleset(): Promise<ToolPayload> {
+    // Mirrors GET /v1/upstream/ruleset: return the raw latest ruleset snapshot, or a normal not-found
+    // result (never throw) when nothing has been synced yet — same error code the REST route uses.
+    const ruleset = await getLatestUpstreamRulesetSnapshot(this.env);
+    if (!ruleset) {
+      return {
+        summary: "No upstream ruleset snapshot has been synced yet.",
+        data: { error: "upstream_ruleset_not_found" },
+      };
+    }
+    return {
+      summary: `Latest upstream ruleset snapshot (${ruleset.activeModel}, ${ruleset.registryRepoCount} repos).`,
+      data: ruleset as unknown as Record<string, unknown>,
+    };
+  }
+
   private async preflightPr(input: z.infer<z.ZodObject<typeof preflightShape>>): Promise<ToolPayload> {
     await this.requireRepoAccess(input.repoFullName);
     const [repo, issues, pullRequests, bounties, issueQuality] = await Promise.all([

test/integration/api.test.ts

@@ -5527,6 +5527,7 @@ describe("api routes", () => {
     expect(toolNames).toContain("loopover_get_registry_changes");
     expect(toolNames).toContain("loopover_get_registry_snapshot");
     expect(toolNames).toContain("loopover_get_upstream_drift");
+    expect(toolNames).toContain("loopover_get_upstream_ruleset");
     expect(toolNames).toContain("loopover_explain_review_risk");
     expect(toolNames).toContain("loopover_compare_pr_variants");
     expect(toolNames).toContain("loopover_local_status");
@@ -5800,6 +5801,7 @@ describe("api routes", () => {
       ["loopover_get_registry_changes", {}],
       ["loopover_get_registry_snapshot", {}],
       ["loopover_get_upstream_drift", {}],
+      ["loopover_get_upstream_ruleset", {}],
       [
         "loopover_preview_local_pr_score",
         {

test/unit/mcp-cli-upstream-ruleset.test.ts

@@ -0,0 +1,76 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { closeFixtureServer, startFixtureServer } from "./support/mcp-cli-harness";
+
+// #7807: in-process coverage for the loopover_get_upstream_ruleset stdio tool in
+// packages/loopover-mcp/bin/loopover-mcp.ts. Same #7764 entrypoint-guard pattern as
+// mcp-cli-registry-snapshot.test.ts — import the .ts source, hold the exported `server`, and connect
+// an in-memory transport so v8/Codecov attributes the new registerStdioTool lines. Subprocess spawn
+// alone does not instrument the bin (that is why #7855's bin lines got 0% patch).
+const MODULES = ["../../packages/loopover-mcp/bin/loopover-mcp.ts"] as const;
+
+type BinModule = {
+  server: { connect: (transport: unknown) => Promise<void> };
+};
+
+let tempDir = "";
+const capturedRequests: Array<{ url: string; method: string }> = [];
+const loaded = new Map<string, BinModule>();
+
+beforeAll(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "loopover-upstream-ruleset-"));
+  const apiUrl = await startFixtureServer({
+    onApiRequest: (request) => {
+      if (request.url === "/v1/upstream/ruleset") {
+        capturedRequests.push({ url: request.url ?? "", method: request.method ?? "GET" });
+      }
+    },
+  });
+  process.env.LOOPOVER_API_URL = apiUrl;
+  process.env.LOOPOVER_API_TOKEN = "in-process-token";
+  process.env.LOOPOVER_API_TIMEOUT_MS = "2000";
+  process.env.LOOPOVER_CONFIG_DIR = tempDir;
+  process.env.LOOPOVER_SKIP_NPM_VERSION_CHECK = "1";
+  for (const specifier of MODULES) {
+    loaded.set(specifier, (await import(specifier)) as unknown as BinModule);
+  }
+}, 120_000);
+
+afterAll(async () => {
+  await closeFixtureServer();
+  if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  delete process.env.LOOPOVER_API_URL;
+  delete process.env.LOOPOVER_API_TOKEN;
+  delete process.env.LOOPOVER_CONFIG_DIR;
+  delete process.env.LOOPOVER_SKIP_NPM_VERSION_CHECK;
+});
+
+describe("bin loopover_get_upstream_ruleset stdio tool (in-process, #7807)", () => {
+  it.each(MODULES)("registers and proxies GET /v1/upstream/ruleset — %s", async (specifier) => {
+    capturedRequests.length = 0;
+    const mod = loaded.get(specifier)!;
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await mod.server.connect(serverTransport);
+    const client = new Client({ name: "upstream-ruleset-test", version: "0.1.0" }, { capabilities: {} });
+    await client.connect(clientTransport);
+    try {
+      const { tools } = await client.listTools();
+      const tool = tools.find((entry) => entry.name === "loopover_get_upstream_ruleset");
+      expect(tool).toBeDefined();
+      expect(tool?.description).toMatch(/upstream.*ruleset|ruleset snapshot/i);
+
+      const result = await client.callTool({ name: "loopover_get_upstream_ruleset", arguments: {} });
+      expect(capturedRequests).toEqual([{ url: "/v1/upstream/ruleset", method: "GET" }]);
+      expect(result.isError).toBeFalsy();
+      const text = JSON.stringify(result);
+      expect(text).toContain("fixture-ruleset");
+      expect(text).toContain("pending_saturation_model");
+    } finally {
+      await client.close().catch(() => undefined);
+    }
+  });
+});

test/unit/mcp-output-schemas.test.ts

@@ -1,7 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, it, vi } from "vitest";
-import { persistSignalSnapshot, upsertBounty, upsertIssueFromGitHub, upsertPullRequestFromGitHub, upsertRepositoryFromGitHub, updatePullRequestSlopAssessment } from "../../src/db/repositories";
+import { persistSignalSnapshot, upsertBounty, upsertIssueFromGitHub, upsertPullRequestFromGitHub, upsertRepositoryFromGitHub, updatePullRequestSlopAssessment, persistUpstreamRulesetSnapshot } from "../../src/db/repositories";
 import type { AuthIdentity } from "../../src/auth/security";
 import { LoopoverMcp } from "../../src/mcp/server";
 import { normalizeRegistryPayload } from "../../src/registry/normalize";
@@ -36,6 +36,7 @@ const TOOLS_WITH_OUTPUT_SCHEMA = [
   "loopover_get_registry_changes",
   "loopover_get_registry_snapshot",
   "loopover_get_upstream_drift",
+  "loopover_get_upstream_ruleset",
   "loopover_local_status",
   "loopover_remediation_plan",
   "loopover_explain_score_breakdown",
@@ -142,6 +143,10 @@ describe("MCP output schema discovery", () => {
     const registrySnapshot = byName.get("loopover_get_registry_snapshot");
     const registrySnapshotProps = Object.keys((registrySnapshot?.outputSchema?.properties ?? {}) as Record<string, unknown>);
     expect(registrySnapshotProps).toEqual(expect.arrayContaining(["id", "repoCount", "repositories", "error"]));
+
+    const upstreamRuleset = byName.get("loopover_get_upstream_ruleset");
+    const upstreamRulesetProps = Object.keys((upstreamRuleset?.outputSchema?.properties ?? {}) as Record<string, unknown>);
+    expect(upstreamRulesetProps).toEqual(expect.arrayContaining(["id", "activeModel", "registryRepoCount", "payload", "error"]));
   });
 
   it("preserves the full tool inventory while adding output schemas", async () => {
@@ -217,6 +222,27 @@ describe("MCP tool calls return schema-valid structured content", () => {
     expect(result.structuredContent).toEqual({ error: "registry_snapshot_not_found" });
   });
 
+  it("loopover_get_upstream_ruleset returns the latest ruleset when one exists (#7807)", async () => {
+    const env = createTestEnv();
+    await seedUpstreamRulesetSnapshot(env);
+    const { client } = await connectTestClient(env);
+    const result = await client.callTool({ name: "loopover_get_upstream_ruleset", arguments: {} });
+    expect(result.isError).toBeFalsy();
+    expect(result.structuredContent).toMatchObject({
+      id: "fixture-upstream-ruleset",
+      activeModel: "pending_saturation_model",
+      registryRepoCount: 1,
+    });
+    expect(JSON.stringify(result.structuredContent)).not.toContain("upstream_ruleset_not_found");
+  });
+
+  it("loopover_get_upstream_ruleset returns a normal not-found result when empty (#7807)", async () => {
+    const { client } = await connectTestClient(createTestEnv());
+    const result = await client.callTool({ name: "loopover_get_upstream_ruleset", arguments: {} });
+    expect(result.isError).toBeFalsy();
+    expect(result.structuredContent).toEqual({ error: "upstream_ruleset_not_found" });
+  });
+
   it("loopover_get_repo_context returns validated structured content", async () => {
     const { client } = await connectTestClient();
     const result = await client.callTool({ name: "loopover_get_repo_context", arguments: { owner: "octo", repo: "demo" } });
@@ -682,7 +708,7 @@ describe("MCP output schemas do not declare private financial fields", () => {
   it("structured content from public-safe tools never includes redacted financial keys", async () => {
     const { client } = await connectTestClient();
 
-    for (const name of ["loopover_local_status", "loopover_get_upstream_drift", "loopover_get_registry_changes", "loopover_get_registry_snapshot"]) {
+    for (const name of ["loopover_local_status", "loopover_get_upstream_drift", "loopover_get_upstream_ruleset", "loopover_get_registry_changes", "loopover_get_registry_snapshot"]) {
       const result = await client.callTool({ name, arguments: {} });
       const serialized = JSON.stringify(result.structuredContent ?? {});
       expect(serialized, `tool "${name}" structured content must not leak financial fields`).not.toMatch(
@@ -719,6 +745,29 @@ async function seedRegistryChangeSnapshots(env: Env) {
   );
 }
 
+async function seedUpstreamRulesetSnapshot(env: Env) {
+  await persistUpstreamRulesetSnapshot(env, {
+    id: "fixture-upstream-ruleset",
+    sourceRepo: "entrius/gittensor",
+    sourceRef: "test",
+    commitSha: "fixture-commit",
+    sourceSnapshotIds: [],
+    activeModel: "pending_saturation_model",
+    registryRepoCount: 1,
+    totalEmissionShare: 0.01,
+    semanticHash: "fixture-semantic-hash",
+    payload: {
+      registry: {
+        repoCount: 1,
+        totalEmissionShare: 0.01,
+        repositories: [],
+      },
+    },
+    warnings: [],
+    generatedAt: "2026-05-30T00:00:00.000Z",
+  });
+}
+
 function repoOutcomePatternsPayload(repoFullName: string, generatedAt: string) {
   return {
     repoFullName,

test/unit/mcp-tool-rename-aliases.test.ts

@@ -25,6 +25,7 @@
 // (#7764 registered the loopover_plan_repo_issues stdio + CLI + REST tool, taking the count from 80 to 81.)
 // (#7887 registered loopover_get_activation_preview without bumping this pin — live count became 82.)
 // (#7803 registered the loopover_get_registry_snapshot remote+stdio tool, taking the count from 82 to 83.)
+// (#7807 registered the loopover_get_upstream_ruleset remote+stdio tool, taking the count from 83 to 84.)
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { mkdtempSync, rmSync } from "node:fs";
@@ -71,14 +72,14 @@ describe("MCP legacy alias retirement (#4777) — discovery invariants", () => {
   });
   afterEach(disconnect);
 
-  it("lists exactly 83 loopover_ tools and zero gittensory_-prefixed aliases", async () => {
+  it("lists exactly 84 loopover_ tools and zero gittensory_-prefixed aliases", async () => {
     const { tools } = await client.listTools();
     const names = tools.map((t) => t.name);
     const primary = names.filter((n) => n.startsWith("loopover_"));
     const legacy = names.filter((n) => n.startsWith("gittensory_"));
-    expect(primary.length).toBe(83);
+    expect(primary.length).toBe(84);
     expect(legacy.length).toBe(0);
-    expect(names.length).toBe(83);
+    expect(names.length).toBe(84);
   });
 
   it("no loopover_ tool's description carries a stale deprecation notice", async () => {
@@ -90,14 +91,14 @@ describe("MCP legacy alias retirement (#4777) — discovery invariants", () => {
     }
   });
 
-  it("`loopover-mcp tools --json` reports the same 83-tool count the live server registers", async () => {
+  it("`loopover-mcp tools --json` reports the same 84-tool count the live server registers", async () => {
     const { tools } = await client.listTools();
     const payload = JSON.parse(run(["tools", "--json"])) as {
       count: number;
       tools: Array<{ name: string }>;
     };
     expect(payload.count).toBe(tools.length);
-    expect(payload.count).toBe(83);
+    expect(payload.count).toBe(84);
     expect([...payload.tools.map((t) => t.name)].sort()).toEqual(
       [...tools.map((t) => t.name)].sort(),
     );

test/unit/support/mcp-cli-harness.ts

@@ -779,6 +779,26 @@ export async function startFixtureServer(
       );
       return;
     }
+    // #7807: public upstream ruleset snapshot (raw current ruleset, not the drift report). No auth.
+    if (request.url === "/v1/upstream/ruleset" && request.method === "GET") {
+      response.end(
+        JSON.stringify({
+          id: "fixture-ruleset",
+          sourceRepo: "entrius/gittensor",
+          sourceRef: "test",
+          commitSha: "fixture-commit",
+          sourceSnapshotIds: [],
+          activeModel: "pending_saturation_model",
+          registryRepoCount: 1,
+          totalEmissionShare: 0.01,
+          semanticHash: "fixture-semantic-hash",
+          payload: { registry: { repoCount: 1 } },
+          warnings: [],
+          generatedAt: "2026-05-30T00:00:00.000Z",
+        }),
+      );
+      return;
+    }
     // #7803: public registry snapshot (raw current snapshot, not a diff). No auth.
     if (request.url === "/v1/registry/snapshot" && request.method === "GET") {
       response.end(