Skip to content

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

36.5 KB
Raw Blame
import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
import { mkdir, readFile, writeFile, rm } from "fs/promises";
import { join } from "path";
import { tmpdir } from "os";

const MOCK_MCP_RULE = "Use Context7 MCP to fetch docs.\n";
const MOCK_CLI_RULE = "Use the `ctx7` CLI to fetch docs.\n";

vi.stubGlobal(
  "fetch",
  vi.fn((url: string) => {
    if (url.includes("context7-mcp.md")) {
      return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_MCP_RULE) });
    }
    if (url.includes("context7-cli.md")) {
      return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_CLI_RULE) });
    }
    return Promise.resolve({ ok: false });
  })
);

import { getRuleContent } from "../setup/templates.js";
import {
  getMcpUrl,
  getOnPremMcpAuthStatus,
  normalizeDeploymentBaseUrl,
  resolveSetupDeployment,
} from "../setup/deployment.js";
import {
  mergeServerEntry,
  removeServerEntry,
  readJsonConfig,
  writeJsonConfig,
  readTomlServerExists,
  buildTomlServerBlock,
  appendTomlServer,
  removeTomlServer,
  resolveMcpPath,
  isStdioContext7Entry,
  patchStdioApiKey,
} from "../setup/mcp-writer.js";
import {
  getAgent,
  detectAgents,
  ALL_AGENT_NAMES,
  resolveVscodeUserDir,
  resolveDevinConfigDir,
  type AuthOptions,
  type Transport,
} from "../setup/agents.js";

function buildEntry(
  agent: ReturnType<typeof getAgent>,
  auth: AuthOptions,
  transport: Transport,
  mcpUrl = getMcpUrl(resolveSetupDeployment(), auth)
): Record<string, unknown> {
  return agent.mcp.buildEntry(auth, transport, mcpUrl);
}

describe("getRuleContent", () => {
  test("returns correct content per mode", async () => {
    expect(await getRuleContent("mcp", "claude")).toBe(MOCK_MCP_RULE);
    expect(await getRuleContent("cli", "claude")).toBe(MOCK_CLI_RULE);
  });

  test("returns fallback content when all fetch URLs fail", async () => {
    vi.stubGlobal(
      "fetch",
      vi.fn(() => Promise.resolve({ ok: false }))
    );
    const content = await getRuleContent("mcp", "claude");
    expect(content).toContain("Context7 MCP");
    expect(content.length).toBeGreaterThan(100);

    vi.stubGlobal(
      "fetch",
      vi.fn((url: string) => {
        if (url.includes("context7-mcp.md"))
          return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_MCP_RULE) });
        if (url.includes("context7-cli.md"))
          return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_CLI_RULE) });
        return Promise.resolve({ ok: false });
      })
    );
  });
});

describe("custom Context7 deployments", () => {
  test("normalizes deployment roots and rejects endpoint URLs", () => {
    expect(normalizeDeploymentBaseUrl("https://context7.internal.example///")).toBe(
      "https://context7.internal.example"
    );
    expect(normalizeDeploymentBaseUrl("http://localhost:3000/context7/")).toBe(
      "http://localhost:3000/context7"
    );
    expect(() => normalizeDeploymentBaseUrl("https://example.com/mcp")).toThrow(
      "without /mcp or /api"
    );
    expect(() => normalizeDeploymentBaseUrl("file:///tmp/context7")).toThrow("http:// or https://");
  });

  test("keeps hosted MCP routing and builds custom MCP URLs", () => {
    const hosted = resolveSetupDeployment("https://context7.com/");
    const custom = resolveSetupDeployment("https://context7.internal.example/");
    expect(hosted.kind).toBe("hosted");
    expect(custom).toEqual({
      kind: "custom",
      baseUrl: "https://context7.internal.example",
    });
    expect(getMcpUrl(hosted, { mode: "oauth" })).toBe("https://mcp.context7.com/mcp/oauth");
    expect(getMcpUrl(custom, { mode: "none" })).toBe("https://context7.internal.example/mcp");
  });

  test("explains that authentication discovery redirects require the final URL", async () => {
    vi.mocked(fetch).mockResolvedValueOnce({
      ok: false,
      status: 301,
    } as Response);

    const deployment = resolveSetupDeployment("http://context7.internal.example");
    if (deployment.kind !== "custom") throw new Error("expected custom deployment");

    await expect(getOnPremMcpAuthStatus(deployment)).rejects.toThrow(
      "Pass the final deployment URL"
    );
  });

  test("rejects invalid authentication discovery responses", async () => {
    vi.mocked(fetch).mockResolvedValueOnce({
      ok: true,
      json: () => Promise.resolve({ enabled: "yes" }),
    } as Response);

    const deployment = resolveSetupDeployment("https://context7.internal.example");
    if (deployment.kind !== "custom") throw new Error("expected custom deployment");

    await expect(getOnPremMcpAuthStatus(deployment)).rejects.toThrow("Invalid response");
  });
});

describe("mergeServerEntry", () => {
  test("adds server to empty config", () => {
    const { config, alreadyExists } = mergeServerEntry({}, "mcpServers", "context7", {
      url: "https://mcp.context7.com/mcp",
    });
    expect(alreadyExists).toBe(false);
    expect((config.mcpServers as Record<string, unknown>).context7).toEqual({
      url: "https://mcp.context7.com/mcp",
    });
  });

  test("preserves existing servers when adding new one", () => {
    const { config } = mergeServerEntry(
      { mcpServers: { other: { url: "https://other.com" } } },
      "mcpServers",
      "context7",
      { url: "https://mcp.context7.com/mcp" }
    );
    const servers = config.mcpServers as Record<string, unknown>;
    expect(servers.context7).toBeTruthy();
    expect(servers.other).toEqual({ url: "https://other.com" });
  });

  test("overwrites existing server entry with new url", () => {
    const existing = {
      mcpServers: {
        context7: { url: "https://old.com", headers: { key: "old-key" } },
        other: { url: "https://other.com" },
      },
    };
    const { config, alreadyExists } = mergeServerEntry(existing, "mcpServers", "context7", {
      url: "https://mcp.context7.com/mcp",
      headers: { key: "new-key" },
    });
    expect(alreadyExists).toBe(true);
    const servers = config.mcpServers as Record<string, unknown>;
    expect(servers.context7).toEqual({
      url: "https://mcp.context7.com/mcp",
      headers: { key: "new-key" },
    });
    expect(servers.other).toEqual({ url: "https://other.com" });
  });

  test("overwrites existing server entry with different auth mode", () => {
    const existing = {
      mcpServers: {
        context7: { url: "https://mcp.context7.com/mcp", headers: { "x-api-key": "old" } },
      },
    };
    const { config, alreadyExists } = mergeServerEntry(existing, "mcpServers", "context7", {
      url: "https://mcp.context7.com/mcp",
    });
    expect(alreadyExists).toBe(true);
    expect((config.mcpServers as Record<string, unknown>).context7).toEqual({
      url: "https://mcp.context7.com/mcp",
    });
  });
});

describe("removeServerEntry", () => {
  test("removes empty config section when context7 is the only server", () => {
    const { config, removed } = removeServerEntry(
      {
        mcpServers: {
          context7: { url: "https://mcp.context7.com/mcp" },
        },
        theme: "dark",
      },
      "mcpServers",
      "context7"
    );

    expect(removed).toBe(true);
    expect(config).toEqual({ theme: "dark" });
  });

  test("returns original config when server is not present", () => {
    const existing = { mcpServers: { other: { url: "https://other.com" } } };
    const { config, removed } = removeServerEntry(existing, "mcpServers", "context7");

    expect(removed).toBe(false);
    expect(config).toEqual(existing);
  });
});

describe("readJsonConfig / writeJsonConfig", () => {
  let tempDir: string;

  beforeEach(async () => {
    tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);
    await mkdir(tempDir, { recursive: true });
  });

  afterEach(async () => {
    await rm(tempDir, { recursive: true, force: true });
  });

  test("returns empty object for missing or empty file", async () => {
    expect(await readJsonConfig(join(tempDir, "nope.json"))).toEqual({});

    await writeFile(join(tempDir, "empty.json"), "", "utf-8");
    expect(await readJsonConfig(join(tempDir, "empty.json"))).toEqual({});
  });

  test("roundtrip write then read preserves data", async () => {
    const path = join(tempDir, "sub", "dir", "config.json");
    const data = { mcpServers: { context7: { url: "https://mcp.context7.com/mcp" } } };

    await writeJsonConfig(path, data);
    const result = await readJsonConfig(path);
    expect(result).toEqual(data);

    const raw = await readFile(path, "utf-8");
    expect(raw.endsWith("\n")).toBe(true);
  });
});

describe("JSONC support", () => {
  let tempDir: string;

  beforeEach(async () => {
    tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);
    await mkdir(tempDir, { recursive: true });
  });

  afterEach(async () => {
    await rm(tempDir, { recursive: true, force: true });
  });

  test("readJsonConfig strips comments without corrupting URLs", async () => {
    const path = join(tempDir, "config.jsonc");
    await writeFile(
      path,
      `{
  // This is a comment
  "mcp": {},
  "$schema": "https://opencode.ai/config.json"
}`,
      "utf-8"
    );
    const result = await readJsonConfig(path);
    expect(result.$schema).toBe("https://opencode.ai/config.json");
    expect(result.mcp).toEqual({});
  });

  test("readJsonConfig accepts trailing commas in OpenCode config", async () => {
    const path = join(tempDir, "opencode.jsonc");
    await writeFile(
      path,
      '{\n  "$schema": "https://opencode.ai/config.json",\n  "lsp": true,\n}',
      "utf-8"
    );
    const result = await readJsonConfig(path);
    expect(result.lsp).toBe(true);
  });

  test("readJsonConfig rejects malformed JSONC", async () => {
    const path = join(tempDir, "invalid.jsonc");
    await writeFile(path, '{ "mcp": {', "utf-8");
    await expect(readJsonConfig(path)).rejects.toThrow(SyntaxError);
  });

  test("readJsonConfig propagates non-missing file errors", async () => {
    await expect(readJsonConfig(tempDir)).rejects.toThrow();
  });

  test("readJsonConfig handles block comments", async () => {
    const path = join(tempDir, "config.jsonc");
    await writeFile(path, '{ /* block */ "key": "value" }', "utf-8");
    const result = await readJsonConfig(path);
    expect(result.key).toBe("value");
  });

  test("resolveMcpPath returns first existing candidate", async () => {
    const jsoncPath = join(tempDir, "opencode.jsonc");
    await writeFile(jsoncPath, "{}", "utf-8");
    const resolved = await resolveMcpPath([join(tempDir, "opencode.json"), jsoncPath]);
    expect(resolved).toBe(jsoncPath);
  });

  test("resolveMcpPath falls back to first candidate when none exist", async () => {
    const jsonPath = join(tempDir, "opencode.json");
    const resolved = await resolveMcpPath([jsonPath]);
    expect(resolved).toBe(jsonPath);
  });
});

describe("TOML config", () => {
  let tempDir: string;

  beforeEach(async () => {
    tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);
    await mkdir(tempDir, { recursive: true });
  });

  afterEach(async () => {
    await rm(tempDir, { recursive: true, force: true });
  });

  test("buildTomlServerBlock includes http_headers", () => {
    const block = buildTomlServerBlock("context7", {
      url: "https://mcp.context7.com/mcp",
      headers: { CONTEXT7_API_KEY: "sk-test" },
    });
    expect(block).toContain("[mcp_servers.context7]");
    expect(block).toContain("[mcp_servers.context7.http_headers]");
    expect(block).toContain('CONTEXT7_API_KEY = "sk-test"');
    expect(block).not.toContain("headers =");
  });

  test("readTomlServerExists detects existing server", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(path, '[mcp_servers.context7]\nurl = "https://test.com"\n', "utf-8");
    expect(await readTomlServerExists(path, "context7")).toBe(true);
    expect(await readTomlServerExists(path, "other")).toBe(false);
  });

  test("readTomlServerExists returns false for missing file", async () => {
    expect(await readTomlServerExists(join(tempDir, "nope.toml"), "context7")).toBe(false);
  });

  test("appendTomlServer appends to empty file", async () => {
    const path = join(tempDir, "config.toml");
    const { alreadyExists } = await appendTomlServer(path, "context7", {
      url: "https://mcp.context7.com/mcp",
    });
    expect(alreadyExists).toBe(false);
    const content = await readFile(path, "utf-8");
    expect(content).toContain("[mcp_servers.context7]");
    expect(content).toContain('url = "https://mcp.context7.com/mcp"');
  });

  test("appendTomlServer preserves existing config", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(path, 'model = "gpt-5"\n\n[mcp_servers.other]\nurl = "https://other.com"\n');
    await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" });
    const content = await readFile(path, "utf-8");
    expect(content).toContain('model = "gpt-5"');
    expect(content).toContain("[mcp_servers.other]");
    expect(content).toContain("[mcp_servers.context7]");
  });

  test("appendTomlServer overwrites existing server with new url", async () => {
    const path = join(tempDir, "config.toml");
    await appendTomlServer(path, "context7", { url: "https://old.com" });
    const { alreadyExists } = await appendTomlServer(path, "context7", {
      url: "https://mcp.context7.com/mcp",
    });
    expect(alreadyExists).toBe(true);
    const content = await readFile(path, "utf-8");
    expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1);
    expect(content).toContain('url = "https://mcp.context7.com/mcp"');
    expect(content).not.toContain("https://old.com");
  });

  test("appendTomlServer overwrites server without affecting other servers", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(
      path,
      '[mcp_servers.context7]\nurl = "https://old.com"\n\n[mcp_servers.other]\nurl = "https://other.com"\n'
    );
    await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" });
    const content = await readFile(path, "utf-8");
    expect(content).toContain('url = "https://mcp.context7.com/mcp"');
    expect(content).not.toContain("https://old.com");
    expect(content).toContain("[mcp_servers.other]");
    expect(content).toContain('url = "https://other.com"');
  });

  test("appendTomlServer overwrites server that appears before non-mcp sections", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(
      path,
      'model = "gpt-5"\n\n[mcp_servers.context7]\nurl = "https://old.com"\n\n[some_other_section]\nkey = "value"\n'
    );
    await appendTomlServer(path, "context7", {
      url: "https://mcp.context7.com/mcp",
      headers: { "x-api-key": "sk-new" },
    });
    const content = await readFile(path, "utf-8");
    expect(content).toContain('model = "gpt-5"');
    expect(content).toContain('url = "https://mcp.context7.com/mcp"');
    expect(content).toContain("[mcp_servers.context7.http_headers]");
    expect(content).toContain('x-api-key = "sk-new"');
    expect(content).not.toContain("https://old.com");
    expect(content).toContain("[some_other_section]");
    expect(content).toContain('key = "value"');
  });

  test("appendTomlServer overwrites server at end of file", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(
      path,
      '[mcp_servers.other]\nurl = "https://other.com"\n\n[mcp_servers.context7]\nurl = "https://old.com"\n'
    );
    await appendTomlServer(path, "context7", { url: "https://new.com" });
    const content = await readFile(path, "utf-8");
    expect(content).toContain("[mcp_servers.other]");
    expect(content).toContain('url = "https://new.com"');
    expect(content).not.toContain("https://old.com");
    expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1);
  });

  test("appendTomlServer does not accumulate blank lines on repeated overwrites", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(
      path,
      'model = "o3"\n\n[mcp_servers.context7]\nurl = "https://old.com"\n\n[mcp_servers.other]\nurl = "https://other.com"\n'
    );

    for (let i = 1; i <= 3; i++) {
      await appendTomlServer(path, "context7", { url: `https://v${i}.com` });
    }

    const content = await readFile(path, "utf-8");
    expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1);
    expect(content).toContain('url = "https://v3.com"');
    expect(content).toContain("[mcp_servers.other]");
    expect(content).not.toContain("\n\n\n");
  });

  test("removeTomlServer removes only the target server", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(
      path,
      'model = "gpt-5"\n\n[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.other]\nurl = "https://other.com"\n',
      "utf-8"
    );

    const { removed } = await removeTomlServer(path, "context7");
    expect(removed).toBe(true);

    const content = await readFile(path, "utf-8");
    expect(content).toContain('model = "gpt-5"');
    expect(content).toContain("[mcp_servers.other]");
    expect(content).toContain('url = "https://other.com"');
    expect(content).not.toContain("[mcp_servers.context7]");
  });

  test("removeTomlServer preserves other MCP servers and their subsections", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(
      path,
      '[mcp_servers.context7]\nurl = "https://mcp.context7.com/mcp"\n\n[mcp_servers.context7.http_headers]\nCONTEXT7_API_KEY = "sk-test"\n\n[mcp_servers.other]\nurl = "https://other.com"\n\n[mcp_servers.other.http_headers]\nX_API_KEY = "keep-me"\n\n[settings]\nmodel = "gpt-5"\n',
      "utf-8"
    );

    const { removed } = await removeTomlServer(path, "context7");
    const content = await readFile(path, "utf-8");

    expect(removed).toBe(true);
    expect(content).toContain("[mcp_servers.other]");
    expect(content).toContain('url = "https://other.com"');
    expect(content).toContain("[mcp_servers.other.http_headers]");
    expect(content).toContain('X_API_KEY = "keep-me"');
    expect(content).toContain("[settings]");
    expect(content).not.toContain("[mcp_servers.context7]");
    expect(content).not.toContain("[mcp_servers.context7.http_headers]");
  });

  test("removeTomlServer returns false when server is missing", async () => {
    const path = join(tempDir, "config.toml");
    await writeFile(path, '[mcp_servers.other]\nurl = "https://other.com"\n', "utf-8");

    const { removed } = await removeTomlServer(path, "context7");
    expect(removed).toBe(false);
  });
});

describe("agent config integration", () => {
  let tempDir: string;

  beforeEach(async () => {
    tempDir = join(tmpdir(), `ctx7-agent-cfg-${Date.now()}`);
    await mkdir(tempDir, { recursive: true });
  });

  afterEach(async () => {
    await rm(tempDir, { recursive: true, force: true });
  });

  const apiKeyAuth: AuthOptions = { mode: "api-key", apiKey: "sk-test-123" };
  const oauthAuth: AuthOptions = { mode: "oauth" };
  const noAuth: AuthOptions = { mode: "none" };

  test("all HTTP agents target an on-premise deployment and use bearer authentication", () => {
    for (const agentName of ALL_AGENT_NAMES) {
      const agent = getAgent(agentName);
      const authenticated = buildEntry(
        agent,
        apiKeyAuth,
        "http",
        "https://context7.internal.example/mcp"
      );
      expect(JSON.stringify(authenticated)).toContain("https://context7.internal.example/mcp");
      expect(authenticated).toMatchObject({
        headers: { Authorization: "Bearer sk-test-123" },
      });

      const anonymous = buildEntry(agent, noAuth, "http", "https://context7.internal.example/mcp");
      expect(JSON.stringify(anonymous)).toContain("https://context7.internal.example/mcp");
      expect(anonymous).not.toHaveProperty("headers");
    }
  });

  describe("claude", () => {
    const agent = getAgent("claude");

    test("buildEntry with api-key produces correct shape", () => {
      const entry = buildEntry(agent, apiKeyAuth, "http");
      expect(entry).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });

    test("buildEntry with oauth produces correct shape", () => {
      const entry = buildEntry(agent, oauthAuth, "http");
      expect(entry).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp/oauth",
      });
    });

    test("uses CLAUDE_CONFIG_DIR for global Claude config, rules, skills, and detection", () => {
      const previous = process.env.CLAUDE_CONFIG_DIR;
      const customDir = join(tempDir, "xdg", "claude");
      process.env.CLAUDE_CONFIG_DIR = customDir;
      try {
        expect(agent.mcp.globalPaths).toEqual([join(customDir, ".claude.json")]);
        expect(agent.rule.kind).toBe("file");
        if (agent.rule.kind === "file") {
          expect(agent.rule.dir("global")).toBe(join(customDir, "rules"));
        }
        expect(agent.skill.dir("global")).toBe(join(customDir, "skills"));
        expect(agent.detect.globalPaths).toEqual([customDir]);
      } finally {
        if (previous === undefined) {
          delete process.env.CLAUDE_CONFIG_DIR;
        } else {
          process.env.CLAUDE_CONFIG_DIR = previous;
        }
      }
    });

    test("merges into JSON config with configKey mcpServers", async () => {
      const path = join(tempDir, ".claude.json");
      const existing = await readJsonConfig(path);
      const { config } = mergeServerEntry(
        existing,
        agent.mcp.configKey,
        "context7",
        buildEntry(agent, apiKeyAuth, "http")
      );
      await writeJsonConfig(path, config);

      const result = await readJsonConfig(path);
      const servers = result.mcpServers as Record<string, unknown>;
      expect(servers.context7).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });
  });

  describe("cursor", () => {
    const agent = getAgent("cursor");

    test("buildEntry with api-key produces correct shape (no type field)", () => {
      const entry = buildEntry(agent, apiKeyAuth, "http");
      expect(entry).toEqual({
        url: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
      expect(entry).not.toHaveProperty("type");
    });

    test("buildEntry with oauth produces correct shape", () => {
      const entry = buildEntry(agent, oauthAuth, "http");
      expect(entry).toEqual({
        url: "https://mcp.context7.com/mcp/oauth",
      });
    });
  });

  describe("vscode", () => {
    const agent = getAgent("vscode");

    test("buildEntry with api-key produces VS Code HTTP shape", () => {
      expect(buildEntry(agent, apiKeyAuth, "http")).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });

    test("buildEntry with oauth produces VS Code HTTP shape without headers", () => {
      expect(buildEntry(agent, oauthAuth, "http")).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp/oauth",
      });
    });

    test.each([
      ["darwin", "/home/test", {}, "/home/test/Library/Application Support/Code/User"],
      [
        "win32",
        "/home/test",
        { APPDATA: "C:\\Users\\test\\AppData\\Roaming" },
        "C:\\Users\\test\\AppData\\Roaming/Code/User",
      ],
      ["win32", "/home/test", {}, "/home/test/AppData/Roaming/Code/User"],
      ["linux", "/home/test", { XDG_CONFIG_HOME: "/xdg" }, "/xdg/Code/User"],
      ["linux", "/home/test", {}, "/home/test/.config/Code/User"],
    ] as const)("resolves the %s user directory", (platform, home, env, expected) => {
      expect(resolveVscodeUserDir(platform, home, env)).toBe(expected);
    });

    test("owns its instructions frontmatter in the agent rule policy", () => {
      expect(agent.rule.kind).toBe("file");
      if (agent.rule.kind === "file") {
        expect(agent.rule.contentPrefix).toBe('---\napplyTo: "**"\n---\n\n');
      }
    });
  });

  describe("devin", () => {
    const agent = getAgent("devin");

    test("buildEntry with api-key produces Devin HTTP shape", () => {
      expect(buildEntry(agent, apiKeyAuth, "http")).toEqual({
        transport: "http",
        url: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });

    test("buildEntry with oauth produces Devin HTTP shape without headers", () => {
      expect(buildEntry(agent, oauthAuth, "http")).toEqual({
        transport: "http",
        url: "https://mcp.context7.com/mcp/oauth",
      });
    });

    test("uses the dedicated project MCP config introduced in Devin 3000.3", () => {
      expect(agent.mcp.projectPaths).toEqual([join(".devin", "mcp_config.json")]);
      expect(agent.skill.dir("project")).toBe(join(".devin", "skills"));
    });

    test.each([
      ["darwin", "/home/test", {}, "/home/test/.config/devin"],
      ["linux", "/home/test", {}, "/home/test/.config/devin"],
      [
        "win32",
        "/home/test",
        { APPDATA: "C:\\Users\\test\\AppData\\Roaming" },
        "C:\\Users\\test\\AppData\\Roaming/devin",
      ],
      ["win32", "/home/test", {}, "/home/test/AppData/Roaming/devin"],
    ] as const)("resolves the %s Devin config directory", (platform, home, env, expected) => {
      expect(resolveDevinConfigDir(platform, home, env)).toBe(expected);
    });
  });

  describe("copilot", () => {
    const agent = getAgent("copilot");

    test("buildEntry produces the Copilot CLI HTTP shape", () => {
      expect(buildEntry(agent, apiKeyAuth, "http")).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp",
        tools: ["*"],
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });

    test("does not claim Claude's shared project .mcp.json during auto-detection", async () => {
      const previousCwd = process.cwd();
      await writeFile(join(tempDir, ".mcp.json"), JSON.stringify({ mcpServers: {} }));
      try {
        process.chdir(tempDir);
        const detected = await detectAgents("project");
        expect(detected).toContain("claude");
        expect(detected).not.toContain("copilot");
      } finally {
        process.chdir(previousCwd);
      }
    });
  });

  describe("opencode", () => {
    const agent = getAgent("opencode");

    test("buildEntry with api-key includes type, url, enabled, and headers", () => {
      const entry = buildEntry(agent, apiKeyAuth, "http");
      expect(entry).toEqual({
        type: "remote",
        url: "https://mcp.context7.com/mcp",
        enabled: true,
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });

    test("buildEntry with oauth includes type, url, enabled without headers", () => {
      const entry = buildEntry(agent, oauthAuth, "http");
      expect(entry).toEqual({
        type: "remote",
        url: "https://mcp.context7.com/mcp/oauth",
        enabled: true,
      });
    });
  });

  describe("codex", () => {
    const agent = getAgent("codex");

    test("buildEntry with api-key uses an Authorization header", () => {
      const entry = buildEntry(agent, apiKeyAuth, "http");
      expect(entry).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });

    test("buildEntry with oauth produces correct shape", () => {
      const entry = buildEntry(agent, oauthAuth, "http");
      expect(entry).toEqual({
        type: "http",
        url: "https://mcp.context7.com/mcp/oauth",
      });
    });

    test("appends to TOML config", async () => {
      const path = join(tempDir, "config.toml");
      const { alreadyExists } = await appendTomlServer(
        path,
        "context7",
        buildEntry(agent, apiKeyAuth, "http")
      );
      expect(alreadyExists).toBe(false);

      const content = await readFile(path, "utf-8");
      expect(content).toContain("[mcp_servers.context7]");
      expect(content).toContain('type = "http"');
      expect(content).toContain('url = "https://mcp.context7.com/mcp"');
      expect(content).toContain("[mcp_servers.context7.http_headers]");
      expect(content).toContain('Authorization = "Bearer sk-test-123"');
    });
  });

  describe("gemini", () => {
    const agent = getAgent("gemini");

    test("buildEntry with api-key uses httpUrl", () => {
      const entry = buildEntry(agent, apiKeyAuth, "http");
      expect(entry).toEqual({
        httpUrl: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
      expect(entry).not.toHaveProperty("url");
    });

    test("buildEntry with oauth uses httpUrl without headers", () => {
      const entry = buildEntry(agent, oauthAuth, "http");
      expect(entry).toEqual({
        httpUrl: "https://mcp.context7.com/mcp/oauth",
      });
    });

    test("merges into settings.json with mcpServers key", async () => {
      const path = join(tempDir, "settings.json");
      await writeJsonConfig(path, { theme: "dark" });

      const existing = await readJsonConfig(path);
      const { config } = mergeServerEntry(
        existing,
        agent.mcp.configKey,
        "context7",
        buildEntry(agent, apiKeyAuth, "http")
      );
      await writeJsonConfig(path, config);

      const result = await readJsonConfig(path);
      expect(result.theme).toBe("dark");
      expect((result.mcpServers as Record<string, unknown>).context7).toEqual({
        httpUrl: "https://mcp.context7.com/mcp",
        headers: { Authorization: "Bearer sk-test-123" },
      });
    });
  });

  describe("all agents have consistent config", () => {
    test.each(ALL_AGENT_NAMES)("%s buildEntry returns url for both auth modes", (name) => {
      const agent = getAgent(name);
      const apiEntry = buildEntry(agent, apiKeyAuth, "http");
      const oauthEntry = buildEntry(agent, oauthAuth, "http");

      const urlKey = name === "gemini" ? "httpUrl" : name === "antigravity" ? "serverUrl" : "url";
      expect(apiEntry[urlKey]).toBe("https://mcp.context7.com/mcp");
      expect(oauthEntry[urlKey]).toBe("https://mcp.context7.com/mcp/oauth");
    });
  });

  describe("stdio buildEntry", () => {
    const apiKeyAuth: AuthOptions = { mode: "api-key", apiKey: "sk-test-stdio" };
    const oauthAuth: AuthOptions = { mode: "oauth" };

    test.each(["claude", "cursor", "devin", "codex", "gemini"] as const)(
      "%s stdio entry uses npx command with --api-key in args",
      (name) => {
        expect(buildEntry(getAgent(name), apiKeyAuth, "stdio")).toEqual({
          command: "npx",
          args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"],
        });
      }
    );

    test("vscode stdio entry includes the stdio transport discriminator", () => {
      const entry = buildEntry(getAgent("vscode"), apiKeyAuth, "stdio");
      expect(entry).toEqual({
        type: "stdio",
        command: "npx",
        args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"],
      });
    });

    test("copilot stdio entry includes all tools", () => {
      const entry = buildEntry(getAgent("copilot"), apiKeyAuth, "stdio");
      expect(entry).toEqual({
        type: "stdio",
        command: "npx",
        args: ["-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"],
        tools: ["*"],
      });
    });

    test("opencode stdio entry uses type:local with array command", () => {
      const entry = buildEntry(getAgent("opencode"), apiKeyAuth, "stdio");
      expect(entry).toEqual({
        type: "local",
        command: ["npx", "-y", "@upstash/context7-mcp", "--api-key", "sk-test-stdio"],
        enabled: true,
      });
    });

    test.each(ALL_AGENT_NAMES)("%s stdio entry omits --api-key for oauth mode", (name) => {
      const entry = buildEntry(getAgent(name), oauthAuth, "stdio");
      const args = (entry.args ?? entry.command) as string[];
      expect(args).not.toContain("--api-key");
      expect(args).toContain("@upstash/context7-mcp");
    });

    test("codex stdio entry serializes to TOML correctly", () => {
      const block = buildTomlServerBlock(
        "context7",
        buildEntry(getAgent("codex"), apiKeyAuth, "stdio")
      );
      expect(block).toContain("[mcp_servers.context7]");
      expect(block).toContain('command = "npx"');
      expect(block).toContain('args = ["-y","@upstash/context7-mcp","--api-key","sk-test-stdio"]');
      expect(block).not.toContain("http_headers");
    });
  });

  describe("isStdioContext7Entry", () => {
    test("detects standard command/args stdio entry", () => {
      expect(
        isStdioContext7Entry({
          command: "npx",
          args: ["-y", "@upstash/context7-mcp", "--api-key", "k"],
        })
      ).toBe(true);
    });

    test("detects entry with @latest specifier", () => {
      expect(
        isStdioContext7Entry({ command: "npx", args: ["-y", "@upstash/context7-mcp@latest"] })
      ).toBe(true);
    });

    test("detects entry with pinned version", () => {
      expect(
        isStdioContext7Entry({ command: "npx", args: ["-y", "@upstash/[email protected]"] })
      ).toBe(true);
    });

    test("detects OpenCode array-command form", () => {
      expect(
        isStdioContext7Entry({
          type: "local",
          command: ["npx", "-y", "@upstash/context7-mcp@latest"],
          enabled: true,
        })
      ).toBe(true);
    });

    test("returns false for HTTP entry", () => {
      expect(isStdioContext7Entry({ url: "https://mcp.context7.com/mcp" })).toBe(false);
    });

    test("returns false for unrelated stdio package", () => {
      expect(isStdioContext7Entry({ command: "npx", args: ["-y", "@some-other/package"] })).toBe(
        false
      );
    });

    test("returns false for null/undefined", () => {
      expect(isStdioContext7Entry(null)).toBe(false);
      expect(isStdioContext7Entry(undefined)).toBe(false);
    });
  });

  describe("patchStdioApiKey", () => {
    test("preserves @latest package specifier", () => {
      const patched = patchStdioApiKey(
        { command: "npx", args: ["-y", "@upstash/context7-mcp@latest"] },
        "new-key"
      );
      expect(patched).toEqual({
        command: "npx",
        args: ["-y", "@upstash/context7-mcp@latest", "--api-key", "new-key"],
      });
    });

    test("preserves pinned version specifier", () => {
      const patched = patchStdioApiKey(
        { command: "npx", args: ["-y", "@upstash/[email protected]"] },
        "new-key"
      );
      expect(patched.args).toEqual(["-y", "@upstash/[email protected]", "--api-key", "new-key"]);
    });

    test("replaces an existing --api-key value", () => {
      const patched = patchStdioApiKey(
        {
          command: "npx",
          args: ["-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"],
        },
        "NEW"
      );
      expect(patched.args).toEqual(["-y", "@upstash/context7-mcp@latest", "--api-key", "NEW"]);
    });

    test("removes --api-key when new key is undefined (oauth)", () => {
      const patched = patchStdioApiKey(
        { command: "npx", args: ["-y", "@upstash/context7-mcp", "--api-key", "OLD"] },
        undefined
      );
      expect(patched.args).toEqual(["-y", "@upstash/context7-mcp"]);
    });

    test("replaces an inline --api-key=<value> arg", () => {
      const patched = patchStdioApiKey(
        { command: "npx", args: ["-y", "@upstash/context7-mcp", "--api-key=OLD"] },
        "NEW"
      );
      expect(patched.args).toEqual(["-y", "@upstash/context7-mcp", "--api-key", "NEW"]);
    });

    test("removes an inline --api-key=<value> arg when new key is undefined (oauth)", () => {
      const patched = patchStdioApiKey(
        { command: "npx", args: ["-y", "@upstash/context7-mcp", "--api-key=OLD"] },
        undefined
      );
      expect(patched.args).toEqual(["-y", "@upstash/context7-mcp"]);
    });

    test("preserves other args (e.g. --debug) untouched", () => {
      const patched = patchStdioApiKey(
        {
          command: "npx",
          args: ["-y", "@upstash/context7-mcp", "--debug", "--api-key", "OLD"],
        },
        "NEW"
      );
      expect(patched.args).toEqual(["-y", "@upstash/context7-mcp", "--debug", "--api-key", "NEW"]);
    });

    test("patches OpenCode array-command form", () => {
      const patched = patchStdioApiKey(
        {
          type: "local",
          command: ["npx", "-y", "@upstash/context7-mcp@latest", "--api-key", "OLD"],
          enabled: true,
        },
        "NEW"
      );
      expect(patched).toEqual({
        type: "local",
        command: ["npx", "-y", "@upstash/context7-mcp@latest", "--api-key", "NEW"],
        enabled: true,
      });
    });

    test("preserves unrelated top-level fields", () => {
      const patched = patchStdioApiKey(
        { command: "npx", args: ["-y", "@upstash/context7-mcp"], cwd: "/custom" },
        "NEW"
      );
      expect(patched.cwd).toBe("/custom");
    });
  });
});