@canonry/canonry 4.104.0

package/dist/mcp.js

@@ -0,0 +1,442 @@
+import {
+  CliError,
+  PACKAGE_VERSION,
+  canonryMcpTools,
+  createApiClient
+} from "./chunk-23DCY7DL.js";
+import {
+  isReadOnlyKey
+} from "./chunk-Q7FFDQU4.js";
+
+// src/mcp/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/mcp/results.ts
+import { ZodError } from "zod";
+function jsonToolResult(value) {
+  const result = value === void 0 ? { ok: true } : value;
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+function errorToolResult(error) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(toCanonryErrorEnvelope(error), null, 2)
+      }
+    ]
+  };
+}
+async function withToolErrors(handler) {
+  try {
+    return jsonToolResult(await handler());
+  } catch (error) {
+    return errorToolResult(error);
+  }
+}
+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: {
+        code: error.code,
+        message: error.message,
+        ...error.details ? { details: error.details } : {}
+      }
+    };
+  }
+  if (hasErrorEnvelope(error)) {
+    const { code, message, details } = error.error;
+    return {
+      error: {
+        code: typeof code === "string" ? code : "API_ERROR",
+        message: typeof message === "string" ? message : "Canonry API error",
+        ...details !== void 0 ? { details } : {}
+      }
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      error: {
+        code: "MCP_TOOL_ERROR",
+        message: error.message
+      }
+    };
+  }
+  return {
+    error: {
+      code: "MCP_TOOL_ERROR",
+      message: "Unknown MCP tool error"
+    }
+  };
+}
+function hasErrorEnvelope(value) {
+  if (!value || typeof value !== "object" || !("error" in value)) return false;
+  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", "gbp", "ads", "traffic", "agent", "discovery"];
+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 queries, competitors, schedules, project upsert, and config-as-code roundtrips.",
+    whenToLoad: "Load when onboarding a new project or editing tracked queries, 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: "gbp",
+    title: "Google Business Profile",
+    description: "Local AEO signals: discover GBP locations under a connected account and toggle which ones sync. Future phases will add reviews, keyword impressions, daily performance metrics, and hotel attributes.",
+    whenToLoad: "Load when the project tracks local search visibility or has connected Google Business Profile."
+  },
+  {
+    name: "ads",
+    title: "OpenAI ads (ChatGPT ads)",
+    description: "Paid-surface data for the connected OpenAI ad account: connection status, campaign/ad-group snapshots (context hints), daily paid-performance rollups (spend in integer micros), and the composite summary. Trigger ads-sync runs.",
+    whenToLoad: "Load when the project runs ChatGPT ads and you need paid performance, campaign structure, or to trigger an ads sync."
+  },
+  {
+    name: "traffic",
+    title: "Server-side traffic ingestion",
+    description: "Connect Cloud Run traffic sources, trigger syncs, and read crawler / AI-referral hourly rollups straight from server logs (no GA dependency).",
+    whenToLoad: "Load when you need server-log evidence of crawler hits or AI-referral sessions (e.g. confirming GPTBot or ChatGPT-User on a page), or when wiring up / syncing a Cloud Run traffic source."
+  },
+  {
+    name: "agent",
+    title: "Aero agent lifecycle and memory",
+    description: "Manage the built-in Aero agent: durable project-scoped memory (list/set/forget), clear the rolling transcript, and detach the external-agent webhook.",
+    whenToLoad: "Load when reading or writing project-scoped Aero notes, clearing a stuck conversation, or removing an external agent webhook."
+  },
+  {
+    name: "discovery",
+    title: "Tracked-basket discovery (ICP \u2192 buckets)",
+    description: "Start and inspect discovery sessions. Each session expands an ICP description into a deduped set of representative queries, probes them against Gemini grounding, classifies each probe into cited / aspirational / wasted-surface, and aggregates a competitor map for the project.",
+    whenToLoad: "Load when the operator wants to expand or audit a project's tracked-query basket, audit competitive surface, or preview a promotion plan from a discovery session."
+  }
+];
+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;
+  server;
+  constructor(server, entries, scope, options = {}) {
+    this.server = server;
+    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;
+    this.batchListChanged(() => {
+      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) };
+    }
+    this.batchListChanged(() => {
+      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. Wait for its response before calling any newly enabled tool."
+    };
+  }
+  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);
+  }
+  // RegisteredTool.enable/disable each call sendToolListChanged on the McpServer
+  // we registered with. Loading an 11-tool toolkit emits 11 notifications under
+  // that contract, which a spec-compliant client will treat as 11 catalog
+  // refetches. Coalesce them into one notification per batch by intercepting
+  // the SDK's sender for the duration of the batch.
+  batchListChanged(fn) {
+    const host = this.server;
+    const original = host.sendToolListChanged.bind(host);
+    let suppressed = false;
+    host.sendToolListChanged = () => {
+      suppressed = true;
+    };
+    try {
+      fn();
+    } finally {
+      host.sendToolListChanged = original;
+    }
+    if (suppressed) original();
+  }
+};
+
+// 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";
+  const server = new McpServer({
+    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;
+    const registered = server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: tool.annotations
+      },
+      async (input) => withToolErrors(async () => {
+        const parsed = tool.inputSchema.parse(input ?? {});
+        return handler(client, parsed);
+      })
+    );
+    entries.push({ tool, registered });
+  }
+  const catalog = new DynamicToolCatalog(server, entries, scope, { eager: options.eager });
+  catalog.applyInitialEnablement();
+  registerMetaTools(server, catalog);
+  return { server, catalog };
+}
+var loadToolkitInputSchema = z.object({
+  name: z.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 one notifications/tools/list_changed. Idempotent. Loaded toolkits remain loaded for the rest of the session. Wait for this call to return before calling any newly enabled tool \u2014 pipelining the call with a tools/call on the same connection can race the registration and fail with "MCP error -32602: Tool ... disabled".`,
+      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)) {
+  let options;
+  try {
+    options = parseCliOptions(argv);
+  } catch (error) {
+    if (error instanceof HelpRequested) {
+      process.stderr.write(HELP_TEXT);
+      return;
+    }
+    throw error;
+  }
+  const client = createApiClient();
+  const scope = await resolveEffectiveScope(client, options.scope);
+  const server = createCanonryMcpServer({ scope, eager: options.eager, clientFactory: () => client });
+  await server.connect(new StdioServerTransport());
+}
+async function resolveEffectiveScope(client, flagScope) {
+  if (flagScope === "read-only") return "read-only";
+  try {
+    const self = await client.getApiKeySelf();
+    if (isReadOnlyKey(self.scopes)) {
+      process.stderr.write(
+        "canonry-mcp: configured API key is read-only \u2014 restricting to read tools.\n"
+      );
+      return "read-only";
+    }
+  } catch {
+  }
+  return flagScope;
+}
+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");
+      scope = normalizeScope(next);
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("--scope=")) {
+      scope = normalizeScope(arg.slice("--scope=".length));
+      continue;
+    }
+    throw new Error(`Unknown canonry-mcp argument: ${arg}`);
+  }
+  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";
+    process.stderr.write(`${message}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  HELP_TEXT,
+  HelpRequested,
+  main,
+  parseCliOptions,
+  resolveEffectiveScope
+};

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@canonry/canonry",
+  "version": "4.104.0",
+  "type": "module",
+  "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
+  "license": "FSL-1.1-ALv2",
+  "homepage": "https://canonry.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Canonry/canonry.git",
+    "directory": "packages/canonry"
+  },
+  "bugs": {
+    "url": "https://github.com/Canonry/canonry/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "canonry": "./bin/canonry.mjs",
+    "cnry": "./bin/canonry.mjs",
+    "canonry-mcp": "./bin/canonry-mcp.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bin/",
+    "dist/",
+    "assets/",
+    "package.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "dependencies": {
+    "@ainyc/aeo-audit": "4.0.1",
+    "@anthropic-ai/sdk": "^0.91.1",
+    "@fastify/static": "^9.1.1",
+    "@google/genai": "^1.46.0",
+    "@mariozechner/pi-agent-core": "0.67.6",
+    "@mariozechner/pi-ai": "0.67.6",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@sinclair/typebox": "^0.34.41",
+    "better-sqlite3": "^12.6.2",
+    "chrome-remote-interface": "^0.33.2",
+    "cron-parser": "^5.5.0",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.8.5",
+    "node-cron": "^4.2.1",
+    "openai": "^6.0.0",
+    "pdf-lib": "^1.17.1",
+    "pino-pretty": "^13.1.3",
+    "undici": "^7.24.2",
+    "yaml": "^2.7.1",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node-cron": "^3.0.11",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
+    "@ainyc/canonry-api-client": "0.0.0",
+    "@ainyc/canonry-contracts": "0.0.0",
+    "@ainyc/canonry-api-routes": "0.0.0",
+    "@ainyc/canonry-config": "0.0.0",
+    "@ainyc/canonry-db": "0.0.0",
+    "@ainyc/canonry-integration-bing": "0.0.0",
+    "@ainyc/canonry-integration-openai-ads": "0.0.0",
+    "@ainyc/canonry-integration-cloud-run": "0.0.0",
+    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
+    "@ainyc/canonry-integration-google": "0.0.0",
+    "@ainyc/canonry-integration-google-business-profile": "0.0.0",
+    "@ainyc/canonry-integration-traffic": "0.0.0",
+    "@ainyc/canonry-integration-wordpress": "0.0.0",
+    "@ainyc/canonry-intelligence": "0.0.0",
+    "@ainyc/canonry-integration-google-places": "0.0.0",
+    "@ainyc/canonry-provider-cdp": "0.0.0",
+    "@ainyc/canonry-provider-claude": "0.0.0",
+    "@ainyc/canonry-provider-gemini": "0.0.0",
+    "@ainyc/canonry-provider-openai": "0.0.0",
+    "@ainyc/canonry-provider-local": "0.0.0",
+    "@ainyc/canonry-provider-perplexity": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsx scripts/copy-agent-assets.ts && tsup && tsx build-web.ts",
+    "build:web": "tsx build-web.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config ../../vitest.package.config.ts",
+    "lint": "eslint src/ test/"
+  }
+}