feat(mcp): add REST + CLI mirrors for finding and enrichment taxonomies (#6620)

Author: andriypolanski

packages/loopover-mcp/bin/loopover-mcp.js

@@ -50,6 +50,8 @@ const npmRegistryUrl = (process.env.LOOPOVER_NPM_REGISTRY_URL ?? "https://regist
 const upgradeCommand = `npm install -g ${packageName}@latest`;
 const npxFallbackCommand = `npx ${packageName}@latest <command>`;
 const compatibilityPath = "/v1/mcp/compatibility";
+const findingTaxonomyPath = "/v1/mcp/finding-taxonomy";
+const enrichmentAnalyzersPath = "/v1/mcp/enrichment-analyzers";
 const currentApiVersion = "0.1.0";
 const decisionPackCacheSchemaVersion = 1;
 const decisionPackCacheMaxEntries = 25;
@@ -2137,14 +2139,52 @@ server.registerResource(
   async () => {
     let data;
     try {
-      data = await apiGet(compatibilityPath);
+      data = await apiFetch(compatibilityPath, { method: "GET" }, { auth: false });
     } catch {
       data = { status: "unavailable", currentApiVersion, packageVersion };
     }
     return { contents: [{ uri: "loopover://compatibility", mimeType: "application/json", text: JSON.stringify(data, null, 2) }] };
   },
 );
 
+server.registerResource(
+  "loopover_finding_taxonomy",
+  "loopover://finding-taxonomy",
+  {
+    title: "LoopOver Finding Taxonomy",
+    description: "Canonical AI review finding categories and severity levels for discovery without hard-coding.",
+    mimeType: "application/json",
+  },
+  async () => {
+    let data;
+    try {
+      data = await apiFetch(findingTaxonomyPath, { method: "GET" }, { auth: false });
+    } catch {
+      data = { status: "unavailable" };
+    }
+    return { contents: [{ uri: "loopover://finding-taxonomy", mimeType: "application/json", text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
+server.registerResource(
+  "loopover_enrichment_analyzers",
+  "gittensory://enrichment-analyzers",
+  {
+    title: "LoopOver Enrichment Analyzers",
+    description: "REES enrichment analyzer taxonomy: names, categories, cost classes, and default profiles.",
+    mimeType: "application/json",
+  },
+  async () => {
+    let data;
+    try {
+      data = await apiFetch(enrichmentAnalyzersPath, { method: "GET" }, { auth: false });
+    } catch {
+      data = { status: "unavailable" };
+    }
+    return { contents: [{ uri: "gittensory://enrichment-analyzers", mimeType: "application/json", text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
 server.registerResource(
   "loopover_decision_pack",
   new ResourceTemplate("loopover://decision-packs/{login}", { list: undefined }),

src/api/routes.ts

@@ -212,6 +212,8 @@ import { generateAndSendReviewRecap } from "../services/review-recap";
 import { loadOrComputeIssueQualityResponse } from "../services/issue-quality";
 import { loadMaintainerNoiseReport } from "../services/maintainer-noise";
 import { buildAmsMinerCohortComparison } from "../review/ams-miner-cohort";
+import { buildEnrichmentAnalyzersTaxonomyDocument } from "../review/enrichment-analyzers-taxonomy";
+import { buildFindingTaxonomyDocument } from "../review/finding-taxonomy";
 import { loadOrComputeBurdenForecastResponse } from "../services/burden-forecast";
 import { buildUnavailableQueueTrendReport } from "../services/queue-trends";
 import { loadOrComputeRepoOutcomePatternsResponse } from "../services/repo-outcome-patterns";
@@ -986,6 +988,8 @@ export function createApp() {
     }),
   );
   app.get("/v1/mcp/compatibility", (c) => c.json(buildMcpCompatibilityMetadata(nowIso())));
+  app.get("/v1/mcp/finding-taxonomy", (c) => c.json(buildFindingTaxonomyDocument()));
+  app.get("/v1/mcp/enrichment-analyzers", (c) => c.json(buildEnrichmentAnalyzersTaxonomyDocument()));
   app.get("/openapi.json", (c) => c.json(buildOpenApiSpec()));
   app.all("/mcp", handleMcpRequest);
 
@@ -5988,6 +5992,8 @@ async function isAuthorizedAmsIngest(env: Env, token: string | undefined): Promi
 function requiresApiToken(path: string): boolean {
   if (path === "/health") return false;
   if (path === "/v1/mcp/compatibility") return false;
+  if (path === "/v1/mcp/finding-taxonomy") return false;
+  if (path === "/v1/mcp/enrichment-analyzers") return false;
   if (/^\/v1\/public\/github\/repos\/[^/]+\/[^/]+\/stats$/.test(path)) return false;
   if (/^\/v1\/public\/repos\/[^/]+\/[^/]+\/badge\.(svg|json)$/.test(path)) return false;
   if (/^\/v1\/public\/repos\/[^/]+\/[^/]+\/quality$/.test(path)) return false;

src/auth/rate-limit.ts

@@ -233,7 +233,14 @@ const SESSION_AUTHENTICATED_AUTH_PATHS = new Set(["/v1/auth/github/token", "/v1/
 
 function isPreAuthRateLimitPath(path: string): boolean {
   return (
-    (path === "/health" || path === "/v1/mcp/compatibility" || path === "/openapi.json" || path === "/mcp" || path.startsWith("/v1/auth/") || path === "/v1/github/webhook") &&
+    (path === "/health" ||
+      path === "/v1/mcp/compatibility" ||
+      path === "/v1/mcp/finding-taxonomy" ||
+      path === "/v1/mcp/enrichment-analyzers" ||
+      path === "/openapi.json" ||
+      path === "/mcp" ||
+      path.startsWith("/v1/auth/") ||
+      path === "/v1/github/webhook") &&
     !SESSION_AUTHENTICATED_AUTH_PATHS.has(path)
   );
 }

test/integration/api.test.ts

@@ -133,6 +133,25 @@ describe("api routes", () => {
     });
     expect(JSON.stringify(compatibilityPayload)).not.toMatch(/token|admin|wallet|hotkey|raw trust|scoreability|private repo|local-path/i);
 
+    const findingTaxonomy = await app.request("/v1/mcp/finding-taxonomy", {}, env);
+    expect(findingTaxonomy.status).toBe(200);
+    const findingTaxonomyPayload = await findingTaxonomy.json();
+    expect(findingTaxonomyPayload).toMatchObject({
+      categories: expect.any(Array),
+      severities: expect.any(Array),
+    });
+    expect(findingTaxonomyPayload.categories.length).toBeGreaterThan(0);
+    expect(findingTaxonomyPayload.severities.length).toBeGreaterThan(0);
+
+    const enrichmentAnalyzers = await app.request("/v1/mcp/enrichment-analyzers", {}, env);
+    expect(enrichmentAnalyzers.status).toBe(200);
+    const enrichmentAnalyzersPayload = await enrichmentAnalyzers.json();
+    expect(enrichmentAnalyzersPayload).toMatchObject({
+      defaultProfile: expect.any(String),
+      analyzers: expect.any(Array),
+    });
+    expect(enrichmentAnalyzersPayload.analyzers.length).toBeGreaterThan(0);
+
     const unauthenticatedSpec = await app.request("/openapi.json", {}, env);
     expect(unauthenticatedSpec.status).toBe(200);
     await expect(unauthenticatedSpec.json()).resolves.toMatchObject({ info: { title: "LoopOver API" } });

test/unit/mcp-discovery.test.ts

@@ -7,6 +7,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { closeFixtureServer, startFixtureServer } from "./support/mcp-cli-harness";
+import { ENRICHMENT_ANALYZERS_URI } from "../../src/review/enrichment-analyzers-taxonomy";
+import { FINDING_TAXONOMY_URI } from "../../src/review/finding-taxonomy";
 
 const bin = join(process.cwd(), "packages/loopover-mcp/bin/loopover-mcp.js");
 
@@ -115,6 +118,8 @@ describe("MCP resource discovery", () => {
     const uris = resources.map((r) => r.uri);
     expect(uris).toContain("loopover://changelog");
     expect(uris).toContain("loopover://compatibility");
+    expect(uris).toContain(FINDING_TAXONOMY_URI);
+    expect(uris).toContain(ENRICHMENT_ANALYZERS_URI);
   });
 
   it("resource descriptions do not expose forbidden public terms", async () => {
@@ -151,13 +156,99 @@ describe("MCP resource discovery", () => {
     expect(() => JSON.parse(content.text ?? "")).not.toThrow();
   });
 
+  it("can read the finding-taxonomy resource and get structured JSON", async () => {
+    const result = await client.readResource({ uri: FINDING_TAXONOMY_URI });
+    expect(result.contents).toHaveLength(1);
+    const content = result.contents[0];
+    expect(content?.mimeType).toBe("application/json");
+    if (!content || !("text" in content)) throw new Error("expected text content");
+    expect(() => JSON.parse(content.text ?? "")).not.toThrow();
+  });
+
+  it("can read the enrichment-analyzers resource and get structured JSON", async () => {
+    const result = await client.readResource({ uri: ENRICHMENT_ANALYZERS_URI });
+    expect(result.contents).toHaveLength(1);
+    const content = result.contents[0];
+    expect(content?.mimeType).toBe("application/json");
+    if (!content || !("text" in content)) throw new Error("expected text content");
+    expect(() => JSON.parse(content.text ?? "")).not.toThrow();
+  });
+
   it("decision-pack resource template is discoverable", async () => {
     const { resourceTemplates } = await client.listResourceTemplates();
     const names = resourceTemplates.map((t) => t.name);
     expect(names).toContain("loopover_decision_pack");
   });
 });
 
+describe("MCP taxonomy resource mirrors (#6620)", () => {
+  let fixtureUrl: string;
+  let fixtureConfigDir: string;
+  let fixtureClient: Client;
+  let fixtureTransport: StdioClientTransport;
+
+  async function connectFixtureClient() {
+    fixtureConfigDir = mkdtempSync(join(tmpdir(), "gittensory-taxonomy-mirror-"));
+    fixtureTransport = new StdioClientTransport({
+      command: "node",
+      args: [bin, "--stdio"],
+      env: {
+        ...process.env,
+        LOOPOVER_API_URL: fixtureUrl,
+        LOOPOVER_CONFIG_DIR: fixtureConfigDir,
+        LOOPOVER_API_TIMEOUT_MS: "1000",
+      },
+    });
+    fixtureClient = new Client({ name: "taxonomy-mirror-test", version: "0.0.1" });
+    await fixtureClient.connect(fixtureTransport);
+  }
+
+  afterEach(async () => {
+    await fixtureClient?.close().catch(() => undefined);
+    if (fixtureConfigDir) rmSync(fixtureConfigDir, { recursive: true, force: true });
+    await closeFixtureServer();
+  });
+
+  it("reads finding taxonomy from the API mirror when available", async () => {
+    fixtureUrl = await startFixtureServer({});
+    await connectFixtureClient();
+    const result = await fixtureClient.readResource({ uri: FINDING_TAXONOMY_URI });
+    const content = result.contents[0];
+    if (!content || !("text" in content)) throw new Error("expected text content");
+    const body = JSON.parse(content.text ?? "") as { categories: string[]; severities: string[] };
+    expect(body.categories.length).toBeGreaterThan(0);
+    expect(body.severities.length).toBeGreaterThan(0);
+  });
+
+  it("falls back to unavailable when finding-taxonomy API fetch fails", async () => {
+    fixtureUrl = await startFixtureServer({ findingTaxonomyStatus: 503 });
+    await connectFixtureClient();
+    const result = await fixtureClient.readResource({ uri: FINDING_TAXONOMY_URI });
+    const content = result.contents[0];
+    if (!content || !("text" in content)) throw new Error("expected text content");
+    expect(JSON.parse(content.text ?? "")).toMatchObject({ status: "unavailable" });
+  });
+
+  it("reads enrichment analyzers from the API mirror when available", async () => {
+    fixtureUrl = await startFixtureServer({});
+    await connectFixtureClient();
+    const result = await fixtureClient.readResource({ uri: ENRICHMENT_ANALYZERS_URI });
+    const content = result.contents[0];
+    if (!content || !("text" in content)) throw new Error("expected text content");
+    const body = JSON.parse(content.text ?? "") as { analyzers: Array<{ name: string }> };
+    expect(body.analyzers.length).toBeGreaterThan(0);
+  });
+
+  it("falls back to unavailable when enrichment-analyzers API fetch fails", async () => {
+    fixtureUrl = await startFixtureServer({ enrichmentAnalyzersStatus: 503 });
+    await connectFixtureClient();
+    const result = await fixtureClient.readResource({ uri: ENRICHMENT_ANALYZERS_URI });
+    const content = result.contents[0];
+    if (!content || !("text" in content)) throw new Error("expected text content");
+    expect(JSON.parse(content.text ?? "")).toMatchObject({ status: "unavailable" });
+  });
+});
+
 describe("MCP prompt discovery", () => {
   beforeEach(connect);
   afterEach(disconnect);

test/unit/mcp-enrichment-analyzers-rest.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createApp } from "../../src/api/routes";
+import { buildEnrichmentAnalyzersTaxonomyDocument } from "../../src/review/enrichment-analyzers-taxonomy";
+import { createTestEnv } from "../helpers/d1";
+
+const metadataPath = join(process.cwd(), "review-enrichment/analyzer-metadata.json");
+
+describe("GET /v1/mcp/enrichment-analyzers (#6620)", () => {
+  it("serves the canonical enrichment analyzer taxonomy without authentication", async () => {
+    const app = createApp();
+    const env = createTestEnv();
+
+    const response = await app.request("/v1/mcp/enrichment-analyzers", {}, env);
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual(buildEnrichmentAnalyzersTaxonomyDocument());
+  });
+
+  it("projects analyzer-metadata.json into the REST taxonomy shape", async () => {
+    const raw = JSON.parse(readFileSync(metadataPath, "utf8")) as {
+      defaultProfile: string;
+      analyzers: Array<{ name: string; category: string; cost: string; profiles: string[] }>;
+    };
+    const app = createApp();
+    const env = createTestEnv();
+
+    const body = (await (await app.request("/v1/mcp/enrichment-analyzers", {}, env)).json()) as {
+      defaultProfile: string;
+      analyzers: Array<{ name: string; category: string; costClass: string; profiles: string[] }>;
+    };
+    expect(body.defaultProfile).toBe(raw.defaultProfile);
+    expect(body.analyzers).toHaveLength(raw.analyzers.length);
+    for (const expected of raw.analyzers) {
+      const actual = body.analyzers.find((analyzer) => analyzer.name === expected.name);
+      expect(actual).toMatchObject({
+        category: expected.category,
+        costClass: expected.cost,
+        profiles: expected.profiles,
+      });
+    }
+  });
+});

test/unit/mcp-finding-taxonomy-rest.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { createApp } from "../../src/api/routes";
+import { FINDING_CATEGORIES } from "../../src/review/finding-category-classify";
+import { buildFindingTaxonomyDocument } from "../../src/review/finding-taxonomy";
+import { REVIEW_FINDING_SEVERITY_LADDER } from "../../src/signals/focus-manifest";
+import { createTestEnv } from "../helpers/d1";
+
+describe("GET /v1/mcp/finding-taxonomy (#6620)", () => {
+  it("serves the canonical finding taxonomy without authentication", async () => {
+    const app = createApp();
+    const env = createTestEnv();
+
+    const response = await app.request("/v1/mcp/finding-taxonomy", {}, env);
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual(buildFindingTaxonomyDocument());
+  });
+
+  it("returns categories and severities exactly once", async () => {
+    const app = createApp();
+    const env = createTestEnv();
+
+    const body = (await (await app.request("/v1/mcp/finding-taxonomy", {}, env)).json()) as {
+      categories: string[];
+      severities: string[];
+    };
+    expect(body.categories).toEqual([...FINDING_CATEGORIES]);
+    expect(body.severities).toEqual([...REVIEW_FINDING_SEVERITY_LADDER]);
+    expect(new Set(body.categories).size).toBe(FINDING_CATEGORIES.length);
+    expect(new Set(body.severities).size).toBe(REVIEW_FINDING_SEVERITY_LADDER.length);
+  });
+});

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

@@ -4,6 +4,8 @@ import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { expect } from "vitest";
+import { buildEnrichmentAnalyzersTaxonomyDocument } from "../../../src/review/enrichment-analyzers-taxonomy";
+import { buildFindingTaxonomyDocument } from "../../../src/review/finding-taxonomy";
 
 export const bin = join(process.cwd(), "packages/loopover-mcp/bin/loopover-mcp.js");
 let server: Server | null = null;
@@ -139,6 +141,8 @@ export async function startFixtureServer(
     latestRecommendedMcpVersion?: string;
     minMcpVersion?: string;
     compatibilityStatus?: number;
+    findingTaxonomyStatus?: number;
+    enrichmentAnalyzersStatus?: number;
     npmStatus?: number;
     decisionPackStatus?: number;
     decisionPackErrorBody?: string;
@@ -198,6 +202,24 @@ export async function startFixtureServer(
       );
       return;
     }
+    if (request.url === "/v1/mcp/finding-taxonomy") {
+      if (options.findingTaxonomyStatus && options.findingTaxonomyStatus >= 400) {
+        response.statusCode = options.findingTaxonomyStatus;
+        response.end(JSON.stringify({ error: "finding_taxonomy_unavailable" }));
+        return;
+      }
+      response.end(JSON.stringify(buildFindingTaxonomyDocument()));
+      return;
+    }
+    if (request.url === "/v1/mcp/enrichment-analyzers") {
+      if (options.enrichmentAnalyzersStatus && options.enrichmentAnalyzersStatus >= 400) {
+        response.statusCode = options.enrichmentAnalyzersStatus;
+        response.end(JSON.stringify({ error: "enrichment_analyzers_unavailable" }));
+        return;
+      }
+      response.end(JSON.stringify(buildEnrichmentAnalyzersTaxonomyDocument()));
+      return;
+    }
     if (request.url === "/health") {
       response.end(JSON.stringify({ status: "ok", service: "loopover-api", ...(options.minMcpVersion ? { minMcpVersion: options.minMcpVersion } : {}) }));
       return;