@moonarc/mcp 0.1.0

package/src/server.js

@@ -0,0 +1,196 @@
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { detail, findComponent, libraryChunks, loadCatalog, search, summary } from './catalog.js';
+import { audit, formatAudit } from './audit.js';
+import { formatMeasure, measureDist } from './measure.js';
+import { compose } from './compose.js';
+import { hasKey, licenseStatus } from './license.js';
+import { installText } from './install.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+// What each tool does to the world, for clients that ask before running one: every tool reads, none writes; the
+// catalogue tools answer from a bundled file, get_usage asks Polar about the key, and the Pro tools read your files.
+const READS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+
+const text = (t) => ({ content: [{ type: 'text', text: t }] });
+const failure = (t) => ({ isError: true, content: [{ type: 'text', text: t }] });
+
+/** Letters to change, add or drop to turn one name into the other. */
+const distance = (a, b) => {
+  let row = [...Array(b.length + 1).keys()];
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    row = next;
+  }
+  return row[b.length];
+};
+/** Names close to one that is not in the catalogue: a misspelling of a name first, then the ranking search_motion uses. */
+const closest = (cat, name) => {
+  const key = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const typos = cat.components.filter((c) => distance(key, c.name.toLowerCase()) <= Math.max(1, Math.floor(key.length / 3))).map((c) => c.name);
+  return [...new Set([...typos, ...search(cat.components, name).map((e) => e.name)])].slice(0, 5);
+};
+
+export function createServer() {
+  const server = new McpServer({ name: 'moonarc', version });
+
+  server.registerTool(
+    'search_motion',
+    {
+      title: 'Search the Moonarc catalogue',
+      description:
+        'Find components for an intent ("fade in on scroll", "logo marquee", "typewriter"). Returns metadata only: name, description, tier, measured JS cost (raw and gzip; jsBytes is raw), page URL, best match first, at most `limit` of them (10 unless set) with the count of all matches. Filter by max_js_bytes (own JS, raw bytes) or tier: A has no script of its own, B its own script up to 1024 B raw, C up to 3072 B raw. Call get_component for source and craft notes.',
+      inputSchema: {
+        intent: z.string().describe('What the user wants, in plain words'),
+        max_js_bytes: z.number().int().nonnegative().optional().describe('Only components whose own JS is at most this many raw bytes'),
+        tier: z.enum(['A', 'B', 'C']).optional().describe('A: no script of its own; B: its own script up to 1024 B raw; C: up to 3072 B raw'),
+        limit: z.number().int().min(1).max(50).optional().describe('How many results to return, best first (default 10, at most 50)'),
+      },
+      annotations: READS,
+    },
+    async ({ intent, max_js_bytes, tier, limit = 10 }) => {
+      const cat = await loadCatalog();
+      const hits = search(cat.components, intent, { maxJsBytes: max_js_bytes, tier });
+      if (hits.length === 0) return text(`No component answers "${intent}". The catalogue is deliberately small (${cat.components.length} components); see ${cat.site}/components/ for what exists, or build it from the runtime: ${cat.site}/docs/runtime/`);
+      return text(JSON.stringify({ runtimeSharedBytes: cat.runtime?.raw ?? null, matched: hits.length, results: hits.slice(0, limit).map(summary) }, null, 2));
+    },
+  );
+
+  server.registerTool(
+    'get_component',
+    {
+      title: 'Get a component: source, props, craft',
+      description: 'Full source, props table, reduced-motion branch, ClientRouter behaviour and the craft decisions (easing, duration, why) for one component. Use the exact name from search_motion (e.g. "Reveal").',
+      inputSchema: { name: z.string().describe('Component name or slug, e.g. Reveal or reveal') },
+      annotations: READS,
+    },
+    async ({ name }) => {
+      const cat = await loadCatalog();
+      const e = findComponent(cat, name);
+      if (!e) {
+        const near = closest(cat, name);
+        return failure(`Unknown component "${name}". ${near.length ? `Closest: ${near.join(', ')}.` : `Known: ${cat.components.map((c) => c.name).join(', ')}.`} Call search_motion to find one by intent.`);
+      }
+      return text(detail(e, cat.runtime));
+    },
+  );
+
+  server.registerTool(
+    'get_install_command',
+    {
+      title: 'Get the install command',
+      description: 'Returns the command to run. The server never writes files. "package" (default) installs the integration once and you import per component; "copy" copies the component source into the project through the shadcn CLI, and the answer carries the components.json and the @/* alias that an Astro project needs for it. Every name must be in the catalogue: an unknown one fails the call and names the closest.',
+      inputSchema: { names: z.array(z.string()).min(1).describe('Component names'), method: z.enum(['package', 'copy']).optional() },
+      annotations: READS,
+    },
+    async ({ names, method = 'package' }) => {
+      const cat = await loadCatalog();
+      const found = names.map((n) => [n, findComponent(cat, n)]);
+      const unknown = found.filter(([, e]) => !e).map(([n]) => n);
+      // a command for some of the names would look complete: every name is known, or none is answered
+      if (unknown.length) {
+        const named = unknown.map((n) => { const near = closest(cat, n); return `"${n}"${near.length ? ` (closest: ${near.join(', ')})` : ''}`; });
+        return failure(`Not in the catalogue: ${named.join('; ')}. Call search_motion to find the right names, then ask again with all of them.`);
+      }
+      const entries = [...new Map(found.map(([, e]) => [e.name, e])).values()];
+      return text(installText(cat.site, entries, method));
+    },
+  );
+
+  server.registerTool(
+    'get_usage',
+    {
+      title: 'Plan and quota',
+      description: 'Which plan this server runs under and whether Pro tools are available. Free is unlimited and needs no account. With a key it asks Polar once whether the key is valid. On subscription_required, do not retry: tell the user.',
+      inputSchema: {},
+      annotations: { ...READS, openWorldHint: true },
+    },
+    async () => {
+      const st = await licenseStatus();
+      const cat = await loadCatalog();
+      return text(JSON.stringify({ plan: st.plan, validated: st.validated ?? false, reason: st.reason ?? null, quota: 'unlimited (plan-level, not metered)', proTools: st.ok ? ['audit_motion', 'measure_budget', 'compose_section'] : [], upgrade: `${cat.site}/pro/` }, null, 2));
+    },
+  );
+
+  // Pro tools occupy agent context only when a key is present (capability gating).
+  if (hasKey) {
+    const gate = async () => {
+      const st = await licenseStatus();
+      if (st.ok) return null;
+      // a key Polar refused says subscription_required itself; a failure that says nothing about the key (no answer,
+      // a 5xx) is not a refusal, and the agent may try again later
+      return failure(/subscription_required/.test(st.reason ?? '') ? st.reason : `Pro tools are unavailable for now: ${st.reason}`);
+    };
+
+    server.registerTool(
+      'audit_motion',
+      {
+        title: 'Audit motion in a codebase (Pro)',
+        description: 'Static findings against the motion critique rubric on your own files, 13 rules: transition: all, transitions and keyframes on layout properties, permanent will-change, animated blur, long UI durations, animation-timeline folded into the shorthand, missing reduced-motion branches, astro:page-load listeners without teardown, single-instance querySelector in component scripts, define:vars on scripts, ungated hover motion, scale(0). Reads style sheets, scripts and markup, never prose or comments. Line-accurate, with the fix and a severity (error, warn, info). Runs on .astro/.css/.scss/.ts/.tsx/.js/.jsx/.svelte/.vue/.html.',
+        inputSchema: { paths: z.array(z.string()).min(1).describe('Files or directories to audit, e.g. ["src"]'), format: z.enum(['text', 'json']).optional() },
+        annotations: READS,
+      },
+      async ({ paths, format = 'text' }) => {
+        const blocked = await gate();
+        if (blocked) return blocked;
+        try {
+          const r = audit(paths);
+          return text(format === 'json' ? JSON.stringify(r, null, 2) : formatAudit(r));
+        } catch (err) {
+          return failure(err.message);
+        }
+      },
+    );
+
+    server.registerTool(
+      'measure_budget',
+      {
+        title: 'Measure per-route JS of a built site (Pro)',
+        description: 'The method of Moonarc\'s own CI: per page, every byte of JavaScript the browser loads (external scripts, inline scripts, modulepreloads, the import graph, the component and renderer of every framework island), with Astro\'s router and Moonarc\'s share broken out and framework runtimes named. JSON and import-map blocks are data and do not count. Pass the folder of a finished `astro build` (dist; a server build\'s dist/client is found by itself); the tool never builds for you. A file a page references that is not in the folder fails the call and names it.',
+        inputSchema: {
+          dist: z.string().describe('Path to the built output, e.g. "dist"'),
+          ceiling: z.number().int().positive().optional().describe('Raw bytes per route you consider acceptable'),
+          base: z.string().optional().describe('The base path the site is built with, when astro.config sets one (e.g. "/docs")'),
+          format: z.enum(['text', 'json']).optional(),
+        },
+        annotations: READS,
+      },
+      async ({ dist, ceiling, base, format = 'text' }) => {
+        const blocked = await gate();
+        if (blocked) return blocked;
+        try {
+          const r = measureDist(dist, { ceiling, base, library: libraryChunks(await loadCatalog()) });
+          return text(format === 'json' ? JSON.stringify({ ...r, routes: r.routes.map(({ assets, ...x }) => x) }, null, 2) : formatMeasure(r));
+        } catch (err) {
+          return failure(err.message);
+        }
+      },
+    );
+
+    server.registerTool(
+      'compose_section',
+      {
+        title: 'Compose a section for a goal (Pro)',
+        description: 'An ordered composition of components for a stated goal ("premium dark SaaS hero", "logo strip", "feature grid", "testimonial wall", "stat row", "CTA", "FAQ") with the total measured cost, the imports and a code skeleton to adapt. A goal with no recipe says so and lists the goals it knows.',
+        inputSchema: { intent: z.string().describe('What the section is for') },
+        annotations: READS,
+      },
+      async ({ intent }) => {
+        const blocked = await gate();
+        if (blocked) return blocked;
+        return text(compose(intent, await loadCatalog()));
+      },
+    );
+  }
+
+  return server;
+}
+
+export async function start() {
+  const server = createServer();
+  await server.connect(new StdioServerTransport());
+}