[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8},"actionData","errors","root",{"_112":113,"_114":115},"routes/embed.x.$handle.$name.$",{"_9":10,"_11":12,"_13":14,"_15":16,"_17":18,"_19":20,"_21":-5},"handle","canonry","name","Brand-Perception-Check","path","src/mcp/tools.ts","project",{"_22":49,"_11":12,"_35":50,"_51":-5,"_52":44,"_53":54,"_55":54,"_56":57,"_58":59,"_60":61,"_62":63,"_64":34,"_65":-5,"_66":-5,"_67":68,"_69":70,"_71":72,"_73":74,"_75":76,"_77":-5,"_78":79,"_80":79,"_81":82,"_83":82,"_84":82,"_85":79,"_86":79,"_87":88,"_89":90,"_91":92,"_93":44},"file",{"_22":23,"_11":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":36,"_37":38,"_39":40,"_41":42,"_43":44,"_45":-5,"_13":46},"permalink","https://www.val.town/x/canonry/Brand-Perception-Check/code/src/mcp/tools.ts","extension","id","a7f7a1ac-d0e9-403f-83a6-decfb8e0de07","tools.ts","fileId","efe97300-a7bd-11f1-90c1-1607ee4eb77e","parentId","ee403354-a7bd-11f1-adc2-1607ee4eb77e","branchId","0ff5a62c-67cf-45f9-85df-c272daf0a6a9","branchVersion",35,"latest",true,"createdAt",["D",1788474102392],"version",1,"fileType","script","content","/**\n * The MCP tool surface: reads over checks this val has already run, plus the\n * bundled skills for clients that do not implement MCP resources.\n *\n * Every tool but `start_check` is a read, and `start_check` runs the host's full\n * admission path — same global daily cap, same single execution lease, same\n * cache reuse — differing only in that it skips Turnstile, which an agent cannot\n * solve, and spends from its own tighter per-caller bucket. The global cap is\n * what bounds the bill; Turnstile bounds fairness, so this widens who may spend\n * the budget without widening the budget.\n *\n * Results are JSON in a text block rather than `structuredContent`, because\n * every client across both protocol eras renders text content, while typed\n * output is newer and unevenly implemented.\n */\nimport { type CheckRecord, checkFingerprint, type CheckStore, isCheckExpired } from 'npm:@canonry/val-kit@0.2.0/jobs'\nimport type { PerceptionEvidence } from 'npm:@canonry/val-kit@0.2.0/perception'\nimport { readSkillResource } from 'npm:@canonry/val-kit@0.2.0/mcp'\nimport { normalizePublicDomain, PublicUrlError } from 'npm:@canonry/val-kit@0.2.0/security'\nimport { CHECK_FINGERPRINT_NAMESPACE, type PerceptionCheckResult } from '../runtime/check-result.ts'\n\nconst CHECK_ID = /^[0-9a-f-]{36}$/i\n\n/**\n * The one sentence that keeps this instrument out of the other one's table.\n *\n * Every question here NAMES the brand, so the engine was always going to talk\n * about it: a mention rate over this basket would read ~100% and mean nothing.\n * AI Visibility asks non-brand questions, where placement is actually decided.\n * The two never share a denominator, so the scope travels with every number.\n */\nconst BRANDED_SCOPE_NOTE =\n 'These are branded questions — the brand is named in each one — so the engine was always going to discuss it. ' +\n 'The finding is what it SAID, never whether it appeared. Never compare these figures to an AI Visibility ' +\n 'mention or citation rate: those are measured on non-brand queries and share no denominator with this.'\n\nexport interface McpToolDefinition {\n name: string\n title: string\n description: string\n inputSchema: Record\n}\n\nexport interface McpToolResult {\n content: Array<{ type: 'text'; text: string }>\n isError?: boolean\n}\n\n/** Runs the host's full admission path; absent when the host disables MCP starts. */\nexport type StartCheckFn = (\n domain: string,\n remoteIp: string | null,\n queries: readonly string[],\n) => Promise<{ record: CheckRecord; reused: boolean }>\n\nexport interface McpToolContext {\n store: CheckStore\n now: () => Date\n startCheck?: StartCheckFn\n /** Edge-provided caller identity, used only as the quota subject. */\n remoteIp?: string | null\n}\n\nfunction ok(payload: unknown): McpToolResult {\n return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] }\n}\n\nfunction fail(message: string, hint?: string): McpToolResult {\n return {\n content: [{ type: 'text', text: JSON.stringify(hint ? { error: message, hint } : { error: message }, null, 2) }],\n isError: true,\n }\n}\n\nconst TARGET_SCHEMA = {\n type: 'object',\n properties: {\n checkId: { type: 'string', description: 'A check ID returned by a previous tool call or shown in the web UI.' },\n domain: {\n type: 'string',\n description:\n 'A domain such as \"example.com\". Resolves the most recent cached check; it never starts one. Use start_check ' +\n 'to run a fresh check.',\n },\n },\n additionalProperties: false,\n} as const\n\n/**\n * Resolve either addressing mode to a readable record.\n *\n * A domain lookup only ever finds work the val already did — it never starts a\n * check — so a miss is reported as a miss rather than quietly queuing paid work\n * the caller did not ask for.\n */\nasync function resolveCheck(\n context: McpToolContext,\n args: Record,\n): Promise<{ record: CheckRecord } | { error: McpToolResult }> {\n const checkId = typeof args.checkId === 'string' ? args.checkId.trim() : ''\n const domain = typeof args.domain === 'string' ? args.domain.trim() : ''\n\n if (!checkId && !domain) return { error: fail('Provide either \"checkId\" or \"domain\".') }\n\n const now = context.now()\n\n if (checkId) {\n if (!CHECK_ID.test(checkId)) return { error: fail(`\"${checkId}\" is not a valid check ID.`) }\n const record = await context.store.get(checkId)\n if (!record || isCheckExpired(record, now)) {\n return {\n error: fail(`No check found for ID \"${checkId}\".`, 'Public checks expire; run a new one from the web UI.'),\n }\n }\n return { record }\n }\n\n let normalized: string\n try {\n normalized = normalizePublicDomain(domain).domain\n } catch (error) {\n return { error: fail(error instanceof PublicUrlError ? error.message : 'Enter a valid public domain.') }\n }\n\n const record = await context.store.findReusable(\n checkFingerprint(CHECK_FINGERPRINT_NAMESPACE, normalized),\n now.toISOString(),\n )\n if (!record) {\n return {\n error: fail(\n `No cached check for \"${normalized}\".`,\n 'Run one with start_check, or from the web UI, then read it here.',\n ),\n }\n }\n return { record }\n}\n\n/** Shared envelope so every tool reports status and freshness the same way. */\nfunction recordEnvelope(record: CheckRecord) {\n return {\n checkId: record.id,\n domain: record.domain,\n status: record.status,\n createdAt: record.createdAt,\n updatedAt: record.updatedAt,\n expiresAt: record.expiresAt,\n error: record.errorCode ? { code: record.errorCode, message: record.errorMessage } : null,\n }\n}\n\n/**\n * The headline numbers, passed straight through from the record.\n *\n * Never recomputed here. The summary is what the instrument measured over the\n * rows it wrote; deriving it a second time on the read path is how a tool\n * payload starts disagreeing with the page and with itself.\n */\nfunction perceptionSummary(record: CheckRecord) {\n const perception = record.result?.perception\n if (!perception) return { measured: false as const }\n return {\n measured: true as const,\n scope: 'branded' as const,\n scopeNote: BRANDED_SCOPE_NOTE,\n brandNames: perception.brandNames,\n successfulChecks: perception.summary.successfulChecks,\n failedChecks: perception.summary.failedChecks,\n verdicts: perception.summary.verdicts,\n verdictNote:\n 'Counts are over successful checks only and sum to successfulChecks. \"none\" means the answer took no position, ' +\n 'which is a finding; a failed check has a null verdict and is in no denominator.',\n concerns: perception.summary.concerns,\n sourceTypes: perception.summary.sourceTypes,\n sourceNote:\n 'Sources the answer engine attributed for these answers, typed. A type counts once per answer, and an answer ' +\n 'that attributed nothing is stated as unattributedAnswers rather than folded into the denominator.',\n startedAt: perception.startedAt,\n completedAt: perception.completedAt,\n }\n}\n\nfunction evidenceRow(evidence: PerceptionEvidence) {\n return {\n query: evidence.query,\n provider: evidence.provider,\n servedModel: evidence.servedModel,\n completedAt: evidence.completedAt,\n // Null means this check produced no verdict — a failed probe or a failed\n // extraction. It is never 'none', which says the answer took no position.\n verdict: evidence.verdict,\n // Copied out of the answer and verified present in it, word for word.\n evidenceSentences: evidence.evidenceSentences,\n concerns: evidence.concerns,\n sources: evidence.sources,\n searchQueries: evidence.searchQueries,\n retrievalStatus: evidence.retrievalStatus,\n answerText: evidence.answerText,\n error: evidence.error,\n }\n}\n\n/**\n * The conversion path. An agent that has just shown a user what an engine says\n * about their brand is exactly where \"how do I get this properly\" gets asked,\n * and without this it would have to guess at an install command.\n */\nconst SELF_HOST_TOOL: McpToolDefinition = {\n name: 'self_host',\n title: 'How to self-host Canonry',\n description:\n 'How to run the full Canonry platform instead of this bounded sample: install command, repository, docs, and ' +\n 'what self-hosting adds over this endpoint. Call it when the user asks for more engines, scheduled tracking, ' +\n 'more questions, their own data, or how any of this actually works.',\n inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n}\n\nconst START_CHECK_TOOL: McpToolDefinition = {\n name: 'start_check',\n title: 'Run a new brand perception check',\n description:\n 'Run a fresh check for a domain: three grounded Gemini answers to BRANDED questions about the brand, each read ' +\n 'back for the position it takes. Blocks until the check finishes, up to about 45 seconds, and returns the same ' +\n 'shape as get_check. A domain checked in the last 24 hours with the same questions returns the cached result ' +\n 'immediately and costs nothing. Daily limits apply.',\n inputSchema: {\n type: 'object',\n properties: {\n domain: { type: 'string', description: 'A domain such as \"example.com\".' },\n queries: {\n type: 'array',\n items: { type: 'string' },\n maxItems: 3,\n description:\n 'Optional. Up to 3 questions to put to the answer engine, used verbatim. Any remaining slots are filled ' +\n 'with branded questions generated for the brand, so supplying none generates all three.',\n },\n },\n required: ['domain'],\n additionalProperties: false,\n },\n}\n\nconst READ_TOOLS: readonly McpToolDefinition[] = [\n SELF_HOST_TOOL,\n {\n name: 'get_check',\n title: 'Get a brand perception check',\n description:\n 'Status and headline numbers for one brand check: how many answers recommend, caution, are mixed, or took no ' +\n 'position, the concerns those answers raised, and the mix of source types the engine attributed. Address it by ' +\n 'checkId or by domain. Every figure is scoped to BRANDED questions and is never comparable to an AI Visibility ' +\n 'mention or citation rate. Reads existing work only — it never starts a new check.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'get_brand_perception',\n title: 'Get brand perception evidence',\n description:\n 'Per answer evidence for one check. Every row carries the verdict the answer gave, the sentences copied out of ' +\n 'that answer word for word which carry it, the concerns it wrote, the typed sources the engine attributed, and ' +\n 'the full answer text. A null verdict means that check produced none and was not measured — it is never \"none\", ' +\n 'which says the answer took no position. Branded scope; not comparable to AI Visibility rates.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'read_skill',\n title: 'Read a Canonry skill document',\n description: 'Read one bundled canonry (operator) or aero (analyst) skill document as markdown. Accepts a ' +\n 'canonry-skill:// URI or a path such as \"aero/references/regression-playbook.md\". The full index is served as ' +\n 'MCP resources: call resources/list for every available URI, starting with the two SKILL.md entry points.',\n inputSchema: {\n type: 'object',\n properties: {\n uri: { type: 'string', description: 'A canonry-skill:// URI, or \"/\", or a bare reference path.' },\n },\n required: ['uri'],\n additionalProperties: false,\n },\n },\n]\n\n/** The advertised catalog. `start_check` appears only when the host can honour it. */\nexport function mcpTools(context: McpToolContext): readonly McpToolDefinition[] {\n return context.startCheck ? [...READ_TOOLS, START_CHECK_TOOL] : READ_TOOLS\n}\n\nexport async function callMcpTool(\n context: McpToolContext,\n name: string,\n args: Record,\n): Promise {\n switch (name) {\n case 'get_check': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n return ok({\n ...recordEnvelope(resolved.record),\n brandPerception: perceptionSummary(resolved.record),\n partialErrors: resolved.record.result?.errors ?? [],\n })\n }\n\n case 'get_brand_perception': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n const perception = resolved.record.result?.perception\n if (!perception) {\n return ok({\n ...recordEnvelope(resolved.record),\n measured: false,\n reason: resolved.record.status === 'queued' || resolved.record.status === 'running'\n ? 'The check is still running.'\n : 'This check has no brand perception result.',\n })\n }\n return ok({\n ...recordEnvelope(resolved.record),\n scope: 'branded',\n scopeNote: BRANDED_SCOPE_NOTE,\n summary: perceptionSummary(resolved.record),\n evidence: perception.evidence.map(evidenceRow),\n })\n }\n\n case 'start_check': {\n if (!context.startCheck) return fail('Starting a check is not enabled on this endpoint.')\n const domain = typeof args.domain === 'string' ? args.domain.trim() : ''\n if (!domain) return fail('Provide a \"domain\".')\n try {\n const queries = Array.isArray(args.queries) ? args.queries : []\n const { record, reused } = await context.startCheck(domain, context.remoteIp ?? null, queries)\n return ok({\n ...recordEnvelope(record),\n reused,\n brandPerception: perceptionSummary(record),\n partialErrors: record.result?.errors ?? [],\n })\n } catch (error) {\n // The host throws typed admission failures (quota, capacity, invalid\n // domain). Their messages are already caller-safe and actionable.\n return fail(error instanceof Error ? error.message : 'The check could not be started.')\n }\n }\n\n case 'self_host':\n return ok({\n summary:\n 'This endpoint is a bounded sample. Canonry is the full platform it samples: open source, self-hosted, ' +\n 'agent-first, with your own data in local SQLite.',\n install: 'npm install -g @canonry/canonry',\n quickstart: [\n 'npm install -g @canonry/canonry',\n 'canonry init',\n 'canonry project create my-site --domain example.com --country US --language en',\n 'canonry query add my-site \"best example widgets\"',\n 'canonry run my-site',\n 'canonry visibility-stats my-site',\n ],\n repository: 'https://github.com/Canonry/canonry',\n website: 'https://canonry.ai',\n package: 'https://www.npmjs.com/package/@canonry/canonry',\n license: 'FSL-1.1-ALv2',\n whatSelfHostingAdds: [\n 'All four answer engines — Gemini, ChatGPT, Claude, Perplexity — not Gemini alone.',\n 'Unlimited tracked questions and scheduled sweeps, instead of 3 branded questions on demand.',\n 'History, so you can see a verdict or a concern appear, spread, or go away.',\n 'Non-brand tracking as well: mention and citation coverage on the questions that decide placement.',\n 'Competitor mention share, regression insights, and a downloadable client report.',\n 'Google Search Console, GA4, Bing, Business Profile, and server-side traffic joined to the same view.',\n 'Your own MCP server (canonry-mcp, 188 tools) and the built-in Aero analyst agent.',\n 'Your data stays in your own SQLite database.',\n ],\n skills: 'The canonry and aero skill documents served by this endpoint are the same playbooks a local install ' +\n 'ships. Read canonry-skill://canonry/SKILL.md to operate the CLI.',\n })\n\n case 'read_skill': {\n const uri = typeof args.uri === 'string' ? args.uri.trim() : ''\n if (!uri) return fail('Provide a skill document \"uri\".')\n const contents = readSkillResource(uri)\n if (!contents) {\n return fail(`No skill document matches \"${uri}\".`, 'Call resources/list for the available URIs.')\n }\n return { content: [{ type: 'text', text: contents.text }] }\n }\n\n default:\n return null\n }\n}\n","deleted",false,"label",[47,48,24],"src","mcp","801445f4-c67d-433d-af43-92af47fb72c9",["D",1788456812405],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","What AI engines say about a brand. Powered by Canonry.","imageUrl","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/aa8bd75a-0bc9-4694-0b72-9f187d1a6201/square512?exp=1789585199&sig=538884e9221cd2bbd7b74ab198e61c2278dcef05070fdfd8361a4fbdfbc7efc6","userId","891d245e-ec71-404d-a5ca-223733ee2844","pinnedFileId","f06d06b6-a7bd-11f1-990b-1607ee4eb77e","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","01a0460b-6625-75ce-9e7f-9a6b062b0798","tursoName","801445f4c67d433daf4392af47fb72c9","tursoHostname","801445f4c67d433daf4392af47fb72c9-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789501263826],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_9":10,"_111":107},"org",{"_9":10,"_104":105,"_106":107,"_60":-5,"_108":109,"_110":44},"branch",{"_37":94,"_11":95,"_22":30,"_96":49,"_97":-5,"_98":-5,"_99":-5,"_100":-5,"_101":-5,"_102":12,"_103":10},"isOwned",40,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","displayName","Canonry","avatar","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/5ae39d80-0d23-48e5-89d8-6bd2a7096401/square512?exp=1789585199&sig=17a7945f2bd6cb2bc36ded14a23a6fde24f62bd8a3b7ee410fad54f95831b7b2","tier","free","canRestrictVals","profileImageUrl","ctx",{"_87":-5,"_145":146,"_147":148,"_149":150,"_151":44,"_152":44,"_153":44,"_154":34,"_155":-5,"_156":-7,"_157":-7,"_158":68,"_159":44,"_160":44,"_161":-5,"_162":44,"_163":44,"_164":44,"_165":-5},"ENV",{"_116":117,"_118":119,"_120":95,"_121":122,"_123":124,"_125":126,"_127":128,"_129":130,"_131":132,"_133":134,"_135":136,"_137":138,"_139":140,"_141":142,"_143":144},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","fdb67791413f4386b4dbf18f354029a617f6160f","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town","orgs",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]