@ainyc/canonry 2.6.0 → 2.9.0

package/dist/mcp.js

@@ -3,11 +3,14 @@ import {
   competitorBatchRequestSchema,
   createApiClient,
   keywordBatchRequestSchema,
+  keywordGenerateRequestSchema,
   notificationCreateRequestSchema,
   notificationEventSchema,
+  projectConfigSchema,
+  projectUpsertRequestSchema,
   runTriggerRequestSchema,
   scheduleUpsertRequestSchema
-} from "./chunk-3DUTT6H2.js";
+} from "./chunk-FPZUQADO.js";
 import "./chunk-MLKGABMK.js";
 
 // src/mcp/cli.ts
@@ -15,6 +18,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z3 } from "zod";
 
 // src/package-version.ts
 import { createRequire } from "module";
@@ -146,10 +150,21 @@ var keywordsInputSchema = z2.object({
   project: projectNameSchema,
   request: keywordBatchRequestSchema
 });
-var competitorsAddInputSchema = z2.object({
+var keywordGenerateInputSchema = z2.object({
+  project: projectNameSchema,
+  request: keywordGenerateRequestSchema
+});
+var competitorsInputSchema = z2.object({
   project: projectNameSchema,
   request: competitorBatchRequestSchema
 });
+var projectUpsertInputSchema = z2.object({
+  project: projectNameSchema,
+  request: projectUpsertRequestSchema
+});
+var applyConfigInputSchema = z2.object({
+  config: projectConfigSchema
+});
 var scheduleSetInputSchema = z2.object({
   project: projectNameSchema,
   schedule: scheduleUpsertRequestSchema
@@ -170,6 +185,7 @@ var canonryMcpTools = [
     title: "List Canonry projects",
     description: "List all Canonry projects available through the configured API.",
     access: "read",
+    tier: "core",
     inputSchema: emptyInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects"],
@@ -180,6 +196,7 @@ var canonryMcpTools = [
     title: "Get project",
     description: "Get a Canonry project by name.",
     access: "read",
+    tier: "core",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}"],
@@ -190,6 +207,7 @@ var canonryMcpTools = [
     title: "Export project config",
     description: "Export a Canonry project in config-as-code format.",
     access: "read",
+    tier: "setup",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/export"],
@@ -200,6 +218,7 @@ var canonryMcpTools = [
     title: "Get project history",
     description: "Get audit history for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/history"],
@@ -210,6 +229,7 @@ var canonryMcpTools = [
     title: "List project runs",
     description: "List runs for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: runsListInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/runs"],
@@ -220,6 +240,7 @@ var canonryMcpTools = [
     title: "Get latest project run",
     description: "Get the latest run and total run count for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/runs/latest"],
@@ -230,6 +251,7 @@ var canonryMcpTools = [
     title: "Get run",
     description: "Get a Canonry run with its snapshots.",
     access: "read",
+    tier: "monitoring",
     inputSchema: runGetInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/runs/{id}"],
@@ -240,6 +262,7 @@ var canonryMcpTools = [
     title: "Get project timeline",
     description: "Get per-keyword citation history for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: timelineInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/timeline"],
@@ -250,6 +273,7 @@ var canonryMcpTools = [
     title: "List query snapshots",
     description: "List paginated query snapshots for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: snapshotsListInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/snapshots"],
@@ -264,6 +288,7 @@ var canonryMcpTools = [
     title: "Diff snapshots",
     description: "Compare query snapshot states between two Canonry runs.",
     access: "read",
+    tier: "monitoring",
     inputSchema: snapshotsDiffInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/snapshots/diff"],
@@ -274,6 +299,7 @@ var canonryMcpTools = [
     title: "List insights",
     description: "List intelligence insights for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: insightsListInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/insights"],
@@ -284,6 +310,7 @@ var canonryMcpTools = [
     title: "Get insight",
     description: "Get one intelligence insight for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: insightInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/insights/{id}"],
@@ -294,6 +321,7 @@ var canonryMcpTools = [
     title: "Get latest health",
     description: "Get the latest health snapshot for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/health/latest"],
@@ -304,6 +332,7 @@ var canonryMcpTools = [
     title: "Get health history",
     description: "Get health snapshot history for a Canonry project.",
     access: "read",
+    tier: "monitoring",
     inputSchema: healthHistoryInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/health/history"],
@@ -314,6 +343,7 @@ var canonryMcpTools = [
     title: "List keywords",
     description: "List tracked keywords for a Canonry project.",
     access: "read",
+    tier: "setup",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/keywords"],
@@ -324,6 +354,7 @@ var canonryMcpTools = [
     title: "List competitors",
     description: "List tracked competitors for a Canonry project.",
     access: "read",
+    tier: "setup",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/competitors"],
@@ -334,6 +365,7 @@ var canonryMcpTools = [
     title: "Get schedule",
     description: "Get the scheduled run configuration for a Canonry project.",
     access: "read",
+    tier: "setup",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/schedule"],
@@ -344,6 +376,7 @@ var canonryMcpTools = [
     title: "Get settings",
     description: "Get Canonry API settings and configured provider status.",
     access: "read",
+    tier: "core",
     inputSchema: emptyInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/settings"],
@@ -354,6 +387,7 @@ var canonryMcpTools = [
     title: "List Google connections",
     description: "List configured Google connections for a Canonry project.",
     access: "read",
+    tier: "gsc",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/google/connections"],
@@ -364,6 +398,7 @@ var canonryMcpTools = [
     title: "Get GSC performance",
     description: "Get stored Google Search Console performance rows for a Canonry project.",
     access: "read",
+    tier: "gsc",
     inputSchema: gscPerformanceInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/performance"],
@@ -374,6 +409,7 @@ var canonryMcpTools = [
     title: "List GSC inspections",
     description: "List stored URL inspection rows for a Canonry project.",
     access: "read",
+    tier: "gsc",
     inputSchema: gscInspectionsInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/inspections"],
@@ -384,6 +420,7 @@ var canonryMcpTools = [
     title: "List deindexed GSC URLs",
     description: "List URLs that appear to have become deindexed in Google Search Console data.",
     access: "read",
+    tier: "gsc",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/deindexed"],
@@ -394,6 +431,7 @@ var canonryMcpTools = [
     title: "Get GSC coverage",
     description: "Get Google Search Console coverage summary for a Canonry project.",
     access: "read",
+    tier: "gsc",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/coverage"],
@@ -404,6 +442,7 @@ var canonryMcpTools = [
     title: "Get GSC coverage history",
     description: "Get Google Search Console coverage history snapshots for a Canonry project.",
     access: "read",
+    tier: "gsc",
     inputSchema: gscCoverageHistoryInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/coverage/history"],
@@ -414,6 +453,7 @@ var canonryMcpTools = [
     title: "Get GSC sitemaps",
     description: "Get sitemap data from Google Search Console for a Canonry project.",
     access: "read",
+    tier: "gsc",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(true),
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/sitemaps"],
@@ -424,6 +464,7 @@ var canonryMcpTools = [
     title: "Get GA status",
     description: "Get Google Analytics connection status for a Canonry project.",
     access: "read",
+    tier: "ga",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/status"],
@@ -434,6 +475,7 @@ var canonryMcpTools = [
     title: "Get GA traffic",
     description: "Get Google Analytics traffic summary for a Canonry project.",
     access: "read",
+    tier: "ga",
     inputSchema: gaTrafficInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/traffic"],
@@ -444,6 +486,7 @@ var canonryMcpTools = [
     title: "Get GA coverage",
     description: "Get Google Analytics page coverage for a Canonry project.",
     access: "read",
+    tier: "ga",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/coverage"],
@@ -454,6 +497,7 @@ var canonryMcpTools = [
     title: "Get GA AI referral history",
     description: "Get AI referral sessions per day grouped by source.",
     access: "read",
+    tier: "ga",
     inputSchema: gaWindowInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/ai-referral-history"],
@@ -464,6 +508,7 @@ var canonryMcpTools = [
     title: "Get GA social referral history",
     description: "Get social referral sessions per day grouped by source.",
     access: "read",
+    tier: "ga",
     inputSchema: gaWindowInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/social-referral-history"],
@@ -474,6 +519,7 @@ var canonryMcpTools = [
     title: "Get GA social referral trend",
     description: "Get social referral trend with biggest mover for a Canonry project.",
     access: "read",
+    tier: "ga",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/social-referral-trend"],
@@ -484,6 +530,7 @@ var canonryMcpTools = [
     title: "Get GA attribution trend",
     description: "Get per-channel attribution trends for organic, AI, social, and total sessions.",
     access: "read",
+    tier: "ga",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/attribution-trend"],
@@ -494,16 +541,65 @@ var canonryMcpTools = [
     title: "Get GA session history",
     description: "Get total sessions per day for a Canonry project.",
     access: "read",
+    tier: "ga",
     inputSchema: gaWindowInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/ga/session-history"],
     handler: (client, input) => client.gaSessionHistory(input.project, compactStringParams(input, ["window"]))
   }),
+  defineTool({
+    name: "canonry_project_upsert",
+    title: "Create or replace project",
+    description: "Create or replace a Canonry project. PUT semantics \u2014 fields not in the request are reset to their defaults. Provide the full intended project shape.",
+    access: "write",
+    tier: "setup",
+    inputSchema: projectUpsertInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
+    openApiOperations: ["PUT /api/v1/projects/{name}"],
+    handler: (client, input) => client.putProject(input.project, input.request)
+  }),
+  defineTool({
+    name: "canonry_apply_config",
+    title: "Apply project config",
+    description: "Apply one Canonry config-as-code project document. Replaces the project to match the config \u2014 fields omitted from the spec are reset to defaults. For multi-document YAML, call this tool once per project document.",
+    access: "write",
+    tier: "core",
+    inputSchema: applyConfigInputSchema,
+    // Declarative apply is safe to repeat, but it replaces configured child state.
+    annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
+    openApiOperations: ["POST /api/v1/apply"],
+    handler: (client, input) => client.apply(input.config)
+  }),
+  defineTool({
+    name: "canonry_keywords_generate",
+    title: "Generate keyword suggestions",
+    description: "Generate candidate key phrases using a configured provider. Returns suggestions only; use canonry_keywords_add to persist them.",
+    access: "write",
+    tier: "setup",
+    inputSchema: keywordGenerateInputSchema,
+    annotations: writeAnnotations({ idempotentHint: false, openWorldHint: true }),
+    openApiOperations: ["POST /api/v1/projects/{name}/keywords/generate"],
+    handler: (client, input) => client.generateKeywords(input.project, input.request.provider, input.request.count)
+  }),
+  defineTool({
+    name: "canonry_keywords_replace",
+    title: "Replace keywords",
+    description: "Replace the tracked keyword set for a Canonry project.",
+    access: "write",
+    tier: "setup",
+    inputSchema: keywordsInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
+    openApiOperations: ["PUT /api/v1/projects/{name}/keywords"],
+    handler: async (client, input) => {
+      await client.putKeywords(input.project, uniqueStrings(input.request.keywords));
+    }
+  }),
   defineTool({
     name: "canonry_run_trigger",
     title: "Trigger run",
     description: "Trigger an answer-visibility run for a Canonry project.",
     access: "write",
+    tier: "core",
     inputSchema: runTriggerInputSchema,
     annotations: writeAnnotations({ idempotentHint: false, openWorldHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/runs"],
@@ -514,6 +610,7 @@ var canonryMcpTools = [
     title: "Cancel run",
     description: "Cancel a queued or running Canonry run.",
     access: "write",
+    tier: "core",
     inputSchema: runGetInputSchema,
     annotations: writeAnnotations({ idempotentHint: false, destructiveHint: true }),
     openApiOperations: ["POST /api/v1/runs/{id}/cancel"],
@@ -524,6 +621,7 @@ var canonryMcpTools = [
     title: "Add keywords",
     description: "Append tracked keywords to a Canonry project; existing keywords are skipped by the API.",
     access: "write",
+    tier: "setup",
     inputSchema: keywordsInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/keywords"],
@@ -536,6 +634,7 @@ var canonryMcpTools = [
     title: "Remove keywords",
     description: "Remove tracked keywords from a Canonry project.",
     access: "write",
+    tier: "setup",
     inputSchema: keywordsInputSchema,
     annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
     openApiOperations: ["DELETE /api/v1/projects/{name}/keywords"],
@@ -548,13 +647,25 @@ var canonryMcpTools = [
     title: "Add competitors",
     description: "Add tracked competitor domains to a Canonry project.",
     access: "write",
-    inputSchema: competitorsAddInputSchema,
+    tier: "setup",
+    inputSchema: competitorsInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
-    openApiOperations: ["GET /api/v1/projects/{name}/competitors", "PUT /api/v1/projects/{name}/competitors"],
+    openApiOperations: ["POST /api/v1/projects/{name}/competitors"],
+    handler: async (client, input) => {
+      await client.appendCompetitors(input.project, uniqueStrings(input.request.competitors));
+    }
+  }),
+  defineTool({
+    name: "canonry_competitors_remove",
+    title: "Remove competitors",
+    description: "Remove tracked competitor domains from a Canonry project.",
+    access: "write",
+    tier: "setup",
+    inputSchema: competitorsInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
+    openApiOperations: ["DELETE /api/v1/projects/{name}/competitors"],
     handler: async (client, input) => {
-      const existing = await client.listCompetitors(input.project);
-      const merged = uniqueStrings([...existing.map((c) => c.domain), ...input.request.competitors]);
-      await client.putCompetitors(input.project, merged);
+      await client.deleteCompetitors(input.project, uniqueStrings(input.request.competitors));
     }
   }),
   defineTool({
@@ -562,6 +673,7 @@ var canonryMcpTools = [
     title: "Set schedule",
     description: "Create or replace the scheduled run configuration for a Canonry project.",
     access: "write",
+    tier: "setup",
     inputSchema: scheduleSetInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["PUT /api/v1/projects/{name}/schedule"],
@@ -572,6 +684,7 @@ var canonryMcpTools = [
     title: "Delete schedule",
     description: "Delete the scheduled run configuration for a Canonry project.",
     access: "write",
+    tier: "setup",
     inputSchema: projectInputSchema,
     annotations: writeAnnotations({ idempotentHint: false, destructiveHint: true }),
     openApiOperations: ["DELETE /api/v1/projects/{name}/schedule"],
@@ -584,6 +697,7 @@ var canonryMcpTools = [
     title: "Dismiss insight",
     description: "Dismiss an intelligence insight for a Canonry project.",
     access: "write",
+    tier: "setup",
     inputSchema: insightInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/insights/{id}/dismiss"],
@@ -594,6 +708,7 @@ var canonryMcpTools = [
     title: "Attach agent webhook",
     description: "Attach an external agent webhook to project run and insight events.",
     access: "write",
+    tier: "core",
     inputSchema: agentWebhookAttachInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["GET /api/v1/projects/{name}/notifications", "POST /api/v1/projects/{name}/notifications"],
@@ -618,6 +733,7 @@ var canonryMcpTools = [
     title: "Detach agent webhook",
     description: "Detach the external agent webhook for a Canonry project.",
     access: "write",
+    tier: "agent",
     inputSchema: projectInputSchema,
     annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
     openApiOperations: ["GET /api/v1/projects/{name}/notifications", "DELETE /api/v1/projects/{name}/notifications/{id}"],
@@ -634,6 +750,7 @@ var canonryMcpTools = [
 ];
 var CANONRY_MCP_TOOL_COUNT = canonryMcpTools.length;
 var CANONRY_MCP_READ_TOOL_COUNT = canonryMcpTools.filter((tool) => tool.access === "read").length;
+var CANONRY_MCP_CORE_TOOL_COUNT = canonryMcpTools.filter((tool) => tool.tier === "core").length;
 
 // src/mcp/results.ts
 function jsonToolResult(value) {
@@ -705,8 +822,119 @@ function hasErrorEnvelope(value) {
   return Boolean(error && typeof error === "object");
 }
 
+// src/mcp/toolkits.ts
+var CANONRY_MCP_TOOLKIT_NAMES = ["monitoring", "setup", "gsc", "ga", "agent"];
+var CANONRY_MCP_TOOLKITS = [
+  {
+    name: "monitoring",
+    title: "Runs, snapshots, insights, health",
+    description: "Inspect run history, query snapshots, intelligence insights, and health timelines.",
+    whenToLoad: "Load when investigating regressions, comparing runs, or reviewing insights and health history."
+  },
+  {
+    name: "setup",
+    title: "Project configuration",
+    description: "Manage keywords, competitors, schedules, project upsert, and config-as-code roundtrips.",
+    whenToLoad: "Load when onboarding a new project or editing tracked keywords, competitors, or schedules."
+  },
+  {
+    name: "gsc",
+    title: "Google Search Console",
+    description: "Read GSC performance, inspections, coverage, sitemaps, and deindexed URLs.",
+    whenToLoad: "Load when you need indexing, coverage, or sitemap data from Google Search Console."
+  },
+  {
+    name: "ga",
+    title: "Google Analytics 4",
+    description: "Read GA traffic, AI/social referral history, attribution trend, and session history.",
+    whenToLoad: "Load when you need traffic, referral, or attribution data from Google Analytics 4."
+  },
+  {
+    name: "agent",
+    title: "Agent webhook lifecycle",
+    description: "Detach the configured external-agent webhook from a project.",
+    whenToLoad: "Load when removing an agent webhook subscription. (Attach lives in the core tier.)"
+  }
+];
+function isCanonryMcpToolkitName(value) {
+  return CANONRY_MCP_TOOLKIT_NAMES.includes(value);
+}
+
+// src/mcp/dynamic-catalog.ts
+var DynamicToolCatalog = class {
+  entries;
+  loaded = /* @__PURE__ */ new Set();
+  eager;
+  scope;
+  constructor(entries, scope, options = {}) {
+    this.entries = entries;
+    this.scope = scope;
+    this.eager = Boolean(options.eager);
+    if (this.eager) {
+      for (const toolkit of CANONRY_MCP_TOOLKITS) {
+        if (this.toolsForToolkit(toolkit.name).length > 0) {
+          this.loaded.add(toolkit.name);
+        }
+      }
+    }
+  }
+  applyInitialEnablement() {
+    if (this.eager) return;
+    for (const entry of this.entries) {
+      if (entry.tool.tier !== "core") entry.registered.disable();
+    }
+  }
+  loadToolkit(rawName) {
+    if (!isCanonryMcpToolkitName(rawName)) {
+      const valid = CANONRY_MCP_TOOLKITS.map((t) => t.name).join(", ");
+      throw new Error(`Unknown toolkit "${rawName}". Available: ${valid}.`);
+    }
+    const name = rawName;
+    const matches = this.entries.filter((entry) => entry.tool.tier === name);
+    if (matches.length === 0) {
+      return { status: "empty", name, tools: [] };
+    }
+    if (this.loaded.has(name)) {
+      return { status: "already-loaded", name, tools: matches.map((entry) => entry.tool.name) };
+    }
+    for (const entry of matches) {
+      entry.registered.enable();
+    }
+    this.loaded.add(name);
+    return { status: "loaded", name, tools: matches.map((entry) => entry.tool.name) };
+  }
+  helpResult() {
+    return {
+      scope: this.scope,
+      eager: this.eager,
+      loadedToolkits: [...this.loaded].sort(),
+      coreTools: this.entries.filter((entry) => entry.tool.tier === "core").map((entry) => entry.tool.name),
+      toolkits: CANONRY_MCP_TOOLKITS.map((toolkit) => this.toolkitEntry(toolkit)).filter((entry) => entry.toolCount > 0),
+      usage: "Call canonry_load_toolkit with one of the toolkit names listed in `toolkits[].name` to register its tools for the rest of this session."
+    };
+  }
+  toolkitEntry(toolkit) {
+    const tools = this.toolsForToolkit(toolkit.name);
+    return {
+      name: toolkit.name,
+      title: toolkit.title,
+      description: toolkit.description,
+      whenToLoad: toolkit.whenToLoad,
+      toolCount: tools.length,
+      tools,
+      loaded: this.loaded.has(toolkit.name)
+    };
+  }
+  toolsForToolkit(name) {
+    return this.entries.filter((entry) => entry.tool.tier === name).map((entry) => entry.tool.name);
+  }
+};
+
 // src/mcp/server.ts
 function createCanonryMcpServer(options = {}) {
+  return createCanonryMcpServerWithCatalog(options).server;
+}
+function createCanonryMcpServerWithCatalog(options = {}) {
   const clientFactory = options.clientFactory ?? createApiClient;
   const client = clientFactory();
   const scope = options.scope ?? "all";
@@ -714,10 +942,11 @@ function createCanonryMcpServer(options = {}) {
     name: "canonry",
     version: PACKAGE_VERSION
   });
+  const entries = [];
   for (const registryTool of getCanonryMcpTools(scope)) {
     const tool = registryTool;
     const handler = tool.handler;
-    server.registerTool(
+    const registered = server.registerTool(
       tool.name,
       {
         title: tool.title,
@@ -727,8 +956,36 @@ function createCanonryMcpServer(options = {}) {
       },
       async (input) => withToolErrors(() => handler(client, input))
     );
+    entries.push({ tool, registered });
   }
-  return server;
+  const catalog = new DynamicToolCatalog(entries, scope, { eager: options.eager });
+  catalog.applyInitialEnablement();
+  registerMetaTools(server, catalog);
+  return { server, catalog };
+}
+function registerMetaTools(server, catalog) {
+  server.registerTool(
+    "canonry_help",
+    {
+      title: "List Canonry MCP toolkits",
+      description: "List available toolkits and which are loaded. Call before canonry_load_toolkit if unsure which to load.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true }
+    },
+    async () => withToolErrors(async () => catalog.helpResult())
+  );
+  server.registerTool(
+    "canonry_load_toolkit",
+    {
+      title: "Load a Canonry MCP toolkit",
+      description: "Register a toolkit's tools for this session and emit notifications/tools/list_changed. Idempotent. Loaded toolkits remain loaded for the rest of the session.",
+      inputSchema: {
+        name: z3.enum(CANONRY_MCP_TOOLKIT_NAMES).describe("Toolkit name. List options with canonry_help.")
+      },
+      annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false }
+    },
+    async ({ name }) => withToolErrors(async () => catalog.loadToolkit(name))
+  );
 }
 function getCanonryMcpTools(scope = "all") {
   return scope === "read-only" ? canonryMcpTools.filter((tool) => tool.access === "read") : [...canonryMcpTools];
@@ -736,17 +993,23 @@ function getCanonryMcpTools(scope = "all") {
 
 // src/mcp/cli.ts
 async function main(argv = process.argv.slice(2)) {
-  const server = createCanonryMcpServer({ scope: parseScope(argv) });
+  const options = parseCliOptions(argv);
+  const server = createCanonryMcpServer({ scope: options.scope, eager: options.eager });
   await server.connect(new StdioServerTransport());
 }
-function parseScope(argv, envScope = process.env.CANONRY_MCP_SCOPE) {
-  let scope = normalizeScope(envScope);
+function parseCliOptions(argv, env = process.env) {
+  let scope = normalizeScope(env.CANONRY_MCP_SCOPE);
+  let eager = parseEagerEnv(env.CANONRY_MCP_EAGER);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--read-only") {
       scope = "read-only";
       continue;
     }
+    if (arg === "--eager") {
+      eager = true;
+      continue;
+    }
     if (arg === "--scope") {
       const next = argv[i + 1];
       if (!next) throw new Error("Missing value for --scope");
@@ -760,13 +1023,18 @@ function parseScope(argv, envScope = process.env.CANONRY_MCP_SCOPE) {
     }
     throw new Error(`Unknown canonry-mcp argument: ${arg}`);
   }
-  return scope;
+  return { scope, eager };
 }
 function normalizeScope(value) {
   if (!value || value === "all") return "all";
   if (value === "read-only") return "read-only";
   throw new Error(`Invalid MCP scope "${value}". Expected "all" or "read-only".`);
 }
+function parseEagerEnv(value) {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch((error) => {
     const message = error instanceof Error ? error.message : "canonry-mcp failed";
@@ -777,5 +1045,5 @@ if (import.meta.url === `file://${process.argv[1]}`) {
 }
 export {
   main,
-  parseScope
+  parseCliOptions
 };