@ainyc/canonry 2.8.2 → 2.10.1

package/dist/mcp.js

@@ -10,7 +10,7 @@ import {
   projectUpsertRequestSchema,
   runTriggerRequestSchema,
   scheduleUpsertRequestSchema
-} from "./chunk-FPZUQADO.js";
+} from "./chunk-KWQCQMPY.js";
 import "./chunk-MLKGABMK.js";
 
 // src/mcp/cli.ts
@@ -18,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";
@@ -184,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"],
@@ -194,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}"],
@@ -204,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"],
@@ -214,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"],
@@ -224,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"],
@@ -234,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"],
@@ -244,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}"],
@@ -254,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"],
@@ -264,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"],
@@ -278,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"],
@@ -288,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"],
@@ -298,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}"],
@@ -306,8 +319,9 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_health_latest",
     title: "Get latest health",
-    description: "Get the latest health snapshot for a Canonry project.",
+    description: 'Get the latest health snapshot for a Canonry project. Always returns a snapshot once the project exists: real data carries `status: "ready"`; newly-created projects (or projects with only failed runs) carry `status: "no-data"` with `reason: "no-runs-yet"` and zeroed metrics.',
     access: "read",
+    tier: "monitoring",
     inputSchema: projectInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/health/latest"],
@@ -318,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"],
@@ -328,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"],
@@ -338,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"],
@@ -348,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"],
@@ -358,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"],
@@ -368,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"],
@@ -378,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"],
@@ -388,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"],
@@ -398,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"],
@@ -408,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"],
@@ -418,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"],
@@ -428,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"],
@@ -438,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"],
@@ -448,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"],
@@ -458,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"],
@@ -468,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"],
@@ -478,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"],
@@ -488,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"],
@@ -498,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"],
@@ -508,6 +541,7 @@ 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"],
@@ -518,6 +552,7 @@ var canonryMcpTools = [
     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}"],
@@ -528,6 +563,7 @@ var canonryMcpTools = [
     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 }),
@@ -539,6 +575,7 @@ var canonryMcpTools = [
     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"],
@@ -549,6 +586,7 @@ var canonryMcpTools = [
     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"],
@@ -561,6 +599,7 @@ var canonryMcpTools = [
     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"],
@@ -571,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"],
@@ -581,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"],
@@ -593,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"],
@@ -605,6 +647,7 @@ var canonryMcpTools = [
     title: "Add competitors",
     description: "Add tracked competitor domains to a Canonry project.",
     access: "write",
+    tier: "setup",
     inputSchema: competitorsInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/competitors"],
@@ -617,6 +660,7 @@ var canonryMcpTools = [
     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"],
@@ -629,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"],
@@ -639,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"],
@@ -651,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"],
@@ -661,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"],
@@ -685,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}"],
@@ -701,8 +750,10 @@ 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
+import { ZodError } from "zod";
 function jsonToolResult(value) {
   const result = value === void 0 ? { ok: true } : value;
   return {
@@ -733,6 +784,15 @@ async function withToolErrors(handler) {
   }
 }
 function toCanonryErrorEnvelope(error) {
+  if (error instanceof ZodError) {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: zodErrorMessage(error),
+        details: { issues: error.issues.map(formatZodIssue) }
+      }
+    };
+  }
   if (error instanceof CliError) {
     return {
       error: {
@@ -771,9 +831,129 @@ function hasErrorEnvelope(value) {
   const error = value.error;
   return Boolean(error && typeof error === "object");
 }
+function formatZodIssue(issue) {
+  return { path: issue.path.map(String).join("."), message: issue.message };
+}
+function zodErrorMessage(error) {
+  const first = error.issues[0];
+  if (!first) return "Input validation failed";
+  const path = first.path.map(String).join(".");
+  return path ? `${path}: ${first.message}` : first.message;
+}
+
+// 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";
@@ -781,10 +961,12 @@ function createCanonryMcpServer(options = {}) {
     name: "canonry",
     version: PACKAGE_VERSION
   });
+  server.validateToolInput = async (_tool, args) => args;
+  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,
@@ -792,28 +974,103 @@ function createCanonryMcpServer(options = {}) {
         inputSchema: tool.inputSchema,
         annotations: tool.annotations
       },
-      async (input) => withToolErrors(() => handler(client, input))
+      async (input) => withToolErrors(async () => {
+        const parsed = tool.inputSchema.parse(input ?? {});
+        return handler(client, parsed);
+      })
     );
+    entries.push({ tool, registered });
   }
-  return server;
+  const catalog = new DynamicToolCatalog(entries, scope, { eager: options.eager });
+  catalog.applyInitialEnablement();
+  registerMetaTools(server, catalog);
+  return { server, catalog };
+}
+var loadToolkitInputSchema = z3.object({
+  name: z3.enum(CANONRY_MCP_TOOLKIT_NAMES).describe("Toolkit name. List options with canonry_help.")
+});
+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: loadToolkitInputSchema.shape,
+      annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false }
+    },
+    async (input) => withToolErrors(async () => {
+      const parsed = loadToolkitInputSchema.parse(input ?? {});
+      return catalog.loadToolkit(parsed.name);
+    })
+  );
 }
 function getCanonryMcpTools(scope = "all") {
   return scope === "read-only" ? canonryMcpTools.filter((tool) => tool.access === "read") : [...canonryMcpTools];
 }
 
 // src/mcp/cli.ts
+var HELP_TEXT = `Usage: canonry-mcp [--read-only | --scope=<all|read-only>] [--eager]
+
+Stdio MCP adapter over the Canonry public API. Inherits config from
+~/.canonry/config.yaml (or $CANONRY_CONFIG_DIR/config.yaml).
+
+Flags:
+  --read-only          Expose read tools only
+  --scope=<all|read-only>
+                       Same as --read-only when "read-only"
+  --eager              Load all toolkits at start (skip progressive discovery)
+  --help, -h           Show this message
+
+Environment variables:
+  CANONRY_MCP_SCOPE    "all" (default) or "read-only"
+  CANONRY_MCP_EAGER    "1" / "true" / "yes" to enable eager mode
+`;
+var HelpRequested = class extends Error {
+  constructor() {
+    super("canonry-mcp --help requested");
+    this.name = "HelpRequested";
+  }
+};
 async function main(argv = process.argv.slice(2)) {
-  const server = createCanonryMcpServer({ scope: parseScope(argv) });
+  let options;
+  try {
+    options = parseCliOptions(argv);
+  } catch (error) {
+    if (error instanceof HelpRequested) {
+      process.stderr.write(HELP_TEXT);
+      return;
+    }
+    throw error;
+  }
+  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) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    throw new HelpRequested();
+  }
+  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");
@@ -827,13 +1084,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";
@@ -843,6 +1105,8 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   });
 }
 export {
+  HELP_TEXT,
+  HelpRequested,
   main,
-  parseScope
+  parseCliOptions
 };