Context7 Platform -- Up-to-date docs for AI agents
import { z } from "zod";
/** `read` changes nothing; `destructive` deletes data that cannot be restored. */
export type Kind = "read" | "write" | "destructive";
type Query = Record<string, string | number | boolean | undefined>;
/** Calls one management API endpoint with the caller's credential. */
export interface Api {
get(path: string, query?: Query): Promise<unknown>;
post(path: string, body?: unknown): Promise<unknown>;
patch(path: string, body: unknown): Promise<unknown>;
put(path: string, body: unknown): Promise<unknown>;
del(path: string, options?: { query?: Query; body?: unknown }): Promise<unknown>;
}
/** A refusal or bad argument: shown to the model as a tool error. */
export class ToolError extends Error {}
type Args<S extends z.ZodRawShape> = z.infer<z.ZodObject<S>> & {
teamspace: string;
action: string;
};
export interface ToolDef<S extends z.ZodRawShape = z.ZodRawShape> {
name: string;
title: string;
description: string;
/** A plain tool has one kind; an action tool has one kind per `action` value. */
kind?: Kind;
actions?: Record<string, Kind>;
/** Only for write tools: a second identical call changes nothing more. */
idempotent?: boolean;
/** The result holds third-party text (questions, queries, feedback, logs, PR text). */
untrusted?: boolean;
/** `false` for the one tool that works across teamspaces. */
teamspace?: false;
args: S;
run(args: Args<S>, api: Api): Promise<unknown>;
}
function tool<S extends z.ZodRawShape>(def: ToolDef<S>): ToolDef {
return def as unknown as ToolDef;
}
/** One URL path segment. Rejects dot segments, which the URL parser would resolve. */
function seg(value: string): string {
if (!value || value === "." || value === "..") throw new ToolError(`Invalid id "${value}".`);
return encodeURIComponent(value);
}
/** The field of the management API's add body that holds each source's URL. */
const ADD_URL_FIELDS: Record<string, string | undefined> = {
github: "docsRepoUrl",
gitlab: "docsRepoUrl",
bitbucket: "docsRepoUrl",
git: "docsRepoUrl",
website: "websiteUrl",
llmstxt: "llmstxtUrl",
openapi: "openApiUrl",
};
const ts = (id: string) => `/v2/teamspaces/${seg(id)}`;
/**
* A library id as Context7 stores it: `/owner/repo`, lowercase. Also takes
* `owner/repo` and a context7.com library URL, which agents often pass.
*/
export function normalizeLibraryId(value: string): string {
const path = value
.trim()
.replace(/^https?:\/\/(?:www\.)?context7\.com/i, "")
.replace(/\/+$/, "");
const id = (path.startsWith("/") ? path : `/${path}`).toLowerCase();
if (!/^\/[^/]+\/[^/]+$/.test(id)) {
throw new ToolError(
`"${value}" is not a library id. Use one like "/owner/repo" (from list_libraries).`
);
}
return id;
}
function lib(teamspace: string, libraryId: string): string {
const [, owner, repo] = normalizeLibraryId(libraryId).split("/");
return `${ts(teamspace)}/libraries/${seg(owner)}/${seg(repo)}`;
}
/**
* Calls `fetchOnce` until `isDone` holds or about 25 seconds pass, so an agent
* waits for a parse, build or crawl in one tool call instead of polling.
* Gives the last answer either way; its state says whether the job finished.
*/
export async function poll(
fetchOnce: () => Promise<unknown>,
isDone: (value: unknown) => boolean,
{ timeoutMs = 25_000, intervalMs = 3_000 }: { timeoutMs?: number; intervalMs?: number } = {}
): Promise<unknown> {
const deadline = Date.now() + timeoutMs;
let value = await fetchOnce();
while (!isDone(value) && Date.now() + intervalMs < deadline) {
await new Promise((resolve) => setTimeout(resolve, intervalMs));
value = await fetchOnce();
}
return value;
}
const wait = z
.boolean()
.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 };
};
/** The agents whose runs each agent-runs history holds. */
const HISTORY_AGENTS = {
improve: ["context7", "buildFix"],
review: ["prReview"],
watch: ["codeWatch"],
} as const;
type AgentHistory = keyof typeof HISTORY_AGENTS;
/** The most runs the agent-runs route gives per history. */
export const AGENT_HISTORY_LIMIT = 50;
/**
* 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. When a full history
* starts inside the month, older runs of the month are not read: its agents
* are named in `minimumCounts`.
*/
export function agentActivity(
histories: Record<AgentHistory, AgentRun[]>,
now = new Date()
): Record<string, unknown> {
const monthStart = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1);
const inMonth = (run: AgentRun) =>
typeof run.createdAt === "string" && Date.parse(run.createdAt) >= monthStart;
const minimumCounts = new Set<string>();
for (const history of Object.keys(HISTORY_AGENTS) as AgentHistory[]) {
const list = histories[history];
if (list.length >= AGENT_HISTORY_LIMIT && list.every(inMonth)) {
// An agent can be missing from the window and still have older runs this month.
for (const agent of HISTORY_AGENTS[history]) minimumCounts.add(agent);
}
}
const runs: Record<string, number> = {};
const failedRuns: Record<string, number> = {};
const pullRequests: Record<string, Record<string, number>> = {};
for (const run of Object.values(histories).flat()) {
if (run.state === "superseded" || !inMonth(run)) 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,
minimumCounts: minimumCounts.size ? [...minimumCounts] : undefined,
};
}
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";
}
/** The `state` (or `indexStatus.kind`) of a result, read through a `{ data }` envelope. */
function stateOf(value: unknown, key: "state" | "indexStatus"): unknown {
const record = data(value);
return key === "state" ? record.state : (record.indexStatus as { kind?: unknown })?.kind;
}
const site = (teamspace: string, siteId: string) => `${ts(teamspace)}/sites/${seg(siteId)}`;
const askSite = (teamspace: string, siteKey: string) =>
`${ts(teamspace)}/ask-sites/${seg(siteKey)}`;
function need<T>(value: T | undefined | null, message: string): T {
if (value === undefined || value === null || value === "") throw new ToolError(message);
return value;
}
function confirmed(confirm: string | undefined, expected: string, what: string): void {
if (!expected) throw new ToolError(`Could not read ${what} from the API. Nothing was deleted.`);
if (confirm !== expected) {
throw new ToolError(
`Refused: \`confirm\` does not match ${what}. Ask the user to confirm this deletion. Then call again with \`confirm\` set to ${what}.`
);
}
}
/** `data` of a `{ data }` envelope, else the body itself. */
function data(body: unknown): Record<string, unknown> {
const value =
body && typeof body === "object" && "data" in body ? (body as { data: unknown }).data : body;
return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
}
/**
* The library a rule belongs to, or null for a teamspace rule: as given, else
* looked up in the rule list, since the API finds a library rule only by both ids.
*/
async function ruleLibrary(
api: Api,
base: string,
ruleId: string,
given: string | undefined
): Promise<string | null> {
if (given) return normalizeLibraryId(given);
const { libraries = {} } = data(await api.get(base)) as {
libraries?: Record<string, Record<string, unknown>>;
};
return Object.keys(libraries).find((library) => ruleId in libraries[library]) ?? null;
}
/** The filter mode a library request's list works in: allow lists are `select`, the rest `quality`. */
function requestMode(requestType: unknown): "select" | "quality" {
return requestType === "allow" || requestType === "unallow" ? "select" : "quality";
}
/** The email of the member with this id, from `GET /members` (`{ members, invitations }`). */
function memberEmail(body: unknown, memberId: string): string | undefined {
const { members } = (body ?? {}) as { members?: { id?: unknown; email?: unknown }[] };
const email = members?.find((member) => member.id === memberId)?.email;
return typeof email === "string" ? email : undefined;
}
const libraryId = z
.string()
.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",
]);
const LIST_OPERATION = z.union([
z.object({ add: z.array(z.string()).optional(), remove: z.array(z.string()).optional() }),
z.object({ clear: z.literal(true) }),
]);
const SITE_REPORTS = {
visitors: "humans",
ai_crawlers: "ai-crawlers",
top_ai_paths: "top-paths",
ai_requests: "recent-requests",
queries: "queries",
feedback: "feedback",
} as const;
export const TOOLS: ToolDef[] = [
// ---------- account ----------
tool({
name: "list_teamspaces",
title: "List teamspaces",
description:
"List the teamspaces of the user, with role and plan. Call this first to get the `teamspace` id that the other tools take.",
kind: "read",
teamspace: false,
args: {},
run: (_args, api) => api.get("/v2/teamspaces"),
}),
tool({
name: "get_teamspace",
title: "Get teamspace",
description:
"Get one teamspace: name, your role, owner plan, billing model, Docs7 Pro, and the monthly spending cap with this month's spend.",
kind: "read",
args: {},
run: async ({ teamspace }, api) => {
const [details, spendingLimit] = await Promise.all([
api.get(ts(teamspace)),
api.get(`${ts(teamspace)}/spending-limit`),
]);
return { teamspace: details, spendingLimit };
},
}),
tool({
name: "manage_members",
title: "Manage members",
description:
"List members and pending invitations, invite a member, change a role, remove a member, or cancel an invitation. Only an owner or admin can make changes. `remove` needs `confirm` set to the member's email, after the user confirms.",
actions: {
list: "read",
invite: "write",
update_role: "write",
remove: "destructive",
cancel_invitation: "write",
},
args: {
email: z.string().optional().describe("Email to invite (invite)."),
role: z.enum(["admin", "developer"]).optional().describe("Role (invite, update_role)."),
member_id: z.string().optional().describe("Member id from list (update_role, remove)."),
invitation_id: z.string().optional().describe("Invitation id from list (cancel_invitation)."),
confirm: z
.string()
.optional()
.describe("The member's email, after the user confirms the removal (remove)."),
},
run: async (args, api) => {
const base = ts(args.teamspace);
switch (args.action) {
case "list":
return api.get(`${base}/members`);
case "invite":
return api.post(`${base}/members`, {
email: need(args.email, "`email` is required to invite."),
role: need(args.role, "`role` is required to invite."),
});
case "update_role":
return api.patch(
`${base}/members/${seg(need(args.member_id, "`member_id` is required."))}`,
{ role: need(args.role, "`role` is required.") }
);
case "remove": {
const id = need(args.member_id, "`member_id` is required.");
const email = memberEmail(await api.get(`${base}/members`), id);
if (!email) throw new ToolError(`No member with id "${id}". Call action list first.`);
confirmed(args.confirm, email, "the member's email");
return api.del(`${base}/members/${seg(id)}`);
}
default:
return api.del(
`${base}/invitations/${seg(need(args.invitation_id, "`invitation_id` is required."))}`
);
}
},
}),
// ---------- libraries ----------
tool({
name: "list_libraries",
title: "List libraries",
description: "List the private and owned libraries of the teamspace, with their parse state.",
kind: "read",
args: {},
run: ({ teamspace }, api) => api.get(`${ts(teamspace)}/libraries`),
}),
tool({
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, 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) => {
const path = lib(teamspace, library_id);
return wait
? poll(
() => api.get(path),
(value) => ["complete", "error"].includes(stateOf(value, "state") as string)
)
: api.get(path);
},
}),
tool({
name: "add_library",
title: "Add library",
description:
"Add a library to the teamspace from a repository, website, llms.txt or OpenAPI URL. The parse takes minutes: then call get_library with the library id from the answer and `wait: true`. A private repository needs the GitHub, GitLab or Bitbucket account connected in the dashboard. Confluence, Notion and file uploads are added in the dashboard.",
kind: "write",
args: {
source: z
.enum(["github", "gitlab", "bitbucket", "git", "website", "llmstxt", "openapi"])
.describe("`git` is any other Git host."),
url: z.string().describe("Repository, documentation website, llms.txt or OpenAPI spec URL."),
private: z
.boolean()
.optional()
.describe("Add a repository as a private source (owner or admin, paid plan)."),
website_base_url: z
.string()
.optional()
.describe("Websites only: crawl only pages under this URL."),
generate_docs: z
.boolean()
.optional()
.describe("Private repositories only: generate docs from the source code."),
},
run: ({ teamspace, source, url, private: isPrivate, website_base_url, generate_docs }, api) =>
api.post(`${ts(teamspace)}/libraries`, {
source,
[ADD_URL_FIELDS[source]!]: url,
private: isPrivate,
websiteBaseUrl: website_base_url,
generateDocs: generate_docs,
}),
}),
tool({
name: "refresh_library",
title: "Refresh library",
description:
"Start a refresh of a library (the daily refresh limit applies). Then call get_library with `wait: true`.",
kind: "write",
args: { library_id: libraryId },
run: ({ teamspace, library_id }, api) => api.post(`${lib(teamspace, library_id)}/refresh`),
}),
tool({
name: "update_library_config",
title: "Update library config",
description:
"Change the settings of a library the teamspace owns. Send only the fields to change. A new title or description of a public library is reviewed before it shows. Returns the saved config. Refresh the library to apply parse settings.",
kind: "write",
idempotent: true,
args: {
library_id: libraryId,
title: z.string().max(100).optional(),
description: z.string().max(500).optional(),
branch: z.string().max(100).optional().describe("Branch to parse (repositories)."),
folders: z.array(z.string()).max(50).optional().describe("Parse only these folders."),
exclude_folders: z.array(z.string()).max(50).optional(),
exclude_files: z.array(z.string()).max(100).optional(),
rules: z
.array(z.string().max(255))
.max(50)
.optional()
.describe("Rules shown to agents with this library's docs."),
base_url: z.string().optional().describe("Websites: the base URL to crawl."),
web_url: z.string().optional().describe("Link shown on the library page."),
exclude_urls: z
.array(z.string())
.max(100)
.optional()
.describe("Websites: URLs not to crawl."),
use_query_params: z.boolean().optional().describe("Websites: keep query parameters."),
keep_version_specific_pages: z
.boolean()
.optional()
.describe("Keep pages that look specific to one version."),
stop_indexing: z.boolean().optional().describe("Stop indexing the library."),
config_source: z
.enum(["dashboard", "context7json"])
.optional()
.describe("Read settings from these fields, or from the repository's context7.json."),
},
run: ({ teamspace, library_id, ...fields }, api) =>
api.patch(lib(teamspace, library_id), {
projectTitle: fields.title,
description: fields.description,
branch: fields.branch,
folders: fields.folders,
excludeFolders: fields.exclude_folders,
excludeFiles: fields.exclude_files,
rules: fields.rules,
baseUrl: fields.base_url,
webUrl: fields.web_url,
excludeUrls: fields.exclude_urls,
useQueryParams: fields.use_query_params,
skipClaudeVersionExclusion: fields.keep_version_specific_pages,
disallow: fields.stop_indexing,
configSource: fields.config_source,
}),
}),
tool({
name: "manage_library_versions",
title: "Manage library versions",
description:
"Add or remove a version (a tag or branch) of a library. After `add`, call get_library with `wait: true`. `remove` needs `confirm` set to the version name, after the user confirms.",
actions: { add: "write", remove: "destructive" },
args: {
library_id: libraryId,
version: z.string().describe("Tag or branch name."),
is_branch: z
.boolean()
.optional()
.describe(
"`version` is a branch, not a tag (add). For remove, set it when a tag and a branch share the name."
),
confirm: z
.string()
.optional()
.describe("The version name, after the user confirms the removal (remove)."),
},
run: ({ teamspace, action, library_id, version, is_branch, confirm }, api) => {
const base = `${lib(teamspace, library_id)}/versions`;
if (action === "add") return api.post(base, { version, isBranch: is_branch });
confirmed(confirm, version, "the version name");
return api.del(`${base}/${seg(version)}`, { query: { isBranch: is_branch } });
},
}),
tool({
name: "claim_library",
title: "Claim library",
description:
"Claim ownership of a library for the teamspace. Without `verify`, get the context7.json content and where it goes: for a repository, commit it to the repository root on the default branch and push; for a website, llms.txt or OpenAPI library, host it under the returned `hostUnder` URL. Then call again with `verify: true`.",
kind: "write",
idempotent: true,
args: {
library_id: libraryId,
verify: z.boolean().optional().describe("true after context7.json is published."),
context7_json_url: z
.string()
.optional()
.describe(
"Where context7.json is hosted (verify). Required for websites, llms.txt and OpenAPI, and for repositories off GitHub, GitLab and Bitbucket."
),
},
run: ({ teamspace, library_id, verify, context7_json_url }, api) => {
const path = `${lib(teamspace, library_id)}/claim`;
return verify
? api.post(path, context7_json_url ? { context7JsonUrl: context7_json_url } : {})
: api.get(path);
},
}),
tool({
name: "remove_library",
title: "Remove library",
description:
"Remove a private library, or give up ownership of a claimed library. Ask the user to confirm first, then set `confirm` to the library id.",
kind: "destructive",
args: {
library_id: libraryId,
confirm: z.string().describe("The library id, after the user confirms."),
},
run: ({ teamspace, library_id, confirm }, api) => {
const id = normalizeLibraryId(library_id);
// "owner/repo" and "/Owner/Repo" confirm the same library as "/owner/repo".
const said = confirm.trim().replace(/^\/?/, "/").toLowerCase();
confirmed(said, id, "the library id");
return api.del(lib(teamspace, library_id));
},
}),
tool({
name: "get_library_analytics",
title: "Get library analytics",
description:
"Get usage analytics of a library the teamspace owns: calls, topics, countries or clients.",
kind: "read",
untrusted: true,
args: {
library_id: libraryId,
report: z.enum(["usage", "topics", "countries", "clients"]),
days: z
.number()
.int()
.min(1)
.max(365)
.optional()
.describe("Window in days (usage and clients only). Default 30."),
},
run: ({ teamspace, library_id, report, days }, api) =>
api.get(`${lib(teamspace, library_id)}/analytics`, { report, days }),
}),
tool({
name: "get_library_suggestions",
title: "Get library suggestions",
description:
"Get the suggestions for a library the teamspace owns: questions its docs answered badly in Context7's benchmark, with what to add and the doc files to change. Use them to improve the docs in the repository. For a Docs7 site, its library id is in docs7_get_site.",
kind: "read",
untrusted: true,
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({
name: "manage_rules",
title: "Manage rules",
description:
"List, create, update or delete the rules that Context7 adds to answers, for the whole teamspace or for one library. `list` gives all rules: `global` (teamspace rules) and `libraries` (rules by library id), each keyed by rule id. Changes need a paid plan. `delete` needs `confirm` set to the rule id, after the user confirms.",
actions: { list: "read", create: "write", update: "write", delete: "destructive" },
args: {
rule_id: z.string().optional().describe("Rule id from list (update, delete)."),
text: z.string().max(1000).optional().describe("Rule text (create, update)."),
library_id: z
.string()
.optional()
.describe(
"Library id of a library rule (create). Leave out for a teamspace rule. Update and delete find the rule's library from `rule_id`."
),
confirm: z
.string()
.optional()
.describe("The rule id, after the user confirms the deletion (delete)."),
},
// 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 data(await api.get(base));
case "create":
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 data(
await api.patch(`${base}/${ruleId()}`, {
text: need(args.text, "`text` is required."),
libraryId: await ruleLibrary(api, base, args.rule_id!, args.library_id),
})
);
default: {
confirmed(args.confirm, need(args.rule_id, "`rule_id` is required."), "the rule id");
const libraryId = await ruleLibrary(api, base, args.rule_id!, args.library_id);
return data(
await api.del(`${base}/${ruleId()}`, { query: { libraryId: libraryId ?? undefined } })
);
}
}
},
}),
tool({
name: "get_library_policies",
title: "Get policies",
description: "Get the library filters (policies) of the teamspace.",
kind: "read",
args: {},
run: ({ teamspace }, api) => api.get(`${ts(teamspace)}/policies`),
}),
tool({
name: "update_library_policies",
title: "Update policies",
description:
'Change which libraries the teamspace can use (owner or admin). Send changes as operations, not the get_library_policies shape. Each list takes { add: [...] }, { remove: [...] } or { clear: true }; library entries are "/org/repo", "/org" or a domain. Use `dry_run: true` first to see how many libraries the change leaves.',
kind: "write",
idempotent: true,
args: {
source_types: z
.object({
enable: z.array(SOURCE_TYPE).optional(),
disable: z.array(SOURCE_TYPE).optional(),
})
.optional(),
library_filters: z
.object({
mode: z
.enum(["quality", "select"])
.nullable()
.optional()
.describe(
"quality: filter by the rules below; select: only allowed libraries; null: off."
),
quality: z
.object({
requireVerified: z.boolean().optional(),
minTrustScore: z.number().int().min(0).max(10).nullable().optional(),
maxAgeDays: z.number().int().min(1).nullable().optional(),
blockedLibraries: LIST_OPERATION.optional(),
exceptedLibraries: LIST_OPERATION.optional(),
repoFilters: z
.object({
minStars: z.number().int().min(0).nullable().optional(),
allowedLicenses: LIST_OPERATION.optional(),
})
.optional(),
websiteFilters: z
.object({
minBacklinks: z.number().int().min(0).nullable().optional(),
minReferringDomains: z.number().int().min(0).nullable().optional(),
minOrganicTraffic: z.number().int().min(0).nullable().optional(),
})
.optional(),
})
.optional(),
select: z.object({ allowedLibraries: LIST_OPERATION.optional() }).optional(),
})
.optional(),
dry_run: z.boolean().optional().describe("Preview the change and its library count."),
},
run: async ({ teamspace, source_types, library_filters, dry_run }, api) => {
if (!source_types && !library_filters) {
throw new ToolError("Send `source_types` or `library_filters`.");
}
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): the saved rules have no effect until `library_filters.mode` is "quality" or "select".',
};
}
return result;
},
}),
tool({
name: "manage_library_requests",
title: "Manage library requests",
description:
"List, create, approve or dismiss requests from members to allow or block a library.",
actions: { list: "read", request: "write", approve: "write", dismiss: "write" },
args: {
library: z
.string()
.optional()
.describe(
'Library such as "/org/repo" or "/org", or a domain such as "stripe.com" (request).'
),
request_type: z
.enum(["allow", "block", "unallow", "unblock", "except", "unexcept"])
.optional()
.describe("What to request (request)."),
request_id: z.string().optional().describe("Request id from list (approve, dismiss)."),
},
run: async (args, api) => {
const base = `${ts(args.teamspace)}/library-requests`;
const requestId = () => seg(need(args.request_id, "`request_id` is required."));
switch (args.action) {
case "list":
return api.get(base);
case "request":
return api.post(base, {
libraryIdentifier: need(args.library, "`library` is required."),
requestType: need(args.request_type, "`request_type` is required."),
});
case "approve": {
// Approval edits a list, never the mode, so the mode is read first: a
// rejected credential then stops the call before anything is written.
const policies = (await api
.get(`${ts(args.teamspace)}/policies`)
.then(data)
.catch((error: unknown) => {
if (error instanceof Error && "status" in error && error.status === 401) throw error;
return null;
})) as { libraryFilters?: { mode?: unknown } } | null;
const approved = await api.post(`${base}/${requestId()}/approve`);
// The list applies only in its own filter mode.
const mode = requestMode(data(approved).requestType);
if (policies?.libraryFilters?.mode === mode) return approved;
if (!policies) {
return {
...data(approved),
note: `Approved. Could not read the policies to check that library filters are in "${mode}" mode; the list has no effect in another mode. Check with get_library_policies, and ask the user before you change the mode.`,
};
}
return {
...data(approved),
note: `Saved in the policy list, but library filters are not in "${mode}" mode, so it has no effect yet. Ask the user before you call update_library_policies with \`library_filters.mode: "${mode}"\`: that mode changes which libraries the whole teamspace can use (try \`dry_run: true\` first).`,
};
}
default:
return api.del(`${base}/${requestId()}`);
}
},
}),
// ---------- usage ----------
tool({
name: "get_teamspace_usage",
title: "Get usage",
description: "Get daily usage and cost, the quota and the credit of the teamspace.",
kind: "read",
args: {},
run: ({ teamspace }, api) => api.get(`${ts(teamspace)}/usage`),
}),
tool({
name: "set_spending_limit",
title: "Set spending limit",
description: "Set or remove the monthly spending cap (owner or admin).",
kind: "write",
idempotent: true,
args: {
limit_cents: z
.number()
.int()
.min(0)
.max(10_000_000)
.nullable()
.describe("Monthly cap in US cents, up to 10,000,000. null removes the cap."),
},
run: ({ teamspace, limit_cents }, api) =>
api.put(`${ts(teamspace)}/spending-limit`, { limitCents: limit_cents }),
}),
// ---------- docs7 ----------
tool({
name: "docs7_list_sites",
title: "List Docs7 sites",
description:
"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: 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, 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 = data(await api.get(path));
// A CLI site has no agent, and its agent-usage route answers 404.
if (details.source === "local") return { site: siteDetails(details) };
const readHistory = async (history: AgentHistory) =>
(
(await api.get(`${path}/agent-runs`, { history, limit: AGENT_HISTORY_LIMIT })) as {
data?: AgentRun[];
}
)?.data ?? [];
const [usage, improve, review, watch] = await Promise.all([
api.get(`${path}/agent-usage`),
readHistory("improve"),
readHistory("review"),
readHistory("watch"),
]);
const activity = agentActivity({ improve, review, watch });
return { site: siteDetails(details), agentUsage: { ...data(usage), ...activity } };
},
}),
tool({
name: "docs7_create_site",
title: "Create Docs7 site",
description:
"Add a Docs7 site from a GitHub repository. The Docs7 GitHub app must be installed on the repository (the user does this in the dashboard). A repository without docs.json or mint.json becomes an agent-only site, which is not published. Gives the site and the first build's `deploymentId` (null when no build started): call docs7_get_deployment with it and `wait: true`.",
kind: "write",
args: {
repo_url: z.string().describe("https://github.com/owner/repo"),
docs_path: z
.string()
.describe('Relative path of the docs folder, such as "docs", or "." for the root.'),
branch: z.string().optional().describe("Branch to build. Default: the repository default."),
slug: z
.string()
.optional()
.describe("First label of the <slug>.docs7.io hostname. Owner or admin only."),
custom_domain: z.string().optional().describe("Owner or admin only. Needs routing."),
custom_domain_path: z
.string()
.optional()
.describe("Path on the custom domain. Required for proxy routing."),
custom_domain_routing: z.enum(["dns", "proxy"]).optional(),
context7_index: z.boolean().optional().describe("Also index the site in Context7."),
},
run: async (args, api) => {
const created = (await api.post(`${ts(args.teamspace)}/sites`, {
repoUrl: args.repo_url,
docsPath: args.docs_path,
branch: args.branch,
slug: args.slug,
customDomain: args.custom_domain,
customDomainPath: args.custom_domain_path,
customDomainRouting: args.custom_domain_routing,
context7Index: args.context7_index,
})) as { data?: Record<string, unknown>; deploymentId?: unknown };
return { site: siteDetails(data(created)), deploymentId: created?.deploymentId ?? null };
},
}),
tool({
name: "docs7_update_site",
title: "Update Docs7 site",
description:
'Change a Docs7 site. Send only the fields to change. A developer can only send `hosting: "on"`, which publishes an agent-only site. After a custom domain change, call docs7_check_domain.',
kind: "write",
idempotent: true,
args: {
site_id: siteId,
slug: z.string().optional().describe("First label of the <slug>.docs7.io hostname."),
branch: z.string().nullable().optional().describe("Branch to build; null: the default."),
docs_path: z.string().optional(),
custom_domain: z.string().nullable().optional().describe("null removes the domain."),
custom_domain_path: z.string().nullable().optional(),
custom_domain_routing: z.enum(["dns", "proxy"]).nullable().optional(),
hosting: z.literal("on").optional().describe("Publish an agent-only site. One-way."),
context7_index: z.boolean().optional().describe("Keep the site's library on Context7."),
improve_schedule: z
.enum(["off", "daily", "weekly"])
.optional()
.describe("How often the Context7 Agent turns reader suggestions into a pull request."),
build_fix_schedule: z
.enum(["off", "after_build", "daily", "weekly"])
.optional()
.describe("When the Build Fix Agent fixes the issues of the latest production build."),
analytics_url: z
.string()
.nullable()
.optional()
.describe("Docs URL of a site not hosted here."),
pull_request_review: z
.object({
enabled: z.boolean(),
response: z
.enum(["comment", "pull_request", "commit"])
.describe("What to do with fixes; the findings comment is always posted."),
})
.optional()
.describe("PR Review Agent settings. Every check always runs."),
code_watch: z
.object({
enabled: z.boolean(),
repositories: z.array(z.string()).max(50).describe("https repository URLs."),
})
.optional()
.describe("All Code Watch settings: the full list of watched repositories."),
},
run: async ({ teamspace, site_id, ...fields }, api) => {
const updated = await api.patch(site(teamspace, site_id), {
slug: fields.slug,
branch: fields.branch,
docsPath: fields.docs_path,
customDomain: fields.custom_domain,
customDomainPath: fields.custom_domain_path,
customDomainRouting: fields.custom_domain_routing,
hosting: fields.hosting,
context7Index: fields.context7_index,
improveSchedule: fields.improve_schedule,
buildFixSchedule: fields.build_fix_schedule,
analyticsUrl: fields.analytics_url,
pullRequestReview: fields.pull_request_review,
codeWatch: fields.code_watch,
});
return { site: siteDetails(data(updated)) };
},
}),
tool({
name: "docs7_check_domain",
title: "Check custom domain",
description:
"Check the custom domain of a Docs7 site again. Gives its status and the DNS records to add.",
kind: "write",
idempotent: true,
args: { site_id: siteId },
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",
title: "List deployments",
description:
"List the builds of a Docs7 site, newest first, and its preview targets. Works for GitHub and CLI sites.",
kind: "read",
untrusted: true,
args: {
site_id: siteId,
page: z
.number()
.int()
.min(0)
.optional()
.describe("Zero-based page (GitHub sites). Default 0."),
},
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.
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({
name: "docs7_get_deployment",
title: "Get deployment",
description:
'Get one build of a Docs7 site (queued, building, succeeded, failed or canceled). After docs7_deploy, call it with `wait: true` until it ends. For a failed build, add `include: ["health", "logs"]` (CLI sites have logs only).',
kind: "read",
untrusted: true,
args: {
site_id: siteId,
deployment_id: z.string(),
include: z.array(z.enum(["logs", "health", "origin"])).optional(),
wait,
},
run: async ({ teamspace, site_id, deployment_id, include: requested = [], wait }, api) => {
const include = [...new Set(requested)];
const sitePath = site(teamspace, site_id);
const path = `${sitePath}/deployments/${seg(deployment_id)}`;
const cli = await isCliSite(api, sitePath);
if (cli && include.some((part) => part !== "logs")) {
throw new ToolError('A CLI site has build logs only. Use `include: ["logs"]`.');
}
const once = cli
? async () => {
const { deployments = [] } = data(await api.get(`${sitePath}/local-deployments`)) as {
deployments?: { id?: unknown }[];
};
const found = deployments.find((deployment) => deployment.id === deployment_id);
if (!found)
throw new ToolError(`No build "${deployment_id}". Call docs7_list_deployments.`);
return { data: found };
}
: () => api.get(path);
const deployment = wait
? await poll(once, (value) =>
["succeeded", "failed", "canceled"].includes(stateOf(value, "state") as string)
)
: await once();
const parts = await Promise.all(include.map((part) => api.get(`${path}/${part}`)));
return Object.fromEntries([
["deployment", deploymentView(data(deployment))],
...include.map((part, index) => [part, parts[index]]),
]);
},
}),
tool({
name: "docs7_deploy",
title: "Deploy Docs7 site",
description:
"Deploy a Docs7 site to production, or deploy a preview of a branch. Gives a deployment id: then call docs7_get_deployment with `wait: true`.",
kind: "write",
args: {
site_id: siteId,
branch: z
.string()
.optional()
.describe("Deploy a preview of this branch. Leave out for production."),
},
run: ({ teamspace, site_id, branch }, api) =>
api.post(
`${site(teamspace, site_id)}/deployments`,
branch ? { kind: "preview", branch } : { kind: "production" }
),
}),
tool({
name: "docs7_remove_preview",
title: "Remove preview",
description:
"Remove the preview of a branch from a Docs7 site. Ask the user to confirm first, then set `confirm` to the branch name.",
kind: "destructive",
args: {
site_id: siteId,
branch: z.string(),
confirm: z.string().describe("The branch name, after the user confirms."),
},
run: ({ teamspace, site_id, branch, confirm }, api) => {
confirmed(confirm, branch, "the branch name");
return api.del(`${site(teamspace, site_id)}/previews`, { query: { branch } });
},
}),
tool({
name: "docs7_get_agent_runs",
title: "Get agent runs",
description:
"Get the agent run history of a Docs7 site, newest first: `improve` (Context7 Agent and Build Fix Agent), `review` (PR Review Agent) or `watch` (Code Watch Agent). Each run has its state (running, completed, failed or superseded) and its pull request. The agents run on their schedules (docs7_update_site); this server does not start them.",
kind: "read",
untrusted: true,
args: {
site_id: siteId,
history: z.enum(["improve", "review", "watch"]).optional().describe("Default improve."),
limit: z.number().int().min(1).max(50).optional().describe("Newest n runs."),
},
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",
title: "Manage feature requests",
description:
"List the feature requests readers and agents left on a Docs7 site, mark one shipped (with the page that answers it), or reopen it.",
actions: { list: "read", ship: "write", reopen: "write" },
untrusted: true,
args: {
site_id: siteId,
feature_request_id: z.string().optional().describe("Feature request id (ship, reopen)."),
docs_url: z.string().optional().describe("https page that answers the request (ship)."),
},
run: (args, api) => {
const base = `${site(args.teamspace, args.site_id)}/feature-requests`;
if (args.action === "list") return api.get(base);
const id = need(args.feature_request_id, "`feature_request_id` is required.");
return args.action === "ship"
? api.patch(base, { id, status: "shipped", docsUrl: args.docs_url ?? null })
: api.patch(base, { id, status: "requested" });
},
}),
tool({
name: "docs7_get_analytics",
title: "Get site analytics",
description:
"Get one analytics report of a Docs7 site. `queries` and `feedback` show what readers searched for and asked, so you can find doc gaps.",
kind: "read",
untrusted: true,
args: {
site_id: siteId,
report: z.enum(
Object.keys(SITE_REPORTS) as [keyof typeof SITE_REPORTS, ...(keyof typeof SITE_REPORTS)[]]
),
days: z
.number()
.int()
.min(1)
.max(90)
.optional()
.describe("Window in days, within the plan's history. Default 7."),
previews: z.boolean().optional().describe("Include branch preview traffic."),
},
run: ({ teamspace, site_id, report, days, previews }, api) =>
api.get(`${site(teamspace, site_id)}/analytics/${SITE_REPORTS[report]}`, {
days,
previews: previews ? "1" : undefined,
}),
}),
tool({
name: "docs7_query_logs",
title: "Query site logs",
description:
"Search the records of a Docs7 site: reader searches, assistant questions, AI requests or page views.",
kind: "read",
untrusted: true,
args: {
site_id: siteId,
dataset: z.enum(["searches", "questions", "ai-requests", "page-views"]),
days: z.number().int().min(1).max(90).optional().describe("Window in days. Default 7."),
search: z.string().max(512).optional(),
filters: z
.array(
z.object({
field: z.string(),
operator: z.enum([
"eq",
"neq",
"contains",
"notContains",
"startsWith",
"gt",
"gte",
"lt",
"lte",
]),
value: z.union([z.string(), z.number(), z.boolean()]),
})
)
.max(8)
.optional()
.describe(
"AND rules. Text fields (eq, neq, contains, notContains, startsWith): searches: query, path, source, language, version, country, host; questions: query, category, path, country, host; ai-requests: company, path, country, host, method; page-views: path, referrer, country, browser, os, device, host. Number field `turn` (questions; eq, neq, gt, gte, lt, lte). Boolean fields (eq only): `found` (searches), `verified` (ai-requests)."
),
group_by: z
.string()
.optional()
.describe(
"Field to group by. searches: query, path, source, country; questions: query, category, path, country; ai-requests: company, path, country, verified; page-views: path, referrer, country, device, browser, os."
),
order: z.enum(["newest", "oldest"]).optional(),
page: z.number().int().min(1).optional(),
previews: z.boolean().optional(),
},
run: async (args, api) => {
const to = new Date();
const from = new Date(to.getTime() - (args.days ?? 7) * 86_400_000);
const body = (await api.post(`${site(args.teamspace, args.site_id)}/analytics/explore`, {
previews: args.previews ?? false,
query: {
dataset: args.dataset,
from: from.toISOString(),
to: to.toISOString(),
search: args.search ?? "",
filters: args.filters ?? [],
groupBy: args.group_by ?? null,
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({
name: "docs7_get_conversation",
title: "Get conversation",
description:
"Get one recorded assistant conversation of a Docs7 site (`conversationId` of a `questions` row from docs7_query_logs).",
kind: "read",
untrusted: true,
args: {
site_id: siteId,
conversation_id: z.string(),
previews: z.boolean().optional(),
},
run: ({ teamspace, site_id, conversation_id, previews }, api) =>
api.post(`${site(teamspace, site_id)}/analytics/conversation`, {
conversationId: conversation_id,
previews: previews ?? false,
}),
}),
// ---------- ask ----------
tool({
name: "ask_list_sites",
title: "List Ask sites",
description: "List the Ask sites of the teamspace, with index status and limits.",
kind: "read",
args: {},
run: ({ teamspace }, api) => api.get(`${ts(teamspace)}/ask-sites`),
}),
tool({
name: "ask_get_site",
title: "Get Ask site",
description:
"Get one Ask site: verification, index status (pending, submitted, ready or failed) and the snippet to embed. After ask_verify_site, call it with `wait: true` until the index is ready or failed.",
kind: "read",
args: { site_key: siteKey, wait },
run: ({ teamspace, site_key, wait }, api) => {
const once = () => api.get(askSite(teamspace, site_key));
return wait
? poll(once, (value) =>
["ready", "failed"].includes(stateOf(value, "indexStatus") as string)
)
: once();
},
}),
tool({
name: "ask_create_site",
title: "Create Ask site",
description:
"Add an Ask site. Gives the meta tag (verificationTag) to put in the page <head>. Deploy the page with the tag, then call ask_verify_site.",
kind: "write",
args: { url: z.string().describe("Public https:// or http:// URL of the site.") },
run: ({ teamspace, url }, api) => api.post(`${ts(teamspace)}/ask-sites`, { url }),
}),
tool({
name: "ask_verify_site",
title: "Verify Ask site",
description:
"Check the meta tag of an Ask site and start the crawl. Then call ask_get_site with `wait: true`.",
kind: "write",
idempotent: true,
args: { site_key: siteKey },
run: ({ teamspace, site_key }, api) => api.post(`${askSite(teamspace, site_key)}/verify`),
}),
tool({
name: "ask_get_analytics",
title: "Get Ask analytics",
description:
"Get the analytics of an Ask site: questions over time, clients, unanswered questions (gaps) and top questions.",
kind: "read",
untrusted: true,
args: {
site_key: siteKey,
days: askDays.describe("Window in days. Default 30."),
},
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",
title: "List Ask questions",
description: "List the question log of an Ask site, or get one answer with `question_id`.",
kind: "read",
untrusted: true,
args: {
site_key: siteKey,
question_id: z.string().optional(),
page: z.number().int().min(0).optional().describe("Zero-based page."),
client: z
.enum([
"anthropic",
"openai",
"perplexity",
"cursor",
"opencode",
"meta",
"mistral",
"xai",
"browser",
"unknown",
])
.optional()
.describe("Only questions from this client."),
days: askDays.describe("Window in days."),
search: z.string().max(200).optional(),
answer: z.enum(["answered", "no_match"]).optional(),
},
run: ({ teamspace, site_key, question_id, ...query }, api) => {
const path = `${askSite(teamspace, site_key)}/questions`;
if (question_id) return api.get(`${path}/${seg(question_id)}`);
const { page, client, days, search, answer } = query;
return api.get(path, { page, client, days, search, answer });
},
}),
];