Skip to content

Context7 Platform -- Up-to-date docs for AI agents

fix(cli): fall back to direct SKILL.md fetch when GitHub tree API is unreachable (#2938)

Fahreddin Özcanc82cc8afa055
diff --git a/.changeset/fix-codex-skill-install.md b/.changeset/fix-codex-skill-install.md
new file mode 100644
index 00000000..660ed9b2
--- /dev/null
+++ b/.changeset/fix-codex-skill-install.md
@@ -0,0 +1,5 @@
+---
+"ctx7": patch
+---
+
+Fix `ctx7 setup` skill install failing with "fetch failed" when the GitHub git tree API (`api.github.com`) is blocked or unreachable. Skill download now falls back to fetching the single `SKILL.md` directly from `raw.githubusercontent.com` — the URL the docs API already resolves — so setup succeeds in environments where only the docs/raw hosts are reachable.
diff --git a/packages/cli/src/__tests__/github.test.ts b/packages/cli/src/__tests__/github.test.ts
index 32f3941b..d6417881 100644
--- a/packages/cli/src/__tests__/github.test.ts
+++ b/packages/cli/src/__tests__/github.test.ts
@@ -4,7 +4,14 @@ const execFileSync = vi.hoisted(() => vi.fn());
vi.mock("node:child_process", () => ({ execFileSync }));
-import { listSkillsFromGitHub } from "../utils/github.js";
+import { downloadSkillFromGitHub, listSkillsFromGitHub } from "../utils/github.js";
+
+const SKILL = {
+ name: "context7-mcp",
+ description: "desc",
+ project: "/upstash/context7",
+ url: "https://raw.githubusercontent.com/upstash/context7/refs/heads/master/plugins/codex/context7/skills/context7-mcp/SKILL.md",
+};
beforeEach(() => {
// resetAllMocks, not clearAllMocks: the latter keeps implementations, so a
@@ -86,3 +93,74 @@ describe("GitHub authentication", () => {
expect(headers).not.toHaveProperty("Authorization");
});
});
+
+describe("downloadSkillFromGitHub", () => {
+ test("downloads every file in the skill directory when the tree API works", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((url: string) => {
+ if (url.includes("api.github.com")) {
+ return Promise.resolve({
+ ok: true,
+ json: () =>
+ Promise.resolve({
+ sha: "s",
+ truncated: false,
+ tree: [
+ { type: "tree", path: "plugins/codex/context7/skills/context7-mcp" },
+ {
+ type: "blob",
+ path: "plugins/codex/context7/skills/context7-mcp/SKILL.md",
+ },
+ {
+ type: "blob",
+ path: "plugins/codex/context7/skills/context7-mcp/references/guide.md",
+ },
+ ],
+ }),
+ });
+ }
+ return Promise.resolve({ ok: true, text: () => Promise.resolve(`raw:${url}`) });
+ })
+ );
+
+ const result = await downloadSkillFromGitHub(SKILL);
+
+ expect(result.error).toBeUndefined();
+ expect(result.files.map((f) => f.path).sort()).toEqual(["SKILL.md", "references/guide.md"]);
+ });
+
+ test("falls back to the single SKILL.md when the tree API is unreachable (#2936)", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((url: string) => {
+ if (url.includes("api.github.com")) {
+ return Promise.reject(new TypeError("fetch failed"));
+ }
+ return Promise.resolve({ ok: true, text: () => Promise.resolve("# Context7 skill") });
+ })
+ );
+
+ const result = await downloadSkillFromGitHub(SKILL);
+
+ expect(result.error).toBeUndefined();
+ expect(result.files).toEqual([{ path: "SKILL.md", content: "# Context7 skill" }]);
+ });
+
+ test("surfaces the tree error when both the tree API and the direct fetch fail", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn((url: string) => {
+ if (url.includes("api.github.com")) {
+ return Promise.reject(new TypeError("fetch failed"));
+ }
+ return Promise.resolve({ ok: false, status: 404 });
+ })
+ );
+
+ const result = await downloadSkillFromGitHub(SKILL);
+
+ expect(result.files).toEqual([]);
+ expect(result.error).toBe("fetch failed");
+ });
+});
diff --git a/packages/cli/src/utils/github.ts b/packages/cli/src/utils/github.ts
index 05f36f96..8242f9a7 100644
--- a/packages/cli/src/utils/github.ts
+++ b/packages/cli/src/utils/github.ts
@@ -253,65 +253,102 @@ export async function getSkillFromGitHub(
return { ...result, skill };
}
-export async function downloadSkillFromGitHub(
- skill: Skill & { project: string }
+async function downloadSkillTree(
+ owner: string,
+ repo: string,
+ branch: string,
+ skillPath: string,
+ ghHeaders: Record<string, string>
): Promise<{ files: SkillFile[]; error?: string }> {
- try {
- const parsed = parseGitHubUrl(skill.url);
+ const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders);
+ if ("error" in treeData) {
+ const hint =
+ !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error)
+ ? " — run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits"
+ : "";
+ return { files: [], error: `GitHub API error: ${treeData.error}${hint}` };
+ }
- if (!parsed) {
- return { files: [], error: `Invalid GitHub URL: ${skill.url}` };
- }
+ const skillFiles = treeData.tree.filter(
+ (item) => item.type === "blob" && item.path.startsWith(skillPath + "/")
+ );
- const { owner, repo, branch, path: skillPath } = parsed;
+ if (skillFiles.length === 0) {
+ return { files: [], error: `No files found in ${skillPath}` };
+ }
- const ghHeaders = getGitHubHeaders();
+ const files: SkillFile[] = [];
+ for (const item of skillFiles) {
+ const rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branch}/${item.path}`;
+ const fileResponse = await fetch(rawUrl, { headers: ghHeaders });
- const treeData = await fetchRepoTree(owner, repo, branch, ghHeaders);
- if ("error" in treeData) {
- const hint =
- !ghHeaders["Authorization"] && /403|429|rate/.test(treeData.error)
- ? " — run `gh auth login` or set the GITHUB_TOKEN env var to increase rate limits"
- : "";
- return { files: [], error: `GitHub API error: ${treeData.error}${hint}` };
+ if (!fileResponse.ok) {
+ console.warn(`Failed to fetch ${item.path}: ${fileResponse.status}`);
+ continue;
}
- const skillFiles = treeData.tree.filter(
- (item) => item.type === "blob" && item.path.startsWith(skillPath + "/")
- );
+ const content = await fileResponse.text();
+ const relativePath = item.path.slice(skillPath.length + 1);
- if (skillFiles.length === 0) {
- return { files: [], error: `No files found in ${skillPath}` };
+ // Reject paths that attempt directory traversal
+ if (relativePath.includes("..")) {
+ console.warn(`Skipping file with unsafe path: ${item.path}`);
+ continue;
}
- const files: SkillFile[] = [];
- for (const item of skillFiles) {
- const rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branch}/${item.path}`;
- const fileResponse = await fetch(rawUrl, { headers: ghHeaders });
+ files.push({
+ path: relativePath,
+ content,
+ });
+ }
- if (!fileResponse.ok) {
- console.warn(`Failed to fetch ${item.path}: ${fileResponse.status}`);
- continue;
- }
+ return { files };
+}
- const content = await fileResponse.text();
- const relativePath = item.path.slice(skillPath.length + 1);
+async function downloadSingleSkillFile(
+ skillUrl: string,
+ ghHeaders: Record<string, string>
+): Promise<SkillFile[] | null> {
+ let fileName: string;
+ try {
+ const url = new URL(skillUrl);
+ const last = url.pathname.split("/").filter(Boolean).pop();
+ if (url.hostname !== "raw.githubusercontent.com" || !last || !last.includes(".")) {
+ return null;
+ }
+ fileName = last;
+ } catch {
+ return null;
+ }
- // Reject paths that attempt directory traversal
- if (relativePath.includes("..")) {
- console.warn(`Skipping file with unsafe path: ${item.path}`);
- continue;
- }
+ const response = await fetch(skillUrl, { headers: ghHeaders });
+ if (!response.ok) return null;
+ const content = await response.text();
+ return [{ path: fileName, content }];
+}
- files.push({
- path: relativePath,
- content,
- });
- }
+export async function downloadSkillFromGitHub(
+ skill: Skill & { project: string }
+): Promise<{ files: SkillFile[]; error?: string }> {
+ const parsed = parseGitHubUrl(skill.url);
+ if (!parsed) {
+ return { files: [], error: `Invalid GitHub URL: ${skill.url}` };
+ }
+
+ const { owner, repo, branch, path: skillPath } = parsed;
+ const ghHeaders = getGitHubHeaders();
- return { files };
+ let treeError: string | undefined;
+ try {
+ const result = await downloadSkillTree(owner, repo, branch, skillPath, ghHeaders);
+ if (result.files.length > 0) return { files: result.files };
+ treeError = result.error;
} catch (err) {
- const message = err instanceof Error ? err.message : String(err);
- return { files: [], error: message };
+ treeError = err instanceof Error ? err.message : String(err);
}
+
+ const single = await downloadSingleSkillFile(skill.url, ghHeaders).catch(() => null);
+ if (single) return { files: single };
+
+ return { files: [], error: treeError ?? `No files found in ${skillPath}` };
}