fix(mcp): continue past invalid library candidates

Reject empty, archived, disabled, and branchless GitHub search results before they reach the index builder. Strip trailing documentation qualifiers for discovery and verify an official owner/docs repository when available, allowing requests such as GitHub Actions documentation to resolve to github/docs.

Return a ranked, deduplicated candidate set from discovery and let the resolver try a bounded number of candidates instead of failing permanently on the first clone or indexing error. Resolve registry and GitHub candidates concurrently to avoid adding lookup latency.

Add a regression test covering the zero-size exact-name repository that caused an unborn-branch checkout. Verified the original MCP call now returns /github/docs from the commit-pinned local index; lint, build, typecheck, and all 21 tests pass.

Author: DeepWiki Dev

packages/mcp/src/local/discovery.ts

@@ -2,6 +2,14 @@ import { normalizeSearchName, parseGitHubRepository } from "./library-id.js";
 import type { DiscoveredLibrary, LibraryRef, LocalContext7Config } from "./types.js";
 
 type JsonObject = Record<string, unknown>;
+const DOCUMENTATION_QUALIFIERS = new Set([
+  "docs",
+  "documentation",
+  "manual",
+  "reference",
+  "references",
+]);
+const MAX_GITHUB_SEARCH_CANDIDATES = 3;
 
 function asObject(value: unknown): JsonObject | undefined {
   return value && typeof value === "object" ? (value as JsonObject) : undefined;
@@ -17,6 +25,48 @@ function repositoryFromValue(value: unknown): LibraryRef | undefined {
   return object ? parseGitHubRepository(asString(object.url) ?? "") : undefined;
 }
 
+function discoveryNames(name: string): string[] {
+  const original = name.trim();
+  const words = original.split(/\s+/);
+  while (words.length > 1 && DOCUMENTATION_QUALIFIERS.has((words.at(-1) ?? "").toLowerCase())) {
+    words.pop();
+  }
+  const withoutQualifier = words.join(" ");
+  return withoutQualifier && withoutQualifier !== original
+    ? [original, withoutQualifier]
+    : [original];
+}
+
+function usableGitHubRepository(value: JsonObject | undefined): boolean {
+  if (!value || value.archived === true || value.disabled === true) return false;
+  return typeof value.size !== "number" || value.size > 0;
+}
+
+function discoveredFromGitHub(value: JsonObject | undefined): DiscoveredLibrary | undefined {
+  if (!usableGitHubRepository(value)) return undefined;
+  const fullName = asString(value?.full_name);
+  const ref = fullName ? parseGitHubRepository(fullName) : undefined;
+  const defaultBranch = asString(value?.default_branch);
+  if (!ref || !defaultBranch) return undefined;
+  return {
+    ref,
+    title: asString(value?.name),
+    description: asString(value?.description),
+    stars: typeof value?.stargazers_count === "number" ? value.stargazers_count : undefined,
+    defaultBranch,
+  };
+}
+
+function uniqueCandidates(candidates: DiscoveredLibrary[]): DiscoveredLibrary[] {
+  const seen = new Set<string>();
+  return candidates.filter((candidate) => {
+    const key = candidate.ref.id.toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
 export class LibraryDiscovery {
   constructor(private readonly config: LocalContext7Config) {}
 
@@ -53,6 +103,19 @@ export class LibraryDiscovery {
     }
   }
 
+  private async verifiedGitHubRepository(ref: LibraryRef): Promise<DiscoveredLibrary | undefined> {
+    const headers: Record<string, string> = {};
+    if (this.config.githubToken) headers.Authorization = `Bearer ${this.config.githubToken}`;
+    try {
+      const data = asObject(
+        await this.fetchJson(`https://api.github.com/repos/${ref.owner}/${ref.repo}`, headers)
+      );
+      return discoveredFromGitHub(data);
+    } catch {
+      return undefined;
+    }
+  }
+
   private async fromNpm(name: string): Promise<DiscoveredLibrary | undefined> {
     try {
       const data = asObject(
@@ -110,7 +173,18 @@ export class LibraryDiscovery {
     }
   }
 
-  private async fromGitHubSearch(name: string): Promise<DiscoveredLibrary | undefined> {
+  private async fromOfficialDocumentationRepository(
+    originalName: string,
+    searchName: string
+  ): Promise<DiscoveredLibrary | undefined> {
+    if (originalName.trim() === searchName.trim()) return undefined;
+    const owner = searchName.trim().split(/\s+/, 1)[0];
+    if (!owner || !/^[A-Za-z0-9_.-]+$/.test(owner)) return undefined;
+    const ref = parseGitHubRepository(`/${owner}/docs`);
+    return ref ? this.verifiedGitHubRepository(ref) : undefined;
+  }
+
+  private async fromGitHubSearch(name: string): Promise<DiscoveredLibrary[]> {
     const headers: Record<string, string> = {};
     if (this.config.githubToken) headers.Authorization = `Bearer ${this.config.githubToken}`;
     try {
@@ -122,32 +196,43 @@ export class LibraryDiscovery {
       );
       const items = Array.isArray(root?.items) ? root.items.map(asObject).filter(Boolean) : [];
       const normalized = normalizeSearchName(name);
-      const exact = items.find(
-        (item) => normalizeSearchName(asString(item?.name) ?? "") === normalized
-      );
-      const fullName = asString(exact?.full_name);
-      const ref = fullName ? parseGitHubRepository(fullName) : undefined;
-      if (!ref) return undefined;
-      return {
-        ref,
-        title: asString(exact?.name),
-        description: asString(exact?.description),
-        stars: typeof exact?.stargazers_count === "number" ? exact.stargazers_count : undefined,
-        defaultBranch: asString(exact?.default_branch),
-      };
+      return items
+        .filter((item) => normalizeSearchName(asString(item?.name) ?? "") === normalized)
+        .map(discoveredFromGitHub)
+        .filter((candidate): candidate is DiscoveredLibrary => Boolean(candidate))
+        .sort((left, right) => (right.stars ?? 0) - (left.stars ?? 0))
+        .slice(0, MAX_GITHUB_SEARCH_CANDIDATES);
     } catch {
-      return undefined;
+      return [];
     }
   }
 
-  async discover(name: string): Promise<DiscoveredLibrary | undefined> {
+  async discoverCandidates(name: string): Promise<DiscoveredLibrary[]> {
     const direct = parseGitHubRepository(name);
-    if (direct) return this.decorate(direct);
+    if (direct) return [await this.decorate(direct)];
 
-    for (const resolver of [this.fromNpm, this.fromPyPi, this.fromCrates, this.fromGitHubSearch]) {
-      const result = await resolver.call(this, name);
-      if (result) return result;
-    }
-    return undefined;
+    const names = discoveryNames(name);
+    const registryCandidates = await Promise.all(
+      names.flatMap((candidateName) =>
+        [this.fromNpm, this.fromPyPi, this.fromCrates].map((resolver) =>
+          resolver.call(this, candidateName)
+        )
+      )
+    );
+    const [officialDocumentation, ...githubCandidates] = await Promise.all([
+      this.fromOfficialDocumentationRepository(names[0]!, names.at(-1)!),
+      ...names.map((candidateName) => this.fromGitHubSearch(candidateName)),
+    ]);
+    return uniqueCandidates([
+      ...registryCandidates.filter((candidate): candidate is DiscoveredLibrary =>
+        Boolean(candidate)
+      ),
+      ...(officialDocumentation ? [officialDocumentation] : []),
+      ...githubCandidates.flat(),
+    ]);
+  }
+
+  async discover(name: string): Promise<DiscoveredLibrary | undefined> {
+    return (await this.discoverCandidates(name))[0];
   }
 }

packages/mcp/src/local/service.ts

@@ -29,6 +29,8 @@ import type {
   LocalContext7Config,
 } from "./types.js";
 
+const MAX_INDEX_CANDIDATES = 5;
+
 function resultFromManifest(manifest: LibraryManifest): SearchResult {
   const safe = (value: string, limit: number) =>
     value
@@ -166,27 +168,34 @@ export class LocalContext7Service {
         normalizeSearchName(manifest.id) === normalizeSearchName(libraryName)
     );
 
-    try {
-      const discovered = exact
-        ? {
-            ref: parseLibraryId(exact.id),
-            title: exact.title,
-            description: exact.description,
-            stars: exact.stars,
-            defaultBranch: exact.branch,
-          }
-        : await this.discovery.discover(libraryName);
-      if (discovered) {
-        const ensured = await this.ensure(discovered);
+    const candidates = exact
+      ? {
+          ref: parseLibraryId(exact.id),
+          title: exact.title,
+          description: exact.description,
+          stars: exact.stars,
+          defaultBranch: exact.branch,
+        }
+      : undefined;
+    const discovered = candidates
+      ? [candidates]
+      : await this.discovery.discoverCandidates(libraryName);
+    const failures: string[] = [];
+    for (const candidate of discovered.slice(0, MAX_INDEX_CANDIDATES)) {
+      try {
+        const ensured = await this.ensure(candidate);
         const others = local.filter((manifest) => manifest.id !== ensured.manifest.id);
         return {
           results: [resultFromManifest(ensured.manifest), ...others.map(resultFromManifest)],
         };
+      } catch (error) {
+        failures.push(`${candidate.ref.id}: ${safeError(error)}`);
       }
-    } catch (error) {
+    }
+    if (failures.length > 0) {
       return {
         results: local.map(resultFromManifest),
-        error: `Local indexing failed for ${libraryName}: ${safeError(error)}`,
+        error: `Local indexing failed for ${libraryName} after trying ${failures.join("; ")}`,
       };
     }
 

packages/mcp/test/local-discovery.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { LibraryDiscovery } from "../src/local/discovery.js";
+import type { LocalContext7Config } from "../src/local/types.js";
+
+const config: LocalContext7Config = {
+  storageDir: "unused",
+  refreshIntervalMs: 60_000,
+  gitTimeoutMs: 30_000,
+  fetchTimeoutMs: 5_000,
+  maxFiles: 100,
+  maxFileBytes: 100_000,
+  maxIndexBytes: 1_000_000,
+  maxResultChars: 10_000,
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("local library discovery", () => {
+  test("prefers an official docs repository and rejects empty exact-name matches", async () => {
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = String(input);
+      if (url === "https://api.github.com/repos/GitHub/docs") {
+        return Response.json({
+          full_name: "github/docs",
+          name: "docs",
+          description: "The open-source repository for docs.github.com",
+          default_branch: "main",
+          stargazers_count: 17_000,
+          size: 500_000,
+        });
+      }
+      if (url.startsWith("https://api.github.com/search/repositories")) {
+        return Response.json({
+          items: [
+            {
+              full_name: "example/github-actions-documentation",
+              name: "github-actions-documentation",
+              default_branch: "main",
+              stargazers_count: 0,
+              size: 0,
+            },
+            {
+              full_name: "example-valid/github-actions-documentation",
+              name: "github-actions-documentation",
+              default_branch: "main",
+              stargazers_count: 1,
+              size: 10,
+            },
+          ],
+        });
+      }
+      return new Response("not found", { status: 404 });
+    });
+
+    const candidates = await new LibraryDiscovery(config).discoverCandidates(
+      "GitHub Actions documentation"
+    );
+
+    expect(candidates[0]?.ref.id.toLowerCase()).toBe("/github/docs");
+    expect(candidates.map((candidate) => candidate.ref.id)).not.toContain(
+      "/example/github-actions-documentation"
+    );
+    expect(candidates.map((candidate) => candidate.ref.id)).toContain(
+      "/example-valid/github-actions-documentation"
+    );
+  });
+});