@blueprint-chart/mcp 0.1.0 → 0.1.3

package/dist/server.test.js

@@ -1,8 +1,8 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { samples } from '@blueprint-chart/lib';
-import { createServer } from './server';
+import { createServer, TOOLS } from './server';
 async function connectInMemory() {
     const server = createServer();
     const [clientT, serverT] = InMemoryTransport.createLinkedPair();
@@ -11,12 +11,56 @@ async function connectInMemory() {
     await client.connect(clientT);
     return { client, server };
 }
+describe('TOOLS registry', () => {
+    it('contains the nine expected tool names', () => {
+        expect(Object.keys(TOOLS).sort()).toEqual([
+            'describe_chart_type',
+            'export_chart',
+            'get_example',
+            'get_grammar',
+            'inspect_dsl',
+            'list_chart_types',
+            'recommend_chart_type',
+            'render',
+            'validate_dsl',
+        ]);
+    });
+});
 describe('server', () => {
-    it('lists 4 tools', async () => {
+    it('lists 9 tools', async () => {
         const { client } = await connectInMemory();
         const r = await client.listTools();
         const names = r.tools.map(t => t.name).sort();
-        expect(names).toEqual(['inspect_dsl', 'recommend_chart_type', 'render', 'validate_dsl']);
+        expect(names).toEqual([
+            'describe_chart_type',
+            'export_chart',
+            'get_example',
+            'get_grammar',
+            'inspect_dsl',
+            'list_chart_types',
+            'recommend_chart_type',
+            'render',
+            'validate_dsl',
+        ]);
+    });
+    it('publishes JSON Schemas with concrete properties (not a permissive stub)', async () => {
+        const { client } = await connectInMemory();
+        const r = await client.listTools();
+        for (const tool of r.tools) {
+            const schema = tool.inputSchema;
+            expect(schema.type, `${tool.name}: schema.type`).toBe('object');
+            // Discovery tools like list_chart_types take no params — their `properties`
+            // object exists but is empty. Every other tool has at least one property.
+            expect(schema.properties, `${tool.name}: schema.properties`).toBeDefined();
+        }
+        const validate = r.tools.find(t => t.name === 'validate_dsl');
+        const validateSchema = validate.inputSchema;
+        expect(validateSchema.properties.source).toBeDefined();
+        expect(validateSchema.required).toEqual(['source']);
+        const render = r.tools.find(t => t.name === 'render');
+        const renderSchema = render.inputSchema;
+        expect(renderSchema.properties.format).toBeDefined();
+        expect(renderSchema.properties.save).toBeDefined();
     });
     it('calls validate_dsl successfully for a sample', async () => {
         const { client } = await connectInMemory();
@@ -58,6 +102,32 @@ describe('server', () => {
         const first = r.contents[0];
         expect(first.text).toMatch(/chart\s+\w/);
     });
+    describe('serverInfo metadata', () => {
+        afterEach(() => {
+            vi.unstubAllEnvs();
+        });
+        it('always advertises title + dynamic version', async () => {
+            vi.stubEnv('MCP_PUBLIC_URL', '');
+            const { client } = await connectInMemory();
+            const info = client.getServerVersion();
+            expect(info?.title).toBe('Blueprint Chart');
+            expect(info?.version).toMatch(/^\d+\.\d+\.\d+/);
+        });
+        it('omits icons when MCP_PUBLIC_URL is unset (stdio / local use)', async () => {
+            vi.stubEnv('MCP_PUBLIC_URL', '');
+            const { client } = await connectInMemory();
+            expect(client.getServerVersion()?.icons).toBeUndefined();
+        });
+        it('advertises absolute-URL icons when MCP_PUBLIC_URL is set', async () => {
+            vi.stubEnv('MCP_PUBLIC_URL', 'https://mcp.example.com/');
+            const { client } = await connectInMemory();
+            const icons = client.getServerVersion()?.icons;
+            expect(icons).toEqual([
+                { src: 'https://mcp.example.com/favicon.svg', mimeType: 'image/svg+xml' },
+                { src: 'https://mcp.example.com/favicon.png', mimeType: 'image/png', sizes: ['256x256'] },
+            ]);
+        });
+    });
     it('exposes author_chart prompt', async () => {
         const { client } = await connectInMemory();
         const prompts = await client.listPrompts();
@@ -65,4 +135,31 @@ describe('server', () => {
         const got = await client.getPrompt({ name: 'author_chart' });
         expect(got.messages.length).toBeGreaterThan(0);
     });
+    describe('export_chart', () => {
+        const VALID_SOURCE = 'chart bar-vertical {\n  data {\n    "A" = 1\n  }\n}\n';
+        afterEach(() => {
+            delete process.env.BLUEPRINT_CHART_EDITOR_URL;
+        });
+        it('appears in tools/list with an object-type inputSchema', async () => {
+            const { client } = await connectInMemory();
+            const r = await client.listTools();
+            const tool = r.tools.find(t => t.name === 'export_chart');
+            expect(tool).toBeDefined();
+            expect(tool.inputSchema.type).toBe('object');
+        });
+        it('returns E_CONFIG when BLUEPRINT_CHART_EDITOR_URL is unset', async () => {
+            delete process.env.BLUEPRINT_CHART_EDITOR_URL;
+            const { client } = await connectInMemory();
+            const res = await client.callTool({ name: 'export_chart', arguments: { source: VALID_SOURCE } });
+            expect(res.isError).toBe(true);
+            expect(JSON.stringify(res.content)).toMatch(/E_CONFIG/);
+        });
+        it('returns copyUrl with #/copy?bpc64= when BLUEPRINT_CHART_EDITOR_URL is set', async () => {
+            process.env.BLUEPRINT_CHART_EDITOR_URL = 'https://blueprintchart.com';
+            const { client } = await connectInMemory();
+            const res = await client.callTool({ name: 'export_chart', arguments: { source: VALID_SOURCE } });
+            expect(res.isError).toBeFalsy();
+            expect(JSON.stringify(res.content)).toMatch(/#\/copy\?bpc64=/);
+        });
+    });
 });

package/dist/tools/describeChartType.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const DescribeChartTypeInputSchema: z.ZodObject<{
+    chartType: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    chartType: string;
+}, {
+    chartType: string;
+}>;
+export type DescribeChartTypeInput = z.infer<typeof DescribeChartTypeInputSchema>;
+export interface ChartTypeProperty {
+    key: string;
+    type: string;
+    description?: string;
+    choices?: string[];
+    default?: unknown;
+}
+export interface ChartTypeDataShape {
+    kind: 'single-series' | 'multi-series' | 'unknown';
+    example: string;
+}
+export interface DescribeChartTypeOutput {
+    name: string;
+    aliases: string[];
+    summary: string;
+    whenToUse: string[];
+    whenNotToUse: string[];
+    properties: ChartTypeProperty[];
+    dataShape: ChartTypeDataShape;
+    exampleSlug?: string;
+    docsUrl?: string;
+}
+export declare function describeChartType(input: unknown): ToolResult<DescribeChartTypeOutput>;

package/dist/tools/describeChartType.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import { getChartOptions, samples } from '@blueprint-chart/lib';
+import { getDoc, listDocs } from '@blueprint-chart/docs';
+import { aliasesFor, canonicalChartType, listCanonicalChartTypes } from '../dsl/chartTypes';
+import { nearestSuggestion } from '../dsl/suggest';
+import { UNIVERSAL_PROPERTIES, UNIVERSAL_PROPERTY_META } from '../dsl/universalProperties';
+import { ErrorCode, toolError, toolOk } from '../errors';
+import { publicDocUrl } from '../resources/docsReader';
+export const DescribeChartTypeInputSchema = z.object({
+    chartType: z.string(),
+}).strict();
+function extractDocSections(name) {
+    const entries = listDocs('charts');
+    const entry = entries.find(e => e.slug === name);
+    if (!entry) {
+        return { summary: '', whenToUse: [], whenNotToUse: [], example: '' };
+    }
+    let content;
+    try {
+        content = getDoc('charts', name).content;
+    }
+    catch {
+        return { summary: '', whenToUse: [], whenNotToUse: [], example: '' };
+    }
+    const summary = content.match(/^>\s*(.+)$/m)?.[1]?.trim() ?? '';
+    const sectionBullets = (heading) => {
+        const re = new RegExp(`##\\s+${heading}[\\s\\S]*?(?=^##\\s+|\\Z)`, 'm');
+        const block = content.match(re)?.[0] ?? '';
+        return Array.from(block.matchAll(/^-\s+(.+)$/gm)).map(m => m[1].trim());
+    };
+    const example = content.match(/```bpc\n([\s\S]*?)```/)?.[1]?.trim() ?? '';
+    return {
+        summary,
+        whenToUse: sectionBullets('When to use'),
+        whenNotToUse: sectionBullets('When NOT to use'),
+        example,
+    };
+}
+function mapOption(opt) {
+    const prop = {
+        key: opt.key,
+        type: String(opt.type),
+    };
+    if (opt.label) {
+        prop.description = opt.label;
+    }
+    if (opt.choices !== undefined && opt.choices.length > 0) {
+        prop.choices = opt.choices.map(c => String(c.value));
+    }
+    if (opt.default !== undefined) {
+        prop.default = opt.default;
+    }
+    return prop;
+}
+function buildProperties(canonical) {
+    const registeredOptions = getChartOptions(canonical);
+    const registeredKeys = new Set(registeredOptions.map(o => o.key));
+    const props = registeredOptions.map(mapOption);
+    // Merge in universal properties that are not already present in the
+    // per-type registry. This ensures discoverable properties like `sort`,
+    // `title`, and `colors` appear for every chart type.
+    for (const key of UNIVERSAL_PROPERTIES) {
+        if (!registeredKeys.has(key)) {
+            const meta = UNIVERSAL_PROPERTY_META[key];
+            if (meta) {
+                props.push({ key, ...meta });
+            }
+            else {
+                props.push({ key, type: 'text' });
+            }
+        }
+    }
+    return props;
+}
+function inferDataShape(name, example) {
+    if (example.includes('_series')) {
+        return { kind: 'multi-series', example };
+    }
+    if (example.includes('data')) {
+        return { kind: 'single-series', example };
+    }
+    return { kind: 'unknown', example: 'data {\n  "Label" = 1.0\n}' };
+}
+export function describeChartType(input) {
+    const parsed = DescribeChartTypeInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    }
+    const canonical = canonicalChartType(parsed.data.chartType);
+    if (!canonical) {
+        const known = listCanonicalChartTypes();
+        return toolError(ErrorCode.E_INPUT, [{
+                code: 'E_UNKNOWN_CHART_TYPE',
+                path: 'chartType',
+                message: `Unknown chart type "${parsed.data.chartType}". Known types: ${known.join(', ')}.`,
+                suggestion: nearestSuggestion(parsed.data.chartType, known),
+                context: { got: parsed.data.chartType, known },
+            }]);
+    }
+    const doc = extractDocSections(canonical);
+    const properties = buildProperties(canonical);
+    const sample = samples.find(s => s.chartType === canonical);
+    const exampleText = doc.example || sample?.dsl || '';
+    const output = {
+        name: canonical,
+        aliases: aliasesFor(canonical),
+        summary: doc.summary,
+        whenToUse: doc.whenToUse,
+        whenNotToUse: doc.whenNotToUse,
+        properties,
+        dataShape: inferDataShape(canonical, exampleText),
+        exampleSlug: sample?.id,
+    };
+    const docsUrl = publicDocUrl('charts', canonical);
+    if (docsUrl) {
+        output.docsUrl = docsUrl;
+    }
+    return toolOk(output);
+}

package/dist/tools/describeChartType.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/describeChartType.test.js

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { describeChartType } from './describeChartType';
+describe('describe_chart_type', () => {
+    afterEach(() => {
+        delete process.env.BLUEPRINT_CHART_DOCS_URL;
+    });
+    it('returns properties + summary for bar-horizontal', () => {
+        const r = describeChartType({ chartType: 'bar-horizontal' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.name).toBe('bar-horizontal');
+            expect(r.data.aliases).toContain('horizontal-bar');
+            expect(r.data.summary.length).toBeGreaterThan(0);
+            expect(r.data.properties.length).toBeGreaterThan(0);
+            const sort = r.data.properties.find(p => p.key === 'sort');
+            expect(sort).toBeDefined();
+            expect(sort?.type).toBeDefined();
+        }
+    });
+    it('accepts an alias and normalizes', () => {
+        const r = describeChartType({ chartType: 'horizontal-bar' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.name).toBe('bar-horizontal');
+        }
+    });
+    it('errors with structured suggestion on unknown name', () => {
+        const r = describeChartType({ chartType: 'bar' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.errors[0].code).toBe('E_UNKNOWN_CHART_TYPE');
+            expect(r.errors[0].suggestion).toMatch(/^bar-/);
+        }
+    });
+    it('includes a starter dataShape example', () => {
+        const r = describeChartType({ chartType: 'bar-vertical' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.dataShape.kind).toMatch(/single-series|multi-series/);
+            expect(r.data.dataShape.example).toContain('data');
+        }
+    });
+    it('omits docsUrl when docs base is unset', () => {
+        const result = describeChartType({ chartType: 'bar-vertical' });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.docsUrl).toBeUndefined();
+        }
+    });
+    it('includes a top-level docsUrl when docs base is set', () => {
+        process.env.BLUEPRINT_CHART_DOCS_URL = 'https://docs.blueprintchart.com';
+        const result = describeChartType({ chartType: 'bar-vertical' });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.docsUrl).toBe('https://docs.blueprintchart.com/charts/bar-vertical');
+        }
+    });
+});

package/dist/tools/exportChart.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { type FrameMetadata } from '../render/frame';
+import { type ToolResult } from '../errors';
+export declare const ExportChartInputSchema: z.ZodObject<{
+    source: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    source: string;
+}, {
+    source: string;
+}>;
+export type ExportChartInput = z.infer<typeof ExportChartInputSchema>;
+export interface ExportChartOutput {
+    copyUrl: string;
+    embedUrl: string;
+    frame: FrameMetadata;
+}
+export declare function exportChart(input: unknown): ToolResult<ExportChartOutput>;

package/dist/tools/exportChart.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { getEditorBaseUrl } from '../links/editorConfig';
+import { buildCopyUrl, buildEmbedUrl } from '../links/buildUrls';
+import { validatePipeline } from '../render/validatePipeline';
+import { extractFrameMetadata } from '../render/frame';
+import { ErrorCode, toolError, toolOk } from '../errors';
+export const ExportChartInputSchema = z.object({
+    source: z.string(),
+}).strict();
+export function exportChart(input) {
+    const parsed = ExportChartInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    }
+    const editorBase = getEditorBaseUrl();
+    if (!editorBase) {
+        return toolError(ErrorCode.E_CONFIG, [{
+                code: 'E_EDITOR_URL_UNSET',
+                message: 'Link export is not configured. Set BLUEPRINT_CHART_EDITOR_URL to enable.',
+            }]);
+    }
+    const validated = validatePipeline(parsed.data.source);
+    if (!validated.ok) {
+        return validated.error;
+    }
+    return toolOk({
+        copyUrl: buildCopyUrl(parsed.data.source, editorBase),
+        embedUrl: buildEmbedUrl(parsed.data.source, editorBase),
+        frame: extractFrameMetadata(validated.ast),
+    });
+}

package/dist/tools/exportChart.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/exportChart.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { exportChart } from './exportChart';
+import { ErrorCode } from '../errors';
+const VALID = 'chart bar-vertical {\n  title = "Hi"\n  data {\n    "A" = 1\n  }\n}\n';
+afterEach(() => {
+    delete process.env.BLUEPRINT_CHART_EDITOR_URL;
+});
+describe('exportChart', () => {
+    it('returns E_CONFIG when the editor base URL is unset', () => {
+        const result = exportChart({ source: VALID });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.code).toBe(ErrorCode.E_CONFIG);
+            expect(result.errors[0]?.message).toMatch(/BLUEPRINT_CHART_EDITOR_URL/);
+        }
+    });
+    it('returns E_INPUT when source is missing', () => {
+        process.env.BLUEPRINT_CHART_EDITOR_URL = 'https://blueprintchart.com';
+        const result = exportChart({});
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.code).toBe(ErrorCode.E_INPUT);
+        }
+    });
+    it('propagates E_PARSE from the shared validation pipeline', () => {
+        process.env.BLUEPRINT_CHART_EDITOR_URL = 'https://blueprintchart.com';
+        const result = exportChart({ source: 'chart bar-vertical {' });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.code).toBe(ErrorCode.E_PARSE);
+        }
+    });
+    it('returns copy + embed URLs and frame for a valid source', () => {
+        process.env.BLUEPRINT_CHART_EDITOR_URL = 'https://blueprintchart.com';
+        const result = exportChart({ source: VALID });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.copyUrl).toMatch(/^https:\/\/blueprintchart\.com\/#\/copy\?bpc64=/);
+            expect(result.data.embedUrl).toMatch(/^https:\/\/blueprintchart\.com\/#\/render\?bpc64=/);
+            expect(result.data.frame.title).toBe('Hi');
+        }
+    });
+});

package/dist/tools/getExample.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const GetExampleInputSchema: z.ZodObject<{
+    chartType: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    name?: string | undefined;
+    chartType?: string | undefined;
+}, {
+    name?: string | undefined;
+    chartType?: string | undefined;
+}>;
+export type GetExampleInput = z.infer<typeof GetExampleInputSchema>;
+export interface GetExampleOutput {
+    id: string;
+    title: string;
+    chartType: string;
+    dsl: string;
+}
+export declare function getExample(input: unknown): ToolResult<GetExampleOutput>;

package/dist/tools/getExample.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { samples } from '@blueprint-chart/lib';
+import { canonicalChartType } from '../dsl/chartTypes';
+import { ErrorCode, toolError, toolOk } from '../errors';
+export const GetExampleInputSchema = z.object({
+    chartType: z.string().optional(),
+    name: z.string().optional(),
+}).strict();
+const STARTER_SAMPLE_ID = 'letter-frequency';
+export function getExample(input) {
+    const parsed = GetExampleInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    }
+    const { chartType, name } = parsed.data;
+    if (name) {
+        const found = samples.find(s => s.id === name);
+        if (!found) {
+            return toolError(ErrorCode.E_INPUT, [{
+                    code: 'E_UNKNOWN_SAMPLE',
+                    path: 'name',
+                    message: `No sample with id "${name}". Try one of: ${samples.map(s => s.id).join(', ')}.`,
+                    context: { knownIds: samples.map(s => s.id) },
+                }]);
+        }
+        return toolOk({ id: found.id, title: found.title, chartType: found.chartType, dsl: found.dsl });
+    }
+    if (chartType) {
+        const canonical = canonicalChartType(chartType);
+        if (!canonical) {
+            return toolError(ErrorCode.E_INPUT, [{
+                    code: 'E_UNKNOWN_CHART_TYPE',
+                    path: 'chartType',
+                    message: `Unknown chart type "${chartType}".`,
+                    context: { got: chartType },
+                }]);
+        }
+        const found = samples.find(s => s.chartType === canonical);
+        if (!found) {
+            return toolError(ErrorCode.E_INPUT, [{
+                    code: 'E_NO_SAMPLE_FOR_TYPE',
+                    path: 'chartType',
+                    message: `No sample is shipped for chart type "${canonical}".`,
+                }]);
+        }
+        return toolOk({ id: found.id, title: found.title, chartType: found.chartType, dsl: found.dsl });
+    }
+    const starter = samples.find(s => s.id === STARTER_SAMPLE_ID) ?? samples[0];
+    if (!starter) {
+        return toolError(ErrorCode.E_INTERNAL, [{
+                message: 'No samples available — lib export is empty.',
+            }]);
+    }
+    return toolOk({ id: starter.id, title: starter.title, chartType: starter.chartType, dsl: starter.dsl });
+}

package/dist/tools/getExample.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/getExample.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { getExample } from './getExample';
+describe('get_example', () => {
+    it('returns the starter sample when no args', () => {
+        const r = getExample({});
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.id).toBe('letter-frequency');
+            expect(r.data.dsl).toContain('chart bar-vertical');
+        }
+    });
+    it('returns a sample by id', () => {
+        const r = getExample({ name: 'letter-frequency' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.chartType).toBe('bar-vertical');
+        }
+    });
+    it('returns the first matching sample for a chartType', () => {
+        const r = getExample({ chartType: 'bar-horizontal' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.chartType).toBe('bar-horizontal');
+        }
+    });
+    it('errors with E_INPUT for an unknown id', () => {
+        const r = getExample({ name: 'made-up-sample' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+        }
+    });
+    it('errors with E_INPUT for an unknown chart type', () => {
+        const r = getExample({ chartType: 'bar' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+        }
+    });
+});

package/dist/tools/getGrammar.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+declare const SectionSchema: z.ZodDefault<z.ZodEnum<["all", "chart", "properties", "scenes", "annotations"]>>;
+export declare const GetGrammarInputSchema: z.ZodObject<{
+    section: z.ZodOptional<z.ZodDefault<z.ZodEnum<["all", "chart", "properties", "scenes", "annotations"]>>>;
+}, "strict", z.ZodTypeAny, {
+    section?: "chart" | "all" | "properties" | "scenes" | "annotations" | undefined;
+}, {
+    section?: "chart" | "all" | "properties" | "scenes" | "annotations" | undefined;
+}>;
+export type GetGrammarInput = z.infer<typeof GetGrammarInputSchema>;
+export interface GetGrammarOutput {
+    section: z.infer<typeof SectionSchema>;
+    text: string;
+}
+export declare function getGrammar(input: unknown): ToolResult<GetGrammarOutput>;
+export {};

package/dist/tools/getGrammar.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { getDoc, listDocs } from '@blueprint-chart/docs';
+import { ErrorCode, toolError, toolOk } from '../errors';
+const SectionSchema = z.enum(['all', 'chart', 'properties', 'scenes', 'annotations']).default('all');
+export const GetGrammarInputSchema = z.object({
+    section: SectionSchema.optional(),
+}).strict();
+const SECTION_TO_SLUG = {
+    chart: 'index',
+    properties: 'properties',
+    scenes: 'scenes-and-transforms',
+    annotations: 'annotations',
+};
+export function getGrammar(input) {
+    const parsed = GetGrammarInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    }
+    const section = parsed.data.section ?? 'all';
+    if (section === 'all') {
+        const pages = listDocs('reference/dsl');
+        const text = pages.map((entry) => {
+            const { content } = getDoc('reference/dsl', entry.slug);
+            return `# ${entry.title}\n\n${content}`;
+        }).join('\n\n---\n\n');
+        return toolOk({ section: 'all', text });
+    }
+    const slug = SECTION_TO_SLUG[section];
+    try {
+        const { content } = getDoc('reference/dsl', slug);
+        return toolOk({ section, text: content });
+    }
+    catch (err) {
+        return toolError(ErrorCode.E_INPUT, [{
+                message: `Grammar section "${section}" not found: ${err instanceof Error ? err.message : String(err)}`,
+            }]);
+    }
+}

package/dist/tools/getGrammar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/getGrammar.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { getGrammar } from './getGrammar';
+describe('get_grammar', () => {
+    it('returns the full grammar by default', () => {
+        const r = getGrammar({});
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.section).toBe('all');
+            expect(r.data.text.length).toBeGreaterThan(100);
+        }
+    });
+    it('returns a single section when requested', () => {
+        const r = getGrammar({ section: 'properties' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.section).toBe('properties');
+            expect(r.data.text.toLowerCase()).toContain('properties');
+        }
+    });
+    it('errors with E_INPUT for an unknown section', () => {
+        const r = getGrammar({ section: 'totally-made-up' });
+        expect(r.ok).toBe(false);
+    });
+});