@sanity-labs/slides 0.0.0

package/src/mcp/server.test.ts

@@ -0,0 +1,309 @@
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createElement } from 'react';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { z } from 'zod';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import {
+  Box,
+  Text,
+  CANVAS_16_9,
+  PptxSlidesRuntime,
+  Slide,
+  type Template,
+  type TemplateComponent,
+} from '../core/index.js';
+import { createSlideServer, type SlideServer } from './server.js';
+
+// ---------------------------------------------------------------------------
+// A small template-agnostic test fixture. Two components, both return real <Slide>s.
+// ---------------------------------------------------------------------------
+
+const CoverProps = z
+  .object({
+    title: z.string().min(1).describe('Cover title.'),
+    subtitle: z.string().optional(),
+  })
+  .strict();
+type CoverProps = z.infer<typeof CoverProps>;
+
+const Cover: TemplateComponent<CoverProps> = {
+  component: ({ title, subtitle }: CoverProps) =>
+    createElement(
+      Slide,
+      null,
+      createElement(
+        Box,
+        { rect: { x: 54, y: 54, w: 600, h: 80 }, slotId: 'cover:title' },
+        createElement(Text, null, title),
+      ),
+      subtitle === undefined
+        ? null
+        : createElement(
+            Box,
+            { rect: { x: 54, y: 140, w: 600, h: 40 }, slotId: 'cover:subtitle' },
+            createElement(Text, null, subtitle),
+          ),
+    ),
+  schema: CoverProps as unknown as z.ZodObject<z.ZodRawShape>,
+  description: 'Use as the first slide. Sets title and stance.',
+};
+
+const TwoColumnProps = z
+  .object({
+    left: z.string().min(1),
+    right: z.string().min(1),
+  })
+  .strict();
+type TwoColumnProps = z.infer<typeof TwoColumnProps>;
+
+const TwoColumn: TemplateComponent<TwoColumnProps> = {
+  component: ({ left, right }: TwoColumnProps) =>
+    createElement(
+      Slide,
+      null,
+      createElement(
+        Box,
+        { rect: { x: 54, y: 54, w: 300, h: 300 } },
+        createElement(Text, null, left),
+      ),
+      createElement(
+        Box,
+        { rect: { x: 386, y: 54, w: 300, h: 300 } },
+        createElement(Text, null, right),
+      ),
+    ),
+  schema: TwoColumnProps as unknown as z.ZodObject<z.ZodRawShape>,
+  description: 'Use to compare two parallel ideas of equal weight.',
+};
+
+const TestTemplate: Template = {
+  name: 'test',
+  canvas: CANVAS_16_9,
+  fonts: { display: ['Inter'], body: ['Inter'], mono: ['Courier New'] },
+  colors: {},
+  typography: {},
+  spacing: {},
+  components: {
+    Cover: Cover as unknown as TemplateComponent,
+    TwoColumn: TwoColumn as unknown as TemplateComponent,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Test harness
+// ---------------------------------------------------------------------------
+
+interface Harness {
+  readonly server: SlideServer;
+  readonly client: Client;
+  readonly outputDir: string;
+  close(): Promise<void>;
+}
+
+let activeDir: string | undefined;
+
+beforeEach(async () => {
+  activeDir = await fs.mkdtemp(join(tmpdir(), 'react-pptx-mcp-test-'));
+});
+
+afterEach(async () => {
+  if (activeDir) await fs.rm(activeDir, { recursive: true, force: true });
+  activeDir = undefined;
+});
+
+const makeHarness = async (): Promise<Harness> => {
+  if (!activeDir) throw new Error('activeDir not set; beforeEach failed?');
+  const runtime = new PptxSlidesRuntime({ outputDir: activeDir });
+  const server = createSlideServer({ template: TestTemplate, runtime });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'test-client', version: '0.0.0' });
+  await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+  return {
+    server,
+    client,
+    outputDir: activeDir,
+    close: async () => {
+      await client.close();
+      await server.close();
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('createSlideServer — tool registration', () => {
+  test('exposes slides_list, slides_create, plus one per slide type', async () => {
+    const h = await makeHarness();
+    try {
+      const list = await h.client.listTools();
+      const names = list.tools.map((t) => t.name).sort();
+      expect(names).toEqual([
+        'slides_add_cover',
+        'slides_add_two_column',
+        'slides_create',
+        'slides_list',
+      ]);
+    } finally {
+      await h.close();
+    }
+  });
+
+  test('per-slide-type tool description carries the template component description', async () => {
+    const h = await makeHarness();
+    try {
+      const list = await h.client.listTools();
+      const cover = list.tools.find((t) => t.name === 'slides_add_cover');
+      expect(cover?.description).toBe('Use as the first slide. Sets title and stance.');
+    } finally {
+      await h.close();
+    }
+  });
+
+  test('every tool advertises an outputSchema', async () => {
+    const h = await makeHarness();
+    try {
+      const list = await h.client.listTools();
+      for (const tool of list.tools) {
+        expect(tool.outputSchema, `tool ${tool.name} should expose an outputSchema`).toBeDefined();
+      }
+    } finally {
+      await h.close();
+    }
+  });
+});
+
+describe('slides_list', () => {
+  test('returns the template name and every slide type with description', async () => {
+    const h = await makeHarness();
+    try {
+      const result = await h.client.callTool({ name: 'slides_list', arguments: {} });
+      expect(result.isError).toBeFalsy();
+      const sc = result.structuredContent as {
+        template: string;
+        slides: Array<{ name: string; toolName: string; description: string }>;
+      };
+      expect(sc.template).toBe('test');
+      expect(sc.slides.map((s) => s.name).sort()).toEqual(['Cover', 'TwoColumn']);
+      const cover = sc.slides.find((s) => s.name === 'Cover');
+      expect(cover?.toolName).toBe('slides_add_cover');
+      expect(cover?.description).toMatch(/first slide/);
+    } finally {
+      await h.close();
+    }
+  });
+});
+
+describe('slides_add_<component> — schema-introspection tools', () => {
+  test('valid props echo back as a slide spec', async () => {
+    const h = await makeHarness();
+    try {
+      const result = await h.client.callTool({
+        name: 'slides_add_cover',
+        arguments: { title: 'Q2 Review' },
+      });
+      expect(result.isError).toBeFalsy();
+      expect(result.structuredContent).toEqual({
+        slide: { component: 'Cover', props: { title: 'Q2 Review' } },
+      });
+    } finally {
+      await h.close();
+    }
+  });
+});
+
+describe('slides_create', () => {
+  test('happy path: writes a .pptx file and returns the absolute path', async () => {
+    const h = await makeHarness();
+    try {
+      const result = await h.client.callTool({
+        name: 'slides_create',
+        arguments: {
+          title: 'Pitch Deck',
+          slides: [
+            { component: 'Cover', props: { title: 'Hello', subtitle: 'world' } },
+            { component: 'TwoColumn', props: { left: 'A', right: 'B' } },
+          ],
+        },
+      });
+      expect(result.isError).toBeFalsy();
+      const sc = result.structuredContent as { filePath: string; slideCount: number };
+      expect(sc.slideCount).toBe(2);
+      expect(sc.filePath).toMatch(/Pitch-Deck\.pptx$/);
+      const buf = await fs.readFile(sc.filePath);
+      // PPTX is a ZIP container. Check magic number.
+      expect(buf[0]).toBe(0x50);
+      expect(buf[1]).toBe(0x4b);
+    } finally {
+      await h.close();
+    }
+  });
+
+  test('error path: invalid props surface field paths and a re-call hint', async () => {
+    const h = await makeHarness();
+    try {
+      const result = await h.client.callTool({
+        name: 'slides_create',
+        arguments: {
+          title: 'X',
+          slides: [{ component: 'Cover', props: { subtitle: 'foo' } }],
+        },
+      });
+      expect(result.isError).toBe(true);
+      const sc = result.structuredContent as {
+        error: { code: string; message: string; issues: Array<{ path: string }> };
+      };
+      expect(sc.error.code).toBe('validation_error');
+      expect(sc.error.message).toMatch(/slides\[0\]/);
+      expect(sc.error.message).toMatch(/title/);
+      expect(sc.error.message).toMatch(/Fix the listed fields and retry/);
+      expect(sc.error.issues.some((i) => i.path === 'title')).toBe(true);
+    } finally {
+      await h.close();
+    }
+  });
+
+  test('error path: unknown component name lists known options and points at slides_list', async () => {
+    const h = await makeHarness();
+    try {
+      const result = await h.client.callTool({
+        name: 'slides_create',
+        arguments: {
+          title: 'X',
+          slides: [{ component: 'NonExistent', props: {} }],
+        },
+      });
+      expect(result.isError).toBe(true);
+      const sc = result.structuredContent as { error: { code: string; message: string } };
+      expect(sc.error.code).toBe('unknown_component');
+      expect(sc.error.message).toMatch(/NonExistent/);
+      expect(sc.error.message).toMatch(/Cover/);
+      expect(sc.error.message).toMatch(/TwoColumn/);
+      expect(sc.error.message).toMatch(/slides_list/);
+    } finally {
+      await h.close();
+    }
+  });
+
+  test('strict()-rejected unknown props produce a validation error', async () => {
+    const h = await makeHarness();
+    try {
+      const result = await h.client.callTool({
+        name: 'slides_create',
+        arguments: {
+          title: 'X',
+          slides: [{ component: 'Cover', props: { title: 'OK', rogueColor: '#ff00ff' } }],
+        },
+      });
+      expect(result.isError).toBe(true);
+      const sc = result.structuredContent as { error: { code: string } };
+      expect(sc.error.code).toBe('validation_error');
+    } finally {
+      await h.close();
+    }
+  });
+});

package/src/mcp/server.ts

@@ -0,0 +1,276 @@
+/**
+ * The template-agnostic MCP server framework.
+ *
+ * createSlideServer({ template, runtime }) builds an McpServer that exposes
+ * three kinds of tools:
+ *
+ * 1. **`slides_list`** — returns the list of slide types the loaded template
+ *    supports, with descriptions. One round-trip to discover the surface.
+ *
+ * 2. **One tool per slide type**, named `<toolPrefix><snake_case>` (default
+ *    prefix `slides_add_`). Validates user-supplied props against the
+ *    component's Zod schema and echoes them back as a slide spec. Used
+ *    iteratively by an LLM to assemble a deck before calling `slides_create`.
+ *
+ * 3. **`slides_create`** — full pipeline. Takes `{ title, slides }`, renders
+ *    via the reconciler, applies through the PPTX runtime, writes the .pptx
+ *    file to disk, and returns the path.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { z } from 'zod';
+import type { ZodError } from 'zod';
+import type { SlidesRuntime, Template } from '../core/index.js';
+import { errorResult, zodErrorResult } from './errors.js';
+import { renderSlides } from './render.js';
+import { deriveComponentTools, type DerivedTool } from './schema.js';
+
+/** Configuration accepted by createSlideServer. */
+export interface SlideServerConfig {
+  /** The template (component vocabulary + tokens) the server exposes. */
+  readonly template: Template;
+  /** The PPTX runtime used to materialize presentations. */
+  readonly runtime: SlidesRuntime;
+  /**
+   * Override the server's reported name/version. Defaults to a name derived
+   * from the template and version `'0.1.0'`.
+   */
+  readonly serverInfo?: { readonly name: string; readonly version: string };
+  /**
+   * Override the per-slide-type tool-name prefix. Default: `'slides_add_'`.
+   * Use this when the server emits something other than slide decks (a
+   * report-builder might use `'report_add_'`, etc.).
+   */
+  readonly toolPrefix?: string;
+}
+
+/** Options accepted by server.start. */
+export type StartOptions = { readonly transport: 'stdio' };
+
+/** The handle returned by createSlideServer. */
+export interface SlideServer {
+  /** The underlying MCP server. Exposed for advanced callers. */
+  readonly mcp: McpServer;
+  /** Tool definitions derived from the template. */
+  readonly tools: ReadonlyArray<DerivedTool>;
+  /** Connect to the given transport. Lower-level than start. */
+  connect(transport: Transport): Promise<void>;
+  /** Start serving over the configured transport. */
+  start(options: StartOptions): Promise<void>;
+  /** Close the server and disconnect any active transport. */
+  close(): Promise<void>;
+}
+
+/** Construct a template-locked MCP server. */
+export const createSlideServer = (config: SlideServerConfig): SlideServer => {
+  const { template, runtime } = config;
+  const serverInfo = config.serverInfo ?? {
+    name: 'react-pptx-mcp:' + template.name,
+    version: '0.1.0',
+  };
+
+  const mcp = new McpServer(serverInfo);
+  const tools = deriveComponentTools(template, config.toolPrefix);
+
+  registerListTool(mcp, template, tools);
+  registerComponentTools(mcp, tools);
+  registerCreateTool(mcp, runtime, template);
+
+  return {
+    mcp,
+    tools,
+    connect: (transport) => mcp.connect(transport),
+    start: async (options) => {
+      switch (options.transport) {
+        case 'stdio': {
+          await mcp.connect(new StdioServerTransport());
+          return;
+        }
+      }
+    },
+    close: () => mcp.close(),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// slides_list
+// ---------------------------------------------------------------------------
+
+const LIST_OUTPUT_SHAPE = {
+  template: z.string().describe('The name of the loaded template.'),
+  slides: z
+    .array(
+      z.object({
+        name: z.string().describe('Slide-type name, e.g. "Cover".'),
+        toolName: z.string().describe('MCP tool name for this slide type.'),
+        description: z.string().describe('When to use this slide type.'),
+      }),
+    )
+    .describe('Every slide type the template exposes.'),
+};
+
+const registerListTool = (
+  mcp: McpServer,
+  template: Template,
+  tools: ReadonlyArray<DerivedTool>,
+): void => {
+  mcp.registerTool(
+    'slides_list',
+    {
+      description:
+        'List every slide type this template supports, with descriptions and the per-type tool names. ' +
+        'Call once at the start of a deck-building session to learn the surface.',
+      outputSchema: LIST_OUTPUT_SHAPE,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      const slides = tools.map((t) => ({
+        name: t.componentName,
+        toolName: t.name,
+        description: t.description,
+      }));
+      const lines = [
+        `Template: ${template.name}`,
+        '',
+        'Available slide types:',
+        ...slides.map((s) => `  • ${s.name} (${s.toolName}) — ${s.description}`),
+        '',
+        'Call slides_add_<type> to validate a single slide. ' +
+          'Call slides_create with an array of slide specs to write a .pptx file.',
+      ].join('\n');
+      return {
+        content: [{ type: 'text' as const, text: lines }],
+        structuredContent: { template: template.name, slides },
+      };
+    },
+  );
+};
+
+// ---------------------------------------------------------------------------
+// slides_add_<component>
+// ---------------------------------------------------------------------------
+
+const COMPONENT_OUTPUT_SHAPE = {
+  slide: z
+    .object({
+      component: z.string(),
+      props: z.record(z.unknown()),
+    })
+    .describe('A single validated slide spec, ready to be passed to slides_create.'),
+};
+
+const registerComponentTools = (mcp: McpServer, tools: readonly DerivedTool[]): void => {
+  for (const tool of tools) {
+    mcp.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputShape,
+        outputSchema: COMPONENT_OUTPUT_SHAPE,
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false,
+        },
+      },
+      async (rawProps) => {
+        const parsed = tool.inputSchema.safeParse(rawProps);
+        if (!parsed.success) {
+          return zodErrorResult(
+            `Validation error in ${tool.name} props:`,
+            parsed.error as ZodError,
+            "Refer to this tool's input schema and retry.",
+          );
+        }
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text:
+                `Validated ${tool.componentName} props. ` +
+                `Pass { component: "${tool.componentName}", props: <these> } ` +
+                `as one entry of slides_create.slides.`,
+            },
+          ],
+          structuredContent: {
+            slide: { component: tool.componentName, props: parsed.data },
+          },
+        };
+      },
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// slides_create
+// ---------------------------------------------------------------------------
+
+const SLIDE_SPEC_SCHEMA = z
+  .object({
+    component: z.string().min(1).describe('The slide-type name, e.g. "Cover".'),
+    props: z
+      .record(z.unknown())
+      .describe("Props matching that slide type's input schema (see slides_add_<type>)."),
+  })
+  .describe('One slide to add. Same shape as the structuredContent of slides_add_<type>.');
+
+const CREATE_INPUT_SHAPE = {
+  title: z.string().min(1).describe('Deck title — used as the .pptx filename stem.'),
+  slides: z.array(SLIDE_SPEC_SCHEMA).min(1).describe('The slides to write, in order.'),
+};
+
+const CREATE_OUTPUT_SHAPE = {
+  filePath: z.string().describe('Absolute path to the generated .pptx file.'),
+  slideCount: z.number().int().nonnegative(),
+};
+
+const registerCreateTool = (mcp: McpServer, runtime: SlidesRuntime, template: Template): void => {
+  mcp.registerTool(
+    'slides_create',
+    {
+      description:
+        'Generate a template-locked .pptx presentation from a sequence of slide specs and write it to disk. ' +
+        'Returns the absolute file path. Each spec is { component, props } — ' +
+        'use the per-type slides_add_<type> tools first to discover schemas and validate props.',
+      inputSchema: CREATE_INPUT_SHAPE,
+      outputSchema: CREATE_OUTPUT_SHAPE,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (input) => {
+      const result = await renderSlides({
+        template,
+        runtime,
+        title: input.title,
+        slides: input.slides,
+      });
+      if (result.ok) {
+        const slideWord = result.slideCount === 1 ? 'slide' : 'slides';
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Wrote ${result.slideCount} ${slideWord} to ${result.filePath}.`,
+            },
+          ],
+          structuredContent: { filePath: result.filePath, slideCount: result.slideCount },
+        };
+      }
+      const hint =
+        result.code === 'validation_error' ? ' Fix the listed fields and retry slides_create.' : '';
+      return errorResult(result.code, result.message + hint, result.issues);
+    },
+  );
+};

package/src/scaffold/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Programmatic scaffolder. The `slidesctl scaffold <dir>` subcommand wraps
+ * this; the same API is exposed at `@sanity-labs/slides/scaffold` so it can
+ * be driven by other tooling.
+ *
+ * The scaffold stamps every file under `template-base/` into the target
+ * directory, applying `__NAME__` / `__IDENT__` substitutions and renaming
+ * the `_gitignore` placeholder back to `.gitignore`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_BASE = resolvePath(HERE, 'template-base');
+
+export type ScaffoldOptions = {
+  /** Target directory; created if missing. Must be empty if it exists. */
+  readonly target: string;
+  /** Template name (used as the package name + Template `name` field). */
+  readonly name: string;
+};
+
+export type ScaffoldResult = {
+  readonly targetPath: string;
+  readonly fileCount: number;
+};
+
+/**
+ * Stamp the template-base into `target`, applying the substitutions.
+ *
+ * Throws if `target` exists and is non-empty.
+ */
+export const scaffoldTemplate = (options: ScaffoldOptions): ScaffoldResult => {
+  const targetPath = resolvePath(process.cwd(), options.target);
+  if (existsSync(targetPath) && readdirSync(targetPath).length > 0) {
+    throw new Error(`Target directory "${targetPath}" already exists and is not empty.`);
+  }
+  copyTemplate(TEMPLATE_BASE, targetPath, {
+    __NAME__: options.name,
+    __IDENT__: toIdentifier(options.name),
+  });
+  return { targetPath, fileCount: countFiles(targetPath) };
+};
+
+/**
+ * Convert a kebab-case template name into a camelCase JS identifier. Used
+ * as the `__IDENT__` substitution in stamped files (e.g. the exported
+ * `Template` const).
+ */
+export const toIdentifier = (name: string): string =>
+  name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
+/**
+ * Validate a template name. Returns an error message string when invalid,
+ * `undefined` when ok. Used by interactive prompts.
+ */
+export const validateName = (value: string): string | undefined => {
+  if (!value) return 'Required';
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+    return 'Must start with a letter or digit and contain only [a-z0-9-].';
+  }
+  return undefined;
+};
+
+/** Infer a default template name from a target path. */
+export const defaultName = (target: string): string => {
+  const last = (target ?? './my-template').split('/').filter(Boolean).pop() ?? 'my-template';
+  return last.replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+};
+
+const copyTemplate = (src: string, dst: string, replacements: Record<string, string>): void => {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcEntry = join(src, entry);
+    const dstEntry = join(dst, denormaliseFilename(entry));
+    if (statSync(srcEntry).isDirectory()) {
+      copyTemplate(srcEntry, dstEntry, replacements);
+      continue;
+    }
+    writeFileSync(dstEntry, applyReplacements(readFileSync(srcEntry, 'utf8'), replacements));
+  }
+};
+
+const denormaliseFilename = (name: string): string => (name === '_gitignore' ? '.gitignore' : name);
+
+const applyReplacements = (content: string, replacements: Record<string, string>): string => {
+  let out = content;
+  for (const [from, to] of Object.entries(replacements)) out = out.split(from).join(to);
+  return out;
+};
+
+const countFiles = (dir: string): number => {
+  let n = 0;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) n += countFiles(full);
+    else n += 1;
+  }
+  return n;
+};