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.mdindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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", asyscopes_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.jsonindex 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"