|
| 1 | +/** |
| 2 | + * The MCP tool declarations. |
| 3 | + * |
| 4 | + * Only `src/plugin.ts` references `mcpTools()`, from its `mcp` property, |
| 5 | + * which the plugin build strips from the runtime: these schemas end up in |
| 6 | + * the manifest as JSON Schema, and neither zod nor this module ships in |
| 7 | + * the bundle. Keep it that way. A schema used by a route handler would |
| 8 | + * pull zod into every sandboxed invocation. |
| 9 | + * |
| 10 | + * Output schemas become strict JSON Schema (`additionalProperties: false`) |
| 11 | + * that the MCP server checks every answer against, so each one has to |
| 12 | + * match its loader's result type in `./load.ts` exactly, optional keys |
| 13 | + * included. `tests/tools.test.ts` holds each loader's output against the |
| 14 | + * schema the build wrote. |
| 15 | + */ |
| 16 | + |
| 17 | +import type { SandboxedMcpTool } from "emdash/plugin"; |
| 18 | +import { z } from "zod"; |
| 19 | + |
| 20 | +import { |
| 21 | + DEFAULT_LIMIT, |
| 22 | + MAX_CURSOR, |
| 23 | + MAX_ENTRY_ID, |
| 24 | + MAX_LIMIT, |
| 25 | + MAX_PATH, |
| 26 | + TOOL_ROUTES, |
| 27 | +} from "./load.js"; |
| 28 | + |
| 29 | +export function mcpTools(): Record<string, SandboxedMcpTool> { |
| 30 | + const day = z.string().describe("A UTC day, YYYY-MM-DD."); |
| 31 | + const window = z.object({ |
| 32 | + days: z.number().int(), |
| 33 | + since: day, |
| 34 | + until: day.describe("Today in UTC. Its numbers still move."), |
| 35 | + partial: z |
| 36 | + .boolean() |
| 37 | + .describe("True when stored history starts after since, so the numbers cover fewer days than the window."), |
| 38 | + }); |
| 39 | + const pageHistorySince = day |
| 40 | + .nullable() |
| 41 | + .describe("The oldest day of per-page numbers in storage, or null before the first sync. Older days are pruned by the retention setting."); |
| 42 | + const indexComplete = z |
| 43 | + .boolean() |
| 44 | + .describe( |
| 45 | + "False while the plugin matches the site's pages to entries, on a new install or during a rebuild; entries may be missing or misattributed until then.", |
| 46 | + ); |
| 47 | + const lastSync = z.string().nullable().describe("When the plugin last synced from the provider, ISO 8601."); |
| 48 | + |
| 49 | + const entryDays = z |
| 50 | + .union([z.literal(7), z.literal(30)]) |
| 51 | + .optional() |
| 52 | + .describe("Window in days, ending today (UTC). Default 30."); |
| 53 | + const listInput = z.object({ |
| 54 | + days: entryDays, |
| 55 | + collection: z |
| 56 | + .string() |
| 57 | + .max(63) |
| 58 | + .regex(/^[a-z][a-z0-9_]*$/) |
| 59 | + .optional() |
| 60 | + .describe("Only entries of this collection, by slug, such as posts."), |
| 61 | + limit: z |
| 62 | + .number() |
| 63 | + .int() |
| 64 | + .min(1) |
| 65 | + .max(MAX_LIMIT) |
| 66 | + .optional() |
| 67 | + .describe(`Entries per page, 1 to ${MAX_LIMIT}. Default ${DEFAULT_LIMIT}.`), |
| 68 | + cursor: z |
| 69 | + .string() |
| 70 | + .min(1) |
| 71 | + .max(MAX_CURSOR) |
| 72 | + .optional() |
| 73 | + .describe("nextCursor from the previous page, sent with the same days and collection."), |
| 74 | + }); |
| 75 | + const listOutput = z.object({ |
| 76 | + window, |
| 77 | + collection: z.string().nullable(), |
| 78 | + items: z.array( |
| 79 | + z.object({ |
| 80 | + entryId: z.string(), |
| 81 | + title: z.string(), |
| 82 | + collection: z.string(), |
| 83 | + collectionLabel: z.string(), |
| 84 | + locale: z.string(), |
| 85 | + path: z.string(), |
| 86 | + views: z.number().describe("Page views in the window."), |
| 87 | + publishedAt: z.string().optional(), |
| 88 | + }), |
| 89 | + ), |
| 90 | + nextCursor: z.string().optional().describe("Pass as cursor to get the next page. Absent on the last page."), |
| 91 | + historySince: pageHistorySince, |
| 92 | + indexComplete, |
| 93 | + lastSync, |
| 94 | + }); |
| 95 | + |
| 96 | + const views = { views7: z.number(), views30: z.number() }; |
| 97 | + |
| 98 | + return { |
| 99 | + top_entries: { |
| 100 | + description: |
| 101 | + "The site's most viewed published entries over the last 7 or 30 days, from the analytics provider's page views matched to content. " + |
| 102 | + "Use it to answer which posts or pages get the most traffic. " + |
| 103 | + "The counts are from the plugin's last sync (lastSync) and include today, which is still counting. " + |
| 104 | + "When window.partial is true, stored history is shorter than the window; when indexComplete is false, some entries are not matched yet: say so rather than presenting the list as complete. " + |
| 105 | + "A page can hold fewer items than limit; follow nextCursor for more.", |
| 106 | + route: TOOL_ROUTES.topEntries, |
| 107 | + input: listInput, |
| 108 | + output: listOutput, |
| 109 | + destructive: false, |
| 110 | + }, |
| 111 | + unviewed_entries: { |
| 112 | + description: |
| 113 | + "Published entries with no page views in the last 7 or 30 days. " + |
| 114 | + "Use it to find content nobody reads. " + |
| 115 | + "Check publishedAt: an entry published inside the window had less time to be seen. " + |
| 116 | + "The list is only as complete as the data: window.partial true means stored history is shorter than the window, indexComplete false means some entries are not matched yet. " + |
| 117 | + "A page can hold fewer items than limit; follow nextCursor for more.", |
| 118 | + route: TOOL_ROUTES.unviewedEntries, |
| 119 | + input: listInput, |
| 120 | + output: listOutput, |
| 121 | + destructive: false, |
| 122 | + }, |
| 123 | + entry_views: { |
| 124 | + description: |
| 125 | + "Page views of one entry over the last 7 and 30 days, with its published translations and their combined total. " + |
| 126 | + "Pass entryId, or path as the site serves it (a full URL works too). " + |
| 127 | + "found is false when no page of the entry is in the plugin's index: it may be a draft, in a collection without a URL pattern, or not matched yet (indexComplete). " + |
| 128 | + "The counts are from the plugin's last sync (lastSync) and include today, which is still counting.", |
| 129 | + route: TOOL_ROUTES.entryViews, |
| 130 | + input: z.object({ |
| 131 | + entryId: z.string().min(1).max(MAX_ENTRY_ID).optional().describe("The entry's id."), |
| 132 | + path: z |
| 133 | + .string() |
| 134 | + .min(1) |
| 135 | + .max(MAX_PATH) |
| 136 | + .optional() |
| 137 | + .describe("The path or URL the entry is published at. Used when entryId is not given."), |
| 138 | + }), |
| 139 | + output: z.object({ |
| 140 | + found: z.boolean(), |
| 141 | + entry: z |
| 142 | + .object({ |
| 143 | + entryId: z.string(), |
| 144 | + title: z.string(), |
| 145 | + collection: z.string(), |
| 146 | + collectionLabel: z.string(), |
| 147 | + locale: z.string(), |
| 148 | + path: z.string(), |
| 149 | + status: z |
| 150 | + .enum(["published", "unpublished", "deleted", "moved"]) |
| 151 | + .describe("Not published: the numbers are from the path it was last published at."), |
| 152 | + ...views, |
| 153 | + publishedAt: z.string().optional(), |
| 154 | + }) |
| 155 | + .nullable(), |
| 156 | + translations: z.array( |
| 157 | + z.object({ |
| 158 | + entryId: z.string(), |
| 159 | + title: z.string(), |
| 160 | + locale: z.string(), |
| 161 | + path: z.string(), |
| 162 | + ...views, |
| 163 | + }), |
| 164 | + ), |
| 165 | + allLanguages: z |
| 166 | + .object(views) |
| 167 | + .nullable() |
| 168 | + .describe("The published pages of the entry and its translations together."), |
| 169 | + windows: z.object({ views7: window, views30: window }), |
| 170 | + historySince: pageHistorySince, |
| 171 | + indexComplete, |
| 172 | + lastSync, |
| 173 | + }), |
| 174 | + destructive: false, |
| 175 | + }, |
| 176 | + site_totals: { |
| 177 | + description: |
| 178 | + "Visits and page views for the whole site over the last 7, 30 or 90 days, with the period of the same length before it for comparison. " + |
| 179 | + "Use it for overall traffic and its trend. " + |
| 180 | + "previous is null when stored history does not reach back far enough to compare. " + |
| 181 | + "estimated is true when the provider sampled a day, so the numbers are extrapolated; provisional is true when today, still counting, is included.", |
| 182 | + route: TOOL_ROUTES.siteTotals, |
| 183 | + input: z.object({ |
| 184 | + days: z |
| 185 | + .union([z.literal(7), z.literal(30), z.literal(90)]) |
| 186 | + .optional() |
| 187 | + .describe("Window in days, ending today (UTC). Default 30."), |
| 188 | + }), |
| 189 | + output: z.object({ |
| 190 | + window, |
| 191 | + visits: z.number(), |
| 192 | + pageviews: z.number(), |
| 193 | + estimated: z.boolean(), |
| 194 | + provisional: z.boolean(), |
| 195 | + previous: z |
| 196 | + .object({ |
| 197 | + since: day, |
| 198 | + until: day, |
| 199 | + visits: z.number(), |
| 200 | + pageviews: z.number(), |
| 201 | + estimated: z.boolean(), |
| 202 | + }) |
| 203 | + .nullable(), |
| 204 | + historySince: day |
| 205 | + .nullable() |
| 206 | + .describe("The oldest day of site totals in storage, or null before the first sync. Site totals are kept longer than per-page numbers."), |
| 207 | + lastSync, |
| 208 | + }), |
| 209 | + destructive: false, |
| 210 | + }, |
| 211 | + }; |
| 212 | +} |
0 commit comments