Skip to content

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

CTX7-3290: Admin MCP icons, server card and a smaller docs7_list_sites (#3517)

Enes Gulesd980242a5b04
diff --git a/packages/admin-mcp/README.md b/packages/admin-mcp/README.md
index 8631f631..e526a96e 100644
--- a/packages/admin-mcp/README.md
+++ b/packages/admin-mcp/README.md
@@ -58,7 +58,7 @@ One OAuth connection reaches every teamspace you are a member of, with your role
| Group | Tools |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account | `list_teamspaces`, `get_teamspace`, `manage_members` |
-| libraries | `list_libraries`, `get_library`, `add_library`, `refresh_library`, `update_library_config`, `manage_library_versions`, `claim_library`, `remove_library`, `get_library_analytics`, `get_library_suggestions` |
+| libraries | `list_libraries`, `get_library`, `add_library`, `refresh_library`, `update_library_config`, `manage_library_versions`, `claim_library`, `remove_library`, `get_library_analytics`, `get_library_suggestions`, `get_library_benchmarks` |
| rules | `manage_rules`, `get_library_policies`, `update_library_policies`, `manage_library_requests` |
| usage | `get_teamspace_usage`, `set_spending_limit` |
| docs7 | `docs7_list_sites`, `docs7_get_site`, `docs7_create_site`, `docs7_update_site`, `docs7_check_domain`, `docs7_list_deployments`, `docs7_get_deployment`, `docs7_deploy`, `docs7_remove_preview`, `docs7_get_agent_runs`, `docs7_manage_feature_requests`, `docs7_get_analytics`, `docs7_query_logs`, `docs7_get_conversation` |
diff --git a/packages/admin-mcp/api/server-card.ts b/packages/admin-mcp/api/server-card.ts
new file mode 100644
index 00000000..020f9a55
--- /dev/null
+++ b/packages/admin-mcp/api/server-card.ts
@@ -0,0 +1,46 @@
+// SEP-2127 server card at `{streamable-http-url}/server-card`, as the docs MCP serves it.
+import { RESOURCE_URL, withCors } from "../src/http.js";
+import { SERVER_ICONS, SERVER_VERSION } from "../src/server.js";
+
+export const serverCard = {
+ $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+ name: "io.github.upstash/context7-admin",
+ title: "Context7 Admin",
+ description: "Manage Context7 teamspaces, libraries, Docs7 sites and Ask sites.",
+ version: SERVER_VERSION,
+ websiteUrl: "https://context7.com",
+ icons: SERVER_ICONS,
+ remotes: [
+ {
+ type: "streamable-http",
+ url: RESOURCE_URL,
+ headers: [
+ {
+ name: "Authorization",
+ description:
+ "Optional. Sign in with OAuth, or send a Context7 API key created with Management access.",
+ isRequired: false,
+ isSecret: true,
+ value: "Bearer {api_key}",
+ variables: {
+ api_key: { description: "Context7 API key", isSecret: true, placeholder: "ctx7sk-..." },
+ },
+ },
+ ],
+ },
+ ],
+};
+
+export default {
+ fetch: (request: Request) =>
+ withCors(
+ request,
+ () =>
+ new Response(JSON.stringify(serverCard), {
+ headers: {
+ "Content-Type": "application/mcp-server-card+json",
+ "Cache-Control": "public, max-age=3600",
+ },
+ })
+ ),
+};
diff --git a/packages/admin-mcp/src/server.ts b/packages/admin-mcp/src/server.ts
index e8b32db2..d0314fa4 100644
--- a/packages/admin-mcp/src/server.ts
+++ b/packages/admin-mcp/src/server.ts
@@ -139,10 +139,24 @@ function errorText(error: unknown, untrusted: boolean): string {
const INSTRUCTIONS = [
"Manage Context7 teamspaces, libraries, Docs7 sites and Ask sites. Tools take `teamspace` as an id or a name; leave it out when the user has one teamspace. list_teamspaces gives them all.",
"Long jobs (library parse, Docs7 build, Ask crawl) take minutes: call the get_ tool with `wait: true` and repeat until the state is final. The Docs7 agents run on their schedules (docs7_update_site); this server does not start them.",
- "Common flows: claim a library (claim_library gives context7.json; commit it, then claim_library with verify: true). Set up Ask (ask_create_site gives a meta tag; add it to the site head, deploy, then ask_verify_site). Fix a failed docs build (docs7_get_deployment with include health and logs). Find doc gaps (get_library_suggestions, docs7_get_analytics report queries, or ask_get_analytics) and fix them in the repository.",
+ "Common flows: claim a library (claim_library gives context7.json; commit it, then claim_library with verify: true). Set up Ask (ask_create_site gives a meta tag; add it to the site head, deploy, then ask_verify_site). Fix a failed docs build (docs7_get_deployment with include health and logs). Find doc gaps (get_library_benchmarks for the questions the docs fail, get_library_suggestions, docs7_get_analytics report queries, or ask_get_analytics) and fix them in the repository.",
"Remove and delete actions need the user's confirmation first. Deleting a whole Docs7 or Ask site, billing, plans, API keys and SSO are not in this server: send the user to https://context7.com/dashboard.",
].join("\n");
+/** The Context7 icon, as the docs MCP server uses it. The vector icon scales; the PNG is 512x512. */
+export const SERVER_ICONS = [
+ {
+ src: "https://context7.com/context7-icon-green.svg",
+ mimeType: "image/svg+xml",
+ sizes: ["any"],
+ },
+ {
+ src: "https://context7.com/context7-icon-green.png",
+ mimeType: "image/png",
+ sizes: ["512x512"],
+ },
+];
+
/** What `mcp-handler` needs to build the server for each request. */
export const SERVER_OPTIONS = {
serverInfo: {
@@ -151,6 +165,7 @@ export const SERVER_OPTIONS = {
version: SERVER_VERSION,
websiteUrl: "https://context7.com",
description: "Manage Context7 teamspaces, libraries, Docs7 sites and Ask sites.",
+ icons: SERVER_ICONS,
},
capabilities: { tools: { listChanged: false } },
instructions: INSTRUCTIONS,
diff --git a/packages/admin-mcp/src/tools.ts b/packages/admin-mcp/src/tools.ts
index 4c190073..5edaa698 100644
--- a/packages/admin-mcp/src/tools.ts
+++ b/packages/admin-mcp/src/tools.ts
@@ -109,6 +109,159 @@ const wait = z
.optional()
.describe("Wait up to about 25 seconds for the job to finish before answering.");
+/**
+ * What an agent needs from a Docs7 site in a list: what it is, where it is
+ * served, and how its agents are set. Internal ids (worker, installation,
+ * repository, creator) stay out; docs7_get_site has every field.
+ */
+function siteSummary(site: Record<string, unknown>): Record<string, unknown> {
+ const review = site.pullRequestReview as { enabled?: unknown } | undefined;
+ const watch = site.codeWatch as { enabled?: unknown; repositories?: unknown[] } | undefined;
+ return {
+ id: site.id,
+ name: site.name,
+ repoUrl: site.repoUrl,
+ branch: site.branch ?? site.defaultBranch,
+ docsPath: site.docsPath,
+ hosting: site.hosting,
+ // A proxy-routed site is built under its custom domain path, on docs7.io too.
+ url: site.platformHostname
+ ? `https://${site.platformHostname}${site.customDomainRouting === "proxy" ? (site.customDomainPath ?? "") : ""}`
+ : undefined,
+ customDomain: site.customDomain
+ ? `${site.customDomain}${site.customDomainPath ?? ""}`
+ : undefined,
+ customDomainStatus: site.customDomain ? site.customDomainStatus : undefined,
+ libraryId: site.context7LibraryName,
+ improveSchedule: site.improveSchedule,
+ buildFixSchedule: site.buildFixSchedule,
+ pullRequestReview: review?.enabled,
+ codeWatchRepositories: watch?.enabled ? watch.repositories?.length : undefined,
+ };
+}
+
+/** One site with every setting an agent can act on; internal ids stay out. */
+function siteDetails(site: Record<string, unknown>): Record<string, unknown> {
+ const watch = site.codeWatch as { enabled?: unknown; repositories?: { repoUrl?: unknown }[] };
+ const records = site.customDomainRecords as unknown[] | undefined;
+ return {
+ ...siteSummary(site),
+ source: site.source === "local" ? "cli" : "github",
+ // As docs7_update_site takes them: null branch follows the repository default.
+ branch: site.branch ?? null,
+ defaultBranch: site.defaultBranch,
+ // Two fields, as docs7_update_site takes them; the list joins them.
+ customDomain: site.customDomain,
+ customDomainPath: site.customDomain ? site.customDomainPath : undefined,
+ customDomainRouting: site.customDomain ? site.customDomainRouting : undefined,
+ customDomainRecords: records?.length ? records : undefined,
+ context7Index: site.context7Index,
+ analyticsUrl: site.analyticsUrl,
+ pullRequestReview: site.pullRequestReview,
+ // docs7_update_site takes `enabled` and the full list, so both stay, also while it is off.
+ codeWatchRepositories: undefined,
+ codeWatch: watch && {
+ enabled: watch.enabled,
+ repositories: watch.repositories?.map((repository) => repository.repoUrl),
+ },
+ createdAt: site.createdAt,
+ updatedAt: site.updatedAt,
+ };
+}
+
+/** The agent of a run, as the dashboard names it, from the run's input kind. */
+function runAgent(run: { input?: { kind?: unknown } }): string {
+ switch (run.input?.kind) {
+ case "review":
+ return "prReview";
+ case "code_change":
+ return "codeWatch";
+ case "health":
+ return "buildFix";
+ default:
+ return "context7";
+ }
+}
+
+type AgentRun = {
+ state?: unknown;
+ createdAt?: unknown;
+ input?: { kind?: unknown };
+ pullRequest?: { state?: unknown };
+};
+
+/**
+ * This UTC month's runs of each agent and the states of their pull requests,
+ * read from the newest 50 runs of each history, as the dashboard's Agents card
+ * counts them. Superseded runs are left out, as there.
+ */
+export function agentActivity(histories: AgentRun[][], now = new Date()): Record<string, unknown> {
+ const monthStart = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1);
+ const runs: Record<string, number> = {};
+ const failedRuns: Record<string, number> = {};
+ const pullRequests: Record<string, Record<string, number>> = {};
+ for (const run of histories.flat()) {
+ if (run.state === "superseded") continue;
+ if (typeof run.createdAt !== "string" || Date.parse(run.createdAt) < monthStart) continue;
+ const agent = runAgent(run);
+ runs[agent] = (runs[agent] ?? 0) + 1;
+ if (run.state === "failed") failedRuns[agent] = (failedRuns[agent] ?? 0) + 1;
+ const state = run.pullRequest?.state;
+ if (typeof state === "string") {
+ const counts = (pullRequests[agent] ??= {});
+ counts[state] = (counts[state] ?? 0) + 1;
+ }
+ }
+ return { month: new Date(monthStart).toISOString().slice(0, 7), runs, failedRuns, pullRequests };
+}
+
+const RUN_NOISE = new Set(["boxId", "siteId"]);
+
+/**
+ * A run with the machine-readable blocks of its summary as fields: per
+ * suggestion results and the pull request title. Box and site ids stay out.
+ */
+function runView(run: Record<string, unknown>): Record<string, unknown> {
+ const { summary, ...rest } = without(run, RUN_NOISE) as Record<string, unknown>;
+ if (typeof summary !== "string") return rest;
+ const block = (name: string) => summary.match(new RegExp(`<!-- ${name}\\n([\\s\\S]*?)\\n-->`));
+ const results = block("docs7-suggestion-results");
+ const title = block("docs7-pr-title");
+ let parsed: unknown;
+ try {
+ parsed = results ? JSON.parse(results[1]) : undefined;
+ } catch {
+ parsed = undefined;
+ }
+ return {
+ ...rest,
+ prTitle: title?.[1].trim(),
+ suggestionResults: parsed,
+ summary: summary.replace(/<!-- docs7-[\s\S]*?-->\n?/g, "").trim() || undefined,
+ };
+}
+
+/** The value with these keys removed at every depth. */
+function without(value: unknown, keys: Set<string>): unknown {
+ if (Array.isArray(value)) return value.map((item) => without(item, keys));
+ if (!value || typeof value !== "object") return value;
+ return Object.fromEntries(
+ Object.entries(value)
+ .filter(([key]) => !keys.has(key))
+ .map(([key, item]) => [key, without(item, keys)])
+ );
+}
+
+/** Deployment fields an agent never needs: the site it asked for, Worker names. */
+const DEPLOYMENT_NOISE = new Set(["siteId", "workerName", "attributionRequired"]);
+
+/** A build without its noise; `requestedCommitSha` only when the build ran another commit. */
+function deploymentView(deployment: unknown): unknown {
+ const view = without(deployment, DEPLOYMENT_NOISE) as Record<string, unknown>;
+ if (view && view.requestedCommitSha === view.commitSha) delete view.requestedCommitSha;
+ return view;
+}
+
/** A Docs7 site deployed from the CLI (`source: "local"`), which has its own build routes. */
async function isCliSite(api: Api, sitePath: string): Promise<boolean> {
return data(await api.get(sitePath)).source === "local";
@@ -157,12 +310,14 @@ const libraryId = z
.describe('Library id, such as "/owner/repo" (from list_libraries). "owner/repo" also works.');
const siteId = z.string().describe("Docs7 site id (from docs7_list_sites).");
const siteKey = z.string().describe("Ask site key, such as ask_… (from ask_list_sites).");
+const ASK_TOP = 20;
const askDays = z.union([z.literal(1), z.literal(7), z.literal(30)]).optional();
const SOURCE_TYPE = z.enum([
"public_repos",
"private_sources",
"confluence",
+ "notion",
"uploaded_files",
"websites",
"llmstxt",
@@ -273,7 +428,7 @@ export const TOOLS: ToolDef[] = [
name: "get_library",
title: "Get library",
description:
- "Get one library: parse state (processing, finalizing, complete, error), the active task's progress, versions, token and snippet counts. After add_library, refresh_library or manage_library_versions, call it with `wait: true` until the state is complete or error.",
+ "Get one library: parse state (processing, finalizing, complete, error), the active task's progress, versions, token and snippet counts, and its benchmark score (0 to 100). After add_library, refresh_library or manage_library_versions, call it with `wait: true` until the state is complete or error.",
kind: "read",
args: { library_id: libraryId, wait },
run: ({ teamspace, library_id, wait }, api) => {
@@ -484,6 +639,33 @@ export const TOOLS: ToolDef[] = [
args: { library_id: libraryId },
run: ({ teamspace, library_id }, api) => api.get(`${lib(teamspace, library_id)}/suggestions`),
}),
+ tool({
+ name: "get_library_benchmarks",
+ title: "Get library benchmarks",
+ description:
+ "Get the benchmark of a library the teamspace owns: score statistics and the graded questions (real questions asked about the library, each with the score its docs earned and the grader's explanation). Lowest scores first by default: these are the questions the docs fail. get_library_suggestions gives the fixes Context7 proposes for them.",
+ kind: "read",
+ untrusted: true,
+ args: {
+ library_id: libraryId,
+ order: z.enum(["lowest", "newest"]).optional().describe("Default lowest."),
+ limit: z
+ .number()
+ .int()
+ .min(1)
+ .max(100)
+ .optional()
+ .describe("Questions to return. Default 20."),
+ },
+ run: async ({ teamspace, library_id, order = "lowest", limit = 20 }, api) => {
+ const { stats, benchmarks = [] } = (await api.get(
+ `${lib(teamspace, library_id)}/benchmarks`
+ )) as { stats?: unknown; benchmarks?: { score: number }[] };
+ const sorted =
+ order === "lowest" ? [...benchmarks].sort((a, b) => a.score - b.score) : benchmarks;
+ return { stats, benchmarks: sorted.slice(0, limit) };
+ },
+ }),
// ---------- rules and policies ----------
tool({
@@ -506,27 +688,34 @@ export const TOOLS: ToolDef[] = [
.optional()
.describe("The rule id, after the user confirms the deletion (delete)."),
},
- run: (args, api) => {
+ // The rules routes answer { success, data }; the other tools answer the data itself.
+ run: async (args, api) => {
const base = `${ts(args.teamspace)}/rules`;
const ruleId = () => seg(need(args.rule_id, "`rule_id` is required."));
switch (args.action) {
case "list":
- return api.get(base);
+ return data(await api.get(base));
case "create":
- return api.post(base, {
- text: need(args.text, "`text` is required."),
- libraryId: args.library_id ? normalizeLibraryId(args.library_id) : null,
- });
+ return data(
+ await api.post(base, {
+ text: need(args.text, "`text` is required."),
+ libraryId: args.library_id ? normalizeLibraryId(args.library_id) : null,
+ })
+ );
case "update":
- return api.patch(`${base}/${ruleId()}`, {
- text: need(args.text, "`text` is required."),
- libraryId: args.library_id ? normalizeLibraryId(args.library_id) : null,
- });
+ return data(
+ await api.patch(`${base}/${ruleId()}`, {
+ text: need(args.text, "`text` is required."),
+ libraryId: args.library_id ? normalizeLibraryId(args.library_id) : null,
+ })
+ );
default:
confirmed(args.confirm, need(args.rule_id, "`rule_id` is required."), "the rule id");
- return api.del(`${base}/${ruleId()}`, {
- query: { libraryId: args.library_id && normalizeLibraryId(args.library_id) },
- });
+ return data(
+ await api.del(`${base}/${ruleId()}`, {
+ query: { libraryId: args.library_id && normalizeLibraryId(args.library_id) },
+ })
+ );
}
},
}),
@@ -588,15 +777,22 @@ export const TOOLS: ToolDef[] = [
.optional(),
dry_run: z.boolean().optional().describe("Preview the change and its library count."),
},
- run: ({ teamspace, source_types, library_filters, dry_run }, api) => {
+ run: async ({ teamspace, source_types, library_filters, dry_run }, api) => {
if (!source_types && !library_filters) {
throw new ToolError("Send `source_types` or `library_filters`.");
}
- return api.patch(`${ts(teamspace)}/policies`, {
+ const result = (await api.patch(`${ts(teamspace)}/policies`, {
sourceTypes: source_types,
libraryFilters: library_filters,
dryRun: dry_run,
- });
+ })) as { libraryFilters?: { mode?: unknown } } | null;
+ if ((library_filters?.quality || library_filters?.select) && !result?.libraryFilters?.mode) {
+ return {
+ ...result,
+ note: 'Library filters are off (mode is null), so these rules change nothing. Set `library_filters.mode` to "quality" or "select" to apply them.',
+ };
+ }
+ return result;
},
}),
tool({
@@ -670,24 +866,40 @@ export const TOOLS: ToolDef[] = [
name: "docs7_list_sites",
title: "List Docs7 sites",
description:
- "List the Docs7 sites of the teamspace: GitHub sites in `data`, sites deployed from the CLI in `localSites`.",
+ "List the Docs7 sites of the teamspace: GitHub sites in `sites`, sites deployed from the CLI in `cliSites`, with their address and agent settings. docs7_get_site gives every setting of one site.",
kind: "read",
args: {},
- run: ({ teamspace }, api) => api.get(`${ts(teamspace)}/sites`),
+ run: async ({ teamspace }, api) => {
+ const body = (await api.get(`${ts(teamspace)}/sites`)) as {
+ data?: Record<string, unknown>[];
+ localSites?: Record<string, unknown>[];
+ };
+ return {
+ sites: (body.data ?? []).map(siteSummary),
+ cliSites: (body.localSites ?? []).map(siteSummary),
+ };
+ },
}),
tool({
name: "docs7_get_site",
title: "Get Docs7 site",
description:
- "Get one Docs7 site: settings, custom domain status, agent settings and, for a GitHub site, agent usage.",
+ "Get one Docs7 site: settings, custom domain, agent settings and, for a GitHub site, agent usage: the plan, whether this month's agent runs are used up, and this UTC month's runs, failed runs and pull request states by agent.",
kind: "read",
args: { site_id: siteId },
run: async ({ teamspace, site_id }, api) => {
const path = site(teamspace, site_id);
- const details = await api.get(path);
+ const details = data(await api.get(path));
// A CLI site has no agent, and its agent-usage route answers 404.
- if (data(details).source === "local") return { site: details };
- return { site: details, agentUsage: await api.get(`${path}/agent-usage`) };
+ if (details.source === "local") return { site: siteDetails(details) };
+ const [usage, ...histories] = await Promise.all([
+ api.get(`${path}/agent-usage`),
+ ...["improve", "review", "watch"].map((history) =>
+ api.get(`${path}/agent-runs`, { history, limit: 50 })
+ ),
+ ]);
+ const runs = histories.map((body) => (body as { data?: AgentRun[] })?.data ?? []);
+ return { site: siteDetails(details), agentUsage: { ...data(usage), ...agentActivity(runs) } };
},
}),
tool({
@@ -799,7 +1011,16 @@ export const TOOLS: ToolDef[] = [
kind: "write",
idempotent: true,
args: { site_id: siteId },
- run: ({ teamspace, site_id }, api) => api.post(`${site(teamspace, site_id)}/domain/refresh`),
+ run: async ({ teamspace, site_id }, api) => {
+ const checked = data(await api.post(`${site(teamspace, site_id)}/domain/refresh`));
+ return {
+ customDomain: checked.customDomain,
+ customDomainPath: checked.customDomain ? checked.customDomainPath : undefined,
+ routing: checked.customDomainRouting,
+ status: checked.customDomainStatus,
+ records: checked.customDomainRecords,
+ };
+ },
}),
tool({
name: "docs7_list_deployments",
@@ -820,8 +1041,19 @@ export const TOOLS: ToolDef[] = [
run: async ({ teamspace, site_id, page }, api) => {
const path = site(teamspace, site_id);
// A CLI site keeps its builds apart; its /deployments route answers 404.
- if (await isCliSite(api, path)) return api.get(`${path}/local-deployments`);
- return api.get(`${path}/deployments`, { page });
+ const body = (await isCliSite(api, path))
+ ? await api.get(`${path}/local-deployments`)
+ : await api.get(`${path}/deployments`, { page });
+ const { data: rows, ...rest } = without(body, DEPLOYMENT_NOISE) as { data?: unknown };
+ // A GitHub site answers { data: [...] }, a CLI site { data: { deployments, targets } }.
+ if (Array.isArray(rows)) return { data: rows.map(deploymentView), ...rest };
+ const cli = rows as { deployments?: unknown[] } | undefined;
+ return {
+ data: cli?.deployments
+ ? { ...cli, deployments: cli.deployments.map(deploymentView) }
+ : rows,
+ ...rest,
+ };
},
}),
tool({
@@ -863,7 +1095,7 @@ export const TOOLS: ToolDef[] = [
: await once();
const parts = await Promise.all(include.map((part) => api.get(`${path}/${part}`)));
return Object.fromEntries([
- ["deployment", deployment],
+ ["deployment", deploymentView(data(deployment))],
...include.map((part, index) => [part, parts[index]]),
]);
},
@@ -915,8 +1147,15 @@ export const TOOLS: ToolDef[] = [
history: z.enum(["improve", "review", "watch"]).optional().describe("Default improve."),
limit: z.number().int().min(1).max(50).optional().describe("Newest n runs."),
},
- run: ({ teamspace, site_id, history, limit }, api) =>
- api.get(`${site(teamspace, site_id)}/agent-runs`, { history, limit }),
+ run: async ({ teamspace, site_id, history, limit }, api) => {
+ const body = (await api.get(`${site(teamspace, site_id)}/agent-runs`, {
+ history,
+ limit,
+ })) as {
+ data?: Record<string, unknown>[];
+ };
+ return { data: (body?.data ?? []).map(runView) };
+ },
}),
tool({
name: "docs7_manage_feature_requests",
@@ -1011,10 +1250,10 @@ export const TOOLS: ToolDef[] = [
page: z.number().int().min(1).optional(),
previews: z.boolean().optional(),
},
- run: (args, api) => {
+ run: async (args, api) => {
const to = new Date();
const from = new Date(to.getTime() - (args.days ?? 7) * 86_400_000);
- return api.post(`${site(args.teamspace, args.site_id)}/analytics/explore`, {
+ const body = (await api.post(`${site(args.teamspace, args.site_id)}/analytics/explore`, {
previews: args.previews ?? false,
query: {
dataset: args.dataset,
@@ -1026,7 +1265,12 @@ export const TOOLS: ToolDef[] = [
order: args.order ?? "newest",
page: args.page ?? 1,
},
- });
+ })) as { data?: { series?: { group?: string | null }[] } };
+ // A grouped series charts the top groups; its null group sums all the others.
+ if (args.group_by) {
+ for (const point of body?.data?.series ?? []) point.group ??= "other";
+ }
+ return body;
},
}),
tool({
@@ -1103,8 +1347,17 @@ export const TOOLS: ToolDef[] = [
site_key: siteKey,
days: askDays.describe("Window in days. Default 30."),
},
- run: ({ teamspace, site_key, days }, api) =>
- api.get(`${askSite(teamspace, site_key)}/analytics`, { days }),
+ run: async ({ teamspace, site_key, days }, api) => {
+ const body = (await api.get(`${askSite(teamspace, site_key)}/analytics`, { days })) as {
+ data?: Record<string, unknown>;
+ };
+ // Both lists hold every distinct question; the first ASK_TOP carry the signal.
+ const report = body?.data ?? {};
+ const top = (list: unknown) => (Array.isArray(list) ? list.slice(0, ASK_TOP) : list);
+ return {
+ data: { ...report, gaps: top(report.gaps), topQuestions: top(report.topQuestions) },
+ };
+ },
}),
tool({
name: "ask_list_questions",
diff --git a/packages/admin-mcp/test/admin-mcp.test.ts b/packages/admin-mcp/test/admin-mcp.test.ts
index 0cfad992..d7d8210a 100644
--- a/packages/admin-mcp/test/admin-mcp.test.ts
+++ b/packages/admin-mcp/test/admin-mcp.test.ts
@@ -1,7 +1,7 @@
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
import { createAdminHandler } from "../src/http.js";
-import { normalizeLibraryId, poll } from "../src/tools.js";
+import { agentActivity, normalizeLibraryId, poll } from "../src/tools.js";
// The server under test is the web-standard handler, driven by a real MCP
// client. Global fetch (the management API) is stubbed: no network.
@@ -291,15 +291,24 @@ test("poll stops at a final state or at the deadline", async () => {
test("deployment tools read a CLI site's builds from local-deployments", async () => {
apiReply = (call) => ({
body: call.path.endsWith("/local-deployments")
- ? { data: { deployments: [{ id: "d-1", state: "succeeded" }], targets: [] } }
+ ? {
+ data: {
+ deployments: [
+ { id: "d-1", state: "succeeded", commitSha: "abc", requestedCommitSha: "abc" },
+ ],
+ targets: [],
+ },
+ }
: { data: { id: "site-1", source: "local" } },
});
const client = await connect();
- await client.callTool({
+ const list = await client.callTool({
name: "docs7_list_deployments",
arguments: { teamspace: TS, site_id: "site-1" },
});
+ expect(text(list)).toContain('"deployments":[{"id":"d-1"');
+ expect(text(list)).not.toContain("requestedCommitSha");
const one = await client.callTool({
name: "docs7_get_deployment",
arguments: { teamspace: TS, site_id: "site-1", deployment_id: "d-1" },
@@ -341,3 +350,144 @@ test("the protected resource metadata names the scopes clients may ask for", asy
scopes_supported: ["profile", "email"],
});
});
+
+test("docs7_list_sites keeps what an agent needs and drops internal ids", async () => {
+ apiReply = () => ({
+ body: {
+ data: [
+ {
+ id: "s-1",
+ repoUrl: "https://github.com/acme/docs",
+ defaultBranch: "main",
+ docsPath: "docs",
+ hosting: "on",
+ platformHostname: "acme-docs.docs7.io",
+ customDomain: "acme.com",
+ customDomainPath: "/docs",
+ customDomainRouting: "proxy",
+ customDomainStatus: "active",
+ context7LibraryName: "/acme/docs",
+ workerName: "s-abc",
+ installationId: 1,
+ createdBy: "user_1",
+ codeWatch: { enabled: true, repositories: [{ repoUrl: "x" }, { repoUrl: "y" }] },
+ },
+ ],
+ localSites: [
+ { id: "c-1", name: "CLI docs", hosting: "on", platformHostname: "cli.docs7.io" },
+ ],
+ },
+ });
+ const client = await connect();
+ const result = JSON.parse(
+ text(await client.callTool({ name: "docs7_list_sites", arguments: { teamspace: TS } }))
+ );
+
+ expect(result.sites[0]).toEqual({
+ id: "s-1",
+ repoUrl: "https://github.com/acme/docs",
+ branch: "main",
+ docsPath: "docs",
+ hosting: "on",
+ url: "https://acme-docs.docs7.io/docs",
+ customDomain: "acme.com/docs",
+ customDomainStatus: "active",
+ libraryId: "/acme/docs",
+ codeWatchRepositories: 2,
+ });
+ expect(result.cliSites[0]).toMatchObject({ id: "c-1", name: "CLI docs" });
+});
+
+test("the server card and serverInfo carry the Context7 icon", async () => {
+ const { default: card } = await import("../api/server-card.js");
+ const body = await (
+ await card.fetch(new Request("https://admin.mcp.context7.com/mcp/server-card"))
+ ).json();
+ expect(body).toMatchObject({
+ name: "io.github.upstash/context7-admin",
+ remotes: [{ type: "streamable-http", url: "https://admin.mcp.context7.com/mcp" }],
+ });
+ expect(body.icons[0].src).toBe("https://context7.com/context7-icon-green.svg");
+
+ const client = await connect();
+ expect(client.getServerVersion()?.icons?.[0]?.src).toBe(
+ "https://context7.com/context7-icon-green.svg"
+ );
+});
+
+test("agent usage counts this UTC month's runs by agent, without superseded runs", () => {
+ const now = new Date("2026-10-22T12:00:00Z");
+ const usage = agentActivity(
+ [
+ [
+ { state: "completed", createdAt: "2026-10-02T00:00:00Z", pullRequest: { state: "merged" } },
+ { state: "completed", createdAt: "2026-10-04T00:00:00Z", pullRequest: { state: "open" } },
+ { state: "failed", createdAt: "2026-10-03T00:00:00Z", input: { kind: "health" } },
+ { state: "completed", createdAt: "2026-09-30T23:59:59Z", pullRequest: { state: "open" } },
+ ],
+ [{ state: "superseded", createdAt: "2026-10-05T00:00:00Z", input: { kind: "review" } }],
+ [
+ {
+ state: "completed",
+ createdAt: "2026-10-21T00:00:00Z",
+ input: { kind: "code_change" },
+ pullRequest: { state: "open" },
+ },
+ ],
+ ],
+ now
+ );
+ expect(usage).toEqual({
+ month: "2026-10",
+ runs: { context7: 2, buildFix: 1, codeWatch: 1 },
+ failedRuns: { buildFix: 1 },
+ pullRequests: { context7: { merged: 1, open: 1 }, codeWatch: { open: 1 } },
+ });
+});
+
+test("docs7_get_agent_runs turns the summary's result blocks into fields", async () => {
+ apiReply = () => ({
+ body: {
+ data: [
+ {
+ id: "r-1",
+ boxId: "box",
+ summary:
+ '<!-- docs7-suggestion-results\n[{"suggestion":1,"status":"fixed"}]\n-->\n<!-- docs7-pr-title\ndocs: fix it\n-->\n- **One** — done',
+ },
+ ],
+ },
+ });
+ const result = await (
+ await connect()
+ ).callTool({ name: "docs7_get_agent_runs", arguments: { teamspace: TS, site_id: "s-1" } });
+ const body = JSON.parse(text(result).split("\n").slice(2, -1).join("\n"));
+ expect(body.data[0]).toEqual({
+ id: "r-1",
+ prTitle: "docs: fix it",
+ suggestionResults: [{ suggestion: 1, status: "fixed" }],
+ summary: "- **One** — done",
+ });
+});
+
+test("get_library_benchmarks gives the lowest scores first", async () => {
+ apiReply = () => ({
+ body: {
+ stats: { count: 3 },
+ benchmarks: [
+ { score: 80, query: "a" },
+ { score: 20, query: "b" },
+ { score: 50, query: "c" },
+ ],
+ },
+ });
+ const result = await (
+ await connect()
+ ).callTool({
+ name: "get_library_benchmarks",
+ arguments: { teamspace: TS, library_id: "/acme/docs", limit: 2 },
+ });
+ const body = JSON.parse(text(result).split("\n").slice(2, -1).join("\n"));
+ expect(body.benchmarks.map((b: { query: string }) => b.query)).toEqual(["b", "c"]);
+ expect(apiCalls[0].path).toBe(`/v2/teamspaces/${TS}/libraries/acme/docs/benchmarks`);
+});
diff --git a/packages/admin-mcp/vercel.json b/packages/admin-mcp/vercel.json
index 4404631c..9506bb2e 100644
--- a/packages/admin-mcp/vercel.json
+++ b/packages/admin-mcp/vercel.json
@@ -6,6 +6,10 @@
"source": "/mcp",
"destination": "/api/mcp"
},
+ {
+ "source": "/mcp/server-card",
+ "destination": "/api/server-card"
+ },
{
"source": "/.well-known/oauth-protected-resource",
"destination": "/api/oauth-protected-resource"