Context7 Platform -- Up-to-date docs for AI agents
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");
});
});
});