@blueprint-chart/mcp 0.1.1 → 0.1.4

package/dist/tools/inspect.test.js

@@ -2,28 +2,77 @@ import { describe, expect, it } from 'vitest';
 import { samples } from '@blueprint-chart/lib';
 import { inspectDsl } from './inspect';
 describe('inspect_dsl', () => {
-    it('returns chartType + scene summary for a sample', () => {
-        const sample = samples[0];
-        const r = inspectDsl({ source: sample.dsl });
-        expect(r.ok).toBe(true);
-        if (r.ok) {
-            expect(r.data.chartType).toBe(sample.chartType);
-            expect(Array.isArray(r.data.scenes)).toBe(true);
-            expect(r.data.seriesCount).toBeGreaterThanOrEqual(0);
-            expect(r.data.rowCount).toBeGreaterThanOrEqual(0);
-        }
-    });
-    it('returns at least one scene for every shipped sample', () => {
+    it('returns chartType + data summary for every sample', () => {
         for (const s of samples) {
             const r = inspectDsl({ source: s.dsl });
             expect(r.ok, `sample ${s.id}`).toBe(true);
             if (r.ok) {
-                expect(r.data.scenes.length).toBeGreaterThanOrEqual(1);
+                expect(r.data.chartType).toBe(s.chartType);
+                expect(r.data.data.rowCount).toBeGreaterThan(0);
+                expect(Array.isArray(r.data.data.labels)).toBe(true);
+                expect(r.data.data.labels.length).toBe(r.data.data.rowCount);
             }
         }
     });
+    it('rowCount counts parsed rows only, not arbitrary AST entries', () => {
+        // Unquoted-identifier keys are now an E_UNKNOWN_DATA_KEY situation; the
+        // inspector should still parse but rowCount reflects only quoted labels.
+        const r = inspectDsl({
+            source: 'chart bar-vertical { data { a = "foo"  b = "bar" "E" = 1 } }',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.data.rowCount).toBe(1); // only "E" counts
+            expect(r.data.data.entryCount).toBe(3); // a, b, "E"
+        }
+    });
+    it('hasHighlights is true for braced highlight syntax', () => {
+        const r = inspectDsl({
+            source: 'chart bar-vertical { data { "E" = 1 }  highlight "E" { color = "red" } }',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasHighlights).toBe(true);
+        }
+    });
+    it('hasHighlights is true for bare highlight syntax', () => {
+        const r = inspectDsl({
+            source: 'chart bar-vertical { data { "E" = 1 }  highlight "E" }',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasHighlights).toBe(true);
+        }
+    });
     it('forwards parse errors', () => {
         const r = inspectDsl({ source: '@@@ not valid' });
         expect(r.ok).toBe(false);
     });
 });
+describe('inspect_dsl fixes', () => {
+    it('lists ALL series names from the _series header', () => {
+        const src = 'chart bar-multi {\n  data {\n    _series = "Hardware","Software","Services"\n    "Q1" = 1,2,3\n  }\n}';
+        const r = inspectDsl({ source: src });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.data.seriesNames).toEqual(['Hardware', 'Software', 'Services']);
+            expect(r.data.data.multiSeries).toBe(true);
+        }
+    });
+    it('reports hasHighlights:true when a highlight lives inside a scene', () => {
+        const src = 'chart area-stacked {\n  data {\n    _series = "A","B"\n    "2000" = 1,2\n  }\n  scene "S1" {\n    highlight "A"\n  }\n}';
+        const r = inspectDsl({ source: src });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasHighlights).toBe(true);
+        }
+    });
+    it('reports hasColorizes:true when a colorize lives inside a scene', () => {
+        const src = 'chart area-stacked {\n  data {\n    _series = "A","B"\n    "2000" = 1,2\n  }\n  scene "S1" {\n    colorize "A" { color = "#f00" }\n  }\n}';
+        const r = inspectDsl({ source: src });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasColorizes).toBe(true);
+        }
+    });
+});

package/dist/tools/listChartTypes.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const ListChartTypesInputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type ListChartTypesInput = z.infer<typeof ListChartTypesInputSchema>;
+export interface ChartTypeListEntry {
+    name: string;
+    aliases: string[];
+    summary: string;
+    docsUrl?: string;
+}
+export interface ListChartTypesOutput {
+    chartTypes: ChartTypeListEntry[];
+}
+export declare function listChartTypes(): ToolResult<ListChartTypesOutput>;

package/dist/tools/listChartTypes.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { getDoc, listDocs } from '@blueprint-chart/docs';
+import { aliasesFor, listCanonicalChartTypes } from '../dsl/chartTypes';
+import { publicDocUrl } from '../resources/docsReader';
+import { toolOk } from '../errors';
+export const ListChartTypesInputSchema = z.object({}).strict();
+function summaryFor(name) {
+    // The chart-type docs follow a consistent template: an H1 followed by a
+    // blockquote subtitle. Example (`bar-horizontal.md`):
+    //   # Horizontal bar chart
+    //
+    //   > Single-series horizontal bar chart for long category labels and ranked bars.
+    // If the doc is missing or the template doesn't match, return ''.
+    const entries = listDocs('charts');
+    const entry = entries.find(e => e.slug === name);
+    if (!entry) {
+        return '';
+    }
+    try {
+        const { content } = getDoc('charts', name);
+        const match = content.match(/^>\s*(.+)$/m);
+        return match?.[1]?.trim() ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+export function listChartTypes() {
+    const chartTypes = listCanonicalChartTypes().map((name) => {
+        const entry = {
+            name,
+            aliases: aliasesFor(name),
+            summary: summaryFor(name),
+        };
+        const docsUrl = publicDocUrl('charts', name);
+        if (docsUrl) {
+            entry.docsUrl = docsUrl;
+        }
+        return entry;
+    });
+    return toolOk({ chartTypes });
+}

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

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

package/dist/tools/listChartTypes.test.js

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { listChartTypes } from './listChartTypes';
+describe('list_chart_types', () => {
+    afterEach(() => {
+        delete process.env.BLUEPRINT_CHART_DOCS_URL;
+    });
+    it('returns canonical chart types with aliases and a summary', () => {
+        const r = listChartTypes();
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const types = r.data.chartTypes;
+            expect(types.length).toBeGreaterThan(5);
+            const horiz = types.find(t => t.name === 'bar-horizontal');
+            expect(horiz).toBeDefined();
+            expect(horiz.aliases).toContain('horizontal-bar');
+            expect(horiz.summary.length).toBeGreaterThan(0);
+        }
+    });
+    it('does not include alias names as canonical entries', () => {
+        const r = listChartTypes();
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.chartTypes.find(t => t.name === 'horizontal-bar')).toBeUndefined();
+        }
+    });
+    it('omits docsUrl when docs base is unset', () => {
+        const result = listChartTypes();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.chartTypes[0]?.docsUrl).toBeUndefined();
+        }
+    });
+    it('includes docsUrl per entry when docs base is set', () => {
+        process.env.BLUEPRINT_CHART_DOCS_URL = 'https://docs.blueprintchart.com';
+        const result = listChartTypes();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            const entry = result.data.chartTypes[0];
+            expect(entry?.docsUrl).toBe(`https://docs.blueprintchart.com/charts/${entry?.name}`);
+        }
+    });
+});

package/dist/tools/listPalettes.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const ListPalettesInputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type ListPalettesInput = z.infer<typeof ListPalettesInputSchema>;
+export interface PaletteSummary {
+    name: string;
+    label: string;
+    colors: string[];
+}
+export interface ListPalettesOutput {
+    palettes: PaletteSummary[];
+}
+export declare function listPalettesTool(): ToolResult<ListPalettesOutput>;

package/dist/tools/listPalettes.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { listPalettes } from '@blueprint-chart/lib';
+import { toolOk } from '../errors';
+export const ListPalettesInputSchema = z.object({}).strict();
+export function listPalettesTool() {
+    const palettes = listPalettes().map(p => ({
+        name: p.name,
+        label: p.label,
+        colors: [...p.colors],
+    }));
+    return toolOk({ palettes });
+}

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

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

package/dist/tools/listPalettes.test.js

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { listPalettesTool } from './listPalettes';
+describe('list_palettes', () => {
+    it('returns named palettes with their colours', () => {
+        const r = listPalettesTool();
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.palettes.length).toBeGreaterThan(0);
+            const first = r.data.palettes[0];
+            expect(first).toHaveProperty('name');
+            expect(Array.isArray(first.colors)).toBe(true);
+            expect(first.colors.length).toBeGreaterThan(0);
+        }
+    });
+});

package/dist/tools/recommend.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { recommendCharts } from '@blueprint-chart/lib';
+import { applyGoalReranking } from '../dsl/goalRanking';
 import { ErrorCode, toolError, toolOk } from '../errors';
 const ColumnTypeSchema = z.enum(['string', 'number', 'date']);
 export const RecommendInputSchema = z.object({
@@ -12,6 +13,7 @@ export function recommendChartType(input) {
     if (!parsed.success) {
         return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
     }
-    const recommendations = recommendCharts(parsed.data.columnTypes, parsed.data.rowCount);
+    const base = recommendCharts(parsed.data.columnTypes, parsed.data.rowCount);
+    const recommendations = applyGoalReranking(base, parsed.data.goal, parsed.data.rowCount);
     return toolOk({ recommendations });
 }

package/dist/tools/recommend.test.js

@@ -30,4 +30,44 @@ describe('recommend_chart_type', () => {
             expect(r.code).toBe('E_INPUT');
         }
     });
+    it('reorders toward part-to-whole when a goal says "share of total"', () => {
+        const r = recommendChartType({ columnTypes: ['string', 'number'], rowCount: 5, goal: 'each region as a share of the total' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(['pie', 'donut', 'bar-stacked', 'column-stacked']).toContain(r.data.recommendations[0]?.chartType);
+        }
+    });
+    it('keeps lib-best bar-multi ahead of a narrative-boosted line-multi', () => {
+        const r = recommendChartType({
+            columnTypes: ['string', 'number', 'number', 'number'],
+            rowCount: 6,
+            goal: 'software overtakes hardware as the top revenue driver',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const types = r.data.recommendations.map(x => x.chartType);
+            const barMulti = types.indexOf('bar-multi');
+            const lineMulti = types.indexOf('line-multi');
+            expect(barMulti).toBeGreaterThanOrEqual(0);
+            expect(lineMulti).toBeGreaterThanOrEqual(0);
+            expect(barMulti).toBeLessThan(lineMulti);
+        }
+    });
+    it('threads rowCount so the pie tiebreak fires for a small-N part-to-whole goal', () => {
+        const r = recommendChartType({
+            columnTypes: ['string', 'number'],
+            rowCount: 5,
+            goal: 'Asia is nearly 60% of the world population; share of total across five regions',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const types = r.data.recommendations.map(x => x.chartType);
+            const pieIdx = types.indexOf('pie');
+            const donutIdx = types.indexOf('donut');
+            // both should be present and boosted to the front; pie before donut at N=5
+            expect(pieIdx).toBeGreaterThanOrEqual(0);
+            expect(donutIdx).toBeGreaterThanOrEqual(0);
+            expect(pieIdx).toBeLessThan(donutIdx);
+        }
+    });
 });

package/dist/tools/render.d.ts

@@ -1,35 +1,37 @@
 import { z } from 'zod';
+import { type FrameMetadata } from '../render/frame';
 import { type ToolResult } from '../errors';
 export declare const RenderInputSchema: z.ZodObject<{
     source: z.ZodString;
-    format: z.ZodDefault<z.ZodEnum<["svg", "png"]>>;
+    format: z.ZodDefault<z.ZodEnum<["svg", "png", "html"]>>;
     scene: z.ZodOptional<z.ZodNumber>;
     width: z.ZodDefault<z.ZodNumber>;
     height: z.ZodDefault<z.ZodNumber>;
+    /** Optional file path (absolute, or relative to MCP server CWD). When provided, the primary output (PNG bytes / SVG / HTML) is written to that path and the inline content is omitted from the response. Requires MCP_ALLOW_FS_WRITE=1. */
+    save: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     source: string;
     width: number;
     height: number;
-    format: "svg" | "png";
+    format: "html" | "svg" | "png";
     scene?: number | undefined;
+    save?: string | undefined;
 }, {
     source: string;
     width?: number | undefined;
     height?: number | undefined;
-    format?: "svg" | "png" | undefined;
     scene?: number | undefined;
+    format?: "html" | "svg" | "png" | undefined;
+    save?: string | undefined;
 }>;
 export type RenderInput = z.infer<typeof RenderInputSchema>;
 export interface RenderOutput {
-    svg: string;
+    svg?: string;
     png?: string;
-    mimeType: 'image/svg+xml' | 'image/png';
+    html?: string;
+    frame: FrameMetadata;
+    mimeType: 'image/svg+xml' | 'image/png' | 'text/html';
+    /** When `save` was used, the resolved absolute path the output was written to. Inline content fields (svg/png/html) are omitted. */
+    savedTo?: string;
 }
-/**
- * Composes `parseDsl`, `renderSceneState`, and `rasterizeToPng` into the
- * `render` MCP tool. Always returns SVG; when `format=png`, also includes a
- * base64-encoded PNG. If rasterisation fails we surface `E_RENDER` — the SVG
- * is discarded in that branch to keep the union shape (ToolResult is either
- * ok-with-data or err-with-errors, no partial-success carrier).
- */
 export declare function renderTool(input: unknown): Promise<ToolResult<RenderOutput>>;

package/dist/tools/render.js

@@ -1,63 +1,131 @@
 import { z } from 'zod';
-import { parseDsl } from '../parse';
+import { writeFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { extractFrameMetadata } from '../render/frame';
 import { renderSceneState } from '../render/renderSceneState';
 import { rasterizeToPng } from '../render/rasterize';
+import { validatePipeline } from '../render/validatePipeline';
 import { ErrorCode, toolError, toolOk } from '../errors';
 export const RenderInputSchema = z.object({
     source: z.string(),
-    format: z.enum(['svg', 'png']).default('svg'),
+    format: z.enum(['svg', 'png', 'html']).default('svg'),
     scene: z.number().int().nonnegative().optional(),
     width: z.number().int().positive().default(800),
     height: z.number().int().positive().default(500),
+    /** Optional file path (absolute, or relative to MCP server CWD). When provided, the primary output (PNG bytes / SVG / HTML) is written to that path and the inline content is omitted from the response. Requires MCP_ALLOW_FS_WRITE=1. */
+    save: z.string().optional(),
 });
-/**
- * `renderSceneState` returns the SVG fragment as produced by jsdom's
- * `outerHTML`, which omits the default SVG namespace. resvg's strict parser
- * rejects that as "the document does not have a root node". Inject the
- * namespace on the way to the rasterizer so the PNG path succeeds.
- */
+function isFsWriteEnabled() {
+    const v = process.env.MCP_ALLOW_FS_WRITE;
+    return v === '1' || v === 'true' || v === 'yes';
+}
+async function trySave(absPath, body) {
+    try {
+        await writeFile(absPath, body);
+        return { savedTo: absPath };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
 function ensureSvgNamespace(svg) {
     if (svg.includes('xmlns="http://www.w3.org/2000/svg"')) {
         return svg;
     }
     return svg.replace(/^<svg(?=\s|>)/, '<svg xmlns="http://www.w3.org/2000/svg"');
 }
-/**
- * Composes `parseDsl`, `renderSceneState`, and `rasterizeToPng` into the
- * `render` MCP tool. Always returns SVG; when `format=png`, also includes a
- * base64-encoded PNG. If rasterisation fails we surface `E_RENDER` — the SVG
- * is discarded in that branch to keep the union shape (ToolResult is either
- * ok-with-data or err-with-errors, no partial-success carrier).
- */
 export async function renderTool(input) {
     const parsed = RenderInputSchema.safeParse(input);
     if (!parsed.success) {
         return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
     }
-    const { source, format, scene, width, height } = parsed.data;
-    const parseResult = parseDsl(source);
-    if (!parseResult.ok) {
-        return parseResult;
+    const { source, format, scene, width, height, save } = parsed.data;
+    if (save !== undefined && !isFsWriteEnabled()) {
+        return toolError(ErrorCode.E_INPUT, [{
+                code: 'E_FS_WRITE_DISABLED',
+                path: 'save',
+                message: 'File saving is disabled. Set MCP_ALLOW_FS_WRITE=1 to enable. This is typically only safe in local stdio mode.',
+            }]);
     }
+    const validated = validatePipeline(source, { sceneIndex: scene });
+    if (!validated.ok) {
+        return validated.error;
+    }
+    const frame = extractFrameMetadata(validated.ast);
+    // Layer 3: actual render.
     let svg;
+    let html;
     try {
-        svg = renderSceneState(source, { sceneIndex: scene, width, height });
+        const result = renderSceneState(source, { sceneIndex: scene, width, height });
+        svg = result.svg;
+        html = result.html;
     }
     catch (err) {
-        return toolError(ErrorCode.E_RENDER, [
-            { path: 'render', message: err instanceof Error ? err.message : String(err) },
-        ]);
+        return toolError(ErrorCode.E_RENDER, [{
+                code: 'E_RENDER_UNKNOWN',
+                path: 'render',
+                message: err instanceof Error ? err.message : String(err),
+            }]);
     }
     if (format === 'svg') {
-        return toolOk({ svg, mimeType: 'image/svg+xml' });
+        if (save !== undefined) {
+            const absPath = resolvePath(save);
+            const result = await trySave(absPath, svg);
+            if ('error' in result) {
+                return toolError(ErrorCode.E_RENDER, [{
+                        code: 'E_SAVE_FAILED',
+                        path: 'save',
+                        message: result.error,
+                    }]);
+            }
+            return toolOk({ frame, mimeType: 'image/svg+xml', savedTo: result.savedTo });
+        }
+        return toolOk({ svg, frame, mimeType: 'image/svg+xml' });
+    }
+    if (format === 'html') {
+        if (!html) {
+            return toolError(ErrorCode.E_RENDER, [{
+                    code: 'E_FRAME_UNAVAILABLE',
+                    path: 'render',
+                    message: 'HTML frame was not produced by the renderer',
+                }]);
+        }
+        if (save !== undefined) {
+            const absPath = resolvePath(save);
+            const result = await trySave(absPath, html);
+            if ('error' in result) {
+                return toolError(ErrorCode.E_RENDER, [{
+                        code: 'E_SAVE_FAILED',
+                        path: 'save',
+                        message: result.error,
+                    }]);
+            }
+            return toolOk({ frame, mimeType: 'text/html', savedTo: result.savedTo });
+        }
+        return toolOk({ svg, html, frame, mimeType: 'text/html' });
     }
+    // format === 'png'
     try {
         const png = await rasterizeToPng(ensureSvgNamespace(svg), { width });
-        return toolOk({ svg, png: png.toString('base64'), mimeType: 'image/png' });
+        if (save !== undefined) {
+            const absPath = resolvePath(save);
+            const result = await trySave(absPath, png);
+            if ('error' in result) {
+                return toolError(ErrorCode.E_RENDER, [{
+                        code: 'E_SAVE_FAILED',
+                        path: 'save',
+                        message: result.error,
+                    }]);
+            }
+            return toolOk({ frame, mimeType: 'image/png', savedTo: result.savedTo });
+        }
+        return toolOk({ svg, png: png.toString('base64'), frame, mimeType: 'image/png' });
     }
     catch (err) {
-        return toolError(ErrorCode.E_RENDER, [
-            { path: 'rasterize', message: err instanceof Error ? err.message : String(err) },
-        ]);
+        return toolError(ErrorCode.E_RENDER, [{
+                code: 'E_RASTERIZE',
+                path: 'rasterize',
+                message: err instanceof Error ? err.message : String(err),
+            }]);
     }
 }