@blueprint-chart/mcp 0.1.1 → 0.1.4

package/dist/tools/render.test.js

@@ -2,13 +2,15 @@ import { describe, expect, it } from 'vitest';
 import { samples } from '@blueprint-chart/lib';
 import { renderTool } from './render';
 describe('render', () => {
-    it('returns SVG by default', async () => {
+    it('returns pure SVG by default', async () => {
         const r = await renderTool({ source: samples[0].dsl });
         expect(r.ok).toBe(true);
         if (r.ok) {
             expect(r.data.mimeType).toBe('image/svg+xml');
             expect(r.data.svg).toMatch(/^<svg/);
             expect(r.data.png).toBeUndefined();
+            expect(r.data.html).toBeUndefined();
+            expect(r.data.frame).toBeDefined();
         }
     });
     it('returns both SVG and PNG when format=png', async () => {
@@ -19,6 +21,7 @@ describe('render', () => {
             expect(r.data.svg).toMatch(/^<svg/);
             expect(r.data.png).toBeTypeOf('string'); // base64
             expect(r.data.png.length).toBeGreaterThan(100);
+            expect(r.data.frame).toBeDefined();
         }
     });
     it('forwards parse errors', async () => {
@@ -37,3 +40,136 @@ describe('render', () => {
         }
     });
 });
+describe('render — frame defaults', () => {
+    it('format=svg returns pure SVG without HTML wrapper', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const r = await renderTool({ source: sample.dsl, format: 'svg' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.svg).toMatch(/^<svg/);
+            expect(r.data.svg).not.toContain('<div class="bc-frame"');
+            expect(r.data.html).toBeUndefined();
+        }
+    });
+    it('format=svg on letter-frequency returns correct frame.title', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const r = await renderTool({ source: sample.dsl, format: 'svg' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.frame.title).toBe('E is the most frequent letter in English');
+        }
+    });
+    it('format=html returns html containing bc-frame and svg', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const r = await renderTool({ source: sample.dsl, format: 'html' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.mimeType).toBe('text/html');
+            expect(r.data.html).toContain('<div class="bc-frame"');
+            expect(r.data.html).toContain('<svg');
+            expect(r.data.svg).toMatch(/^<svg/);
+            expect(r.data.frame).toBeDefined();
+        }
+    });
+});
+describe('render — save option', () => {
+    it('errors when MCP_ALLOW_FS_WRITE is unset', async () => {
+        delete process.env.MCP_ALLOW_FS_WRITE;
+        const r = await renderTool({
+            source: 'chart bar-vertical { data { "E" = 1 } }',
+            format: 'png',
+            save: '/tmp/test.png',
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.errors[0].code).toBe('E_FS_WRITE_DISABLED');
+        }
+    });
+    it('writes the PNG when MCP_ALLOW_FS_WRITE=1', async () => {
+        process.env.MCP_ALLOW_FS_WRITE = '1';
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const tmp = `/tmp/mcp-render-test-${Date.now()}.png`;
+        try {
+            const r = await renderTool({ source: sample.dsl, format: 'png', save: tmp });
+            expect(r.ok).toBe(true);
+            if (r.ok) {
+                expect(r.data.savedTo).toBe(tmp);
+                expect(r.data.png).toBeUndefined(); // inline payload omitted
+                const { statSync } = await import('node:fs');
+                expect(statSync(tmp).size).toBeGreaterThan(1000); // real PNG, not stub
+            }
+        }
+        finally {
+            const { unlinkSync, existsSync } = await import('node:fs');
+            if (existsSync(tmp)) {
+                unlinkSync(tmp);
+            }
+            delete process.env.MCP_ALLOW_FS_WRITE;
+        }
+    });
+    it('writes the SVG when format=svg and save provided', async () => {
+        process.env.MCP_ALLOW_FS_WRITE = '1';
+        const tmp = `/tmp/mcp-render-test-${Date.now()}.svg`;
+        try {
+            const r = await renderTool({
+                source: 'chart bar-vertical { title = "x"  data { "E" = 1 } }',
+                format: 'svg',
+                save: tmp,
+            });
+            expect(r.ok).toBe(true);
+            if (r.ok) {
+                expect(r.data.savedTo).toBe(tmp);
+                expect(r.data.svg).toBeUndefined();
+            }
+        }
+        finally {
+            const { unlinkSync, existsSync } = await import('node:fs');
+            if (existsSync(tmp)) {
+                unlinkSync(tmp);
+            }
+            delete process.env.MCP_ALLOW_FS_WRITE;
+        }
+    });
+});
+describe('render — structured diagnostics', () => {
+    it('returns E_SEMANTIC + E_UNKNOWN_CHART_TYPE for chart bar', async () => {
+        const r = await renderTool({ source: 'chart bar { data { "E" = 1 } }' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_SEMANTIC');
+            expect(r.errors[0].code).toBe('E_UNKNOWN_CHART_TYPE');
+            expect(r.errors[0].suggestion).toMatch(/^bar-/);
+        }
+    });
+    it('returns E_SEMANTIC + E_EMPTY_DATA when data is empty', async () => {
+        const r = await renderTool({ source: 'chart bar-vertical { title = "x" }' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_SEMANTIC');
+            expect(r.errors[0].code).toBe('E_EMPTY_DATA');
+        }
+    });
+    it('never returns the generic "produced no SVG output" message', async () => {
+        const r = await renderTool({ source: 'chart bar { data { "E" = 1 } }' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            for (const e of r.errors) {
+                expect(e.message).not.toContain('produced no SVG output');
+            }
+        }
+    });
+    it('renders every sample to SVG and provides frame metadata', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        for (const s of samples) {
+            const r = await renderTool({ source: s.dsl, format: 'svg' });
+            expect(r.ok, `sample ${s.id}`).toBe(true);
+            if (r.ok) {
+                expect(r.data.frame, `sample ${s.id} frame`).toBeDefined();
+            }
+        }
+    });
+});

package/dist/tools/searchExamples.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const SearchExamplesInputSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    chartType: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    chartType?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}, {
+    chartType?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}>;
+export type SearchExamplesInput = z.infer<typeof SearchExamplesInputSchema>;
+export interface SearchExampleHit {
+    id: string;
+    title: string;
+    description: string;
+    chartType: string;
+    /** Raw count of query terms matched in title+description; used only for ordering. */
+    score: number;
+}
+export interface SearchExamplesOutput {
+    results: SearchExampleHit[];
+}
+export declare function searchExamples(input: unknown): ToolResult<SearchExamplesOutput>;

package/dist/tools/searchExamples.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { samples } from '@blueprint-chart/lib';
+import { canonicalChartType } from '../dsl/chartTypes';
+import { ErrorCode, toolError, toolOk } from '../errors';
+export const SearchExamplesInputSchema = z.object({
+    query: z.string().optional(),
+    chartType: z.string().optional(),
+    limit: z.number().int().positive().max(20).optional(),
+}).strict();
+function scoreSample(s, terms) {
+    if (terms.length === 0) {
+        return 1;
+    }
+    const hay = `${s.title} ${s.description}`.toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+        if (hay.includes(t)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+export function searchExamples(input) {
+    const parsed = SearchExamplesInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    }
+    const { query, chartType, limit } = parsed.data;
+    if ((!query || query.trim() === '') && !chartType) {
+        return toolError(ErrorCode.E_INPUT, [{
+                path: 'query',
+                message: 'Provide a `query` (topic keywords) and/or a `chartType` to search examples.',
+            }]);
+    }
+    let canonical;
+    if (chartType) {
+        canonical = canonicalChartType(chartType);
+        if (!canonical) {
+            return toolError(ErrorCode.E_INPUT, [{
+                    code: 'E_UNKNOWN_CHART_TYPE',
+                    path: 'chartType',
+                    message: `Unknown chart type "${chartType}".`,
+                }]);
+        }
+    }
+    const terms = (query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    const results = samples
+        .filter(s => (canonical ? s.chartType === canonical : true))
+        .map(s => ({ id: s.id, title: s.title, description: s.description, chartType: s.chartType, score: scoreSample(s, terms) }))
+        .filter(h => h.score > 0)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, limit ?? 10);
+    return toolOk({ results });
+}

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

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

package/dist/tools/searchExamples.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { searchExamples } from './searchExamples';
+describe('search_examples', () => {
+    it('finds samples by topic keyword in title/description', () => {
+        const r = searchExamples({ query: 'population' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.results.length).toBeGreaterThan(0);
+            expect(r.data.results[0]).toHaveProperty('id');
+            expect(r.data.results[0]).toHaveProperty('chartType');
+            expect(r.data.results[0]).not.toHaveProperty('dsl');
+        }
+    });
+    it('filters by chartType', () => {
+        const r = searchExamples({ chartType: 'pie' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.results.every(x => x.chartType === 'pie')).toBe(true);
+        }
+    });
+    it('rejects when neither query nor chartType is given', () => {
+        const r = searchExamples({});
+        expect(r.ok).toBe(false);
+    });
+    it('rejects an unknown chartType', () => {
+        const r = searchExamples({ chartType: 'notachart' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+        }
+    });
+});

package/dist/tools/validate.d.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { type ValidationIssue } from '../dsl/validate';
+import { type WarningIssue } from '../dsl/semanticWarnings';
 import { type ToolResult } from '../errors';
 export declare const ValidateInputSchema: z.ZodObject<{
     source: z.ZodString;
@@ -8,6 +10,10 @@ export declare const ValidateInputSchema: z.ZodObject<{
     source: string;
 }>;
 export type ValidateInput = z.infer<typeof ValidateInputSchema>;
-export declare function validateDsl(input: ValidateInput): ToolResult<{
-    valid: true;
-}>;
+export interface ValidateOutput {
+    valid: boolean;
+    errors: ValidationIssue[];
+    /** Non-fatal advisories (W_NO_EFFECT / W_NOT_IMPLEMENTED / W_MULTISERIES_SHAPE). `code` is a plain string until the warning catalogue stabilises; errors keep the strict ValidationCode union. */
+    warnings: WarningIssue[];
+}
+export declare function validateDsl(input: ValidateInput): ToolResult<ValidateOutput>;

package/dist/tools/validate.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { parseDsl } from '../parse';
+import { validateAst } from '../dsl/validate';
+import { collectWarnings } from '../dsl/semanticWarnings';
 import { toolOk } from '../errors';
 export const ValidateInputSchema = z.object({
     source: z.string(),
@@ -9,5 +11,13 @@ export function validateDsl(input) {
     if (!parsed.ok) {
         return parsed;
     }
-    return toolOk({ valid: true });
+    const errors = validateAst(parsed.data.ast);
+    // Warnings are non-fatal: they never change `valid`. Only emit them when the
+    // structure is sound, so authors fix hard errors before chasing advisories.
+    const warnings = errors.length === 0 ? collectWarnings(parsed.data.ast) : [];
+    return toolOk({
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    });
 }

package/dist/tools/validate.test.js

@@ -2,26 +2,48 @@ import { describe, expect, it } from 'vitest';
 import { samples } from '@blueprint-chart/lib';
 import { validateDsl } from './validate';
 describe('validate_dsl', () => {
-    it('returns ok for every shipped sample', () => {
+    it('returns valid: true with empty errors/warnings for every sample', () => {
         for (const s of samples) {
             const r = validateDsl({ source: s.dsl });
-            expect(r.ok, `sample "${s.id}" should validate`).toBe(true);
+            expect(r.ok, `sample ${s.id}`).toBe(true);
+            if (r.ok) {
+                expect(r.data.valid).toBe(true);
+                expect(r.data.errors).toEqual([]);
+                expect(r.data.warnings).toEqual([]);
+            }
         }
     });
-    it('returns parse error with line/column', () => {
-        const r = validateDsl({ source: 'chart not-a-real-thing\n@@@' });
+    it('returns valid: false with E_UNKNOWN_CHART_TYPE on chart bar', () => {
+        const r = validateDsl({ source: 'chart bar { data { "E" = 1 } }' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.valid).toBe(false);
+            expect(r.data.errors[0].code).toBe('E_UNKNOWN_CHART_TYPE');
+            expect(r.data.errors[0].suggestion).toMatch(/^bar-/);
+        }
+    });
+    it('still surfaces PEG errors as E_PARSE (isError channel)', () => {
+        const r = validateDsl({ source: '@@@ not valid' });
         expect(r.ok).toBe(false);
         if (!r.ok) {
             expect(r.code).toBe('E_PARSE');
-            expect(r.errors[0]?.line).toBeTypeOf('number');
         }
     });
-    it('returns E_INPUT for non-string source', () => {
-        // @ts-expect-error testing runtime validation
-        const r = validateDsl({ source: null });
-        expect(r.ok).toBe(false);
-        if (!r.ok) {
-            expect(r.code).toBe('E_INPUT');
+});
+describe('validate_dsl warnings', () => {
+    it('stays valid but surfaces a no-op warning for sort on donut', () => {
+        const r = validateDsl({ source: 'chart donut {\n  sort = descending\n  data { "A" = 1 }\n}' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.valid).toBe(true);
+            expect(r.data.warnings.some(w => w.code === 'W_NO_EFFECT')).toBe(true);
+        }
+    });
+    it('emits no warnings for a clean chart', () => {
+        const r = validateDsl({ source: 'chart bar-vertical {\n  data { "A" = 1 }\n}' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.warnings).toEqual([]);
         }
     });
 });

package/dist/transports/http.d.ts

@@ -1,18 +1,20 @@
 export interface StartHttpOptions {
     port: number;
     host?: string;
-    /** If set, require `Authorization: Bearer <token>` on every /mcp request. */
+    /** If set, require `Authorization: Bearer <token>` on every request. */
     authToken?: string;
     /** Comma-resolved CORS allowlist. `'*'` allows any origin. Default: `'*'`. */
     allowedOrigins?: string[] | '*';
     /** Read `X-Forwarded-For` for client IP (enable when behind a reverse proxy). */
     trustProxy?: boolean;
-    /** Cap on concurrent `POST /mcp` requests. Default: 16. */
+    /** Cap on concurrent tool calls. Default: 16. */
     maxConcurrentRequests?: number;
     /** Per-IP token-bucket rate limit. Disabled when undefined or 0. */
     rateLimitPerMinute?: number;
     /** Suppress JSON access logs. Default: false (logs to stderr). */
     silent?: boolean;
+    /** If set, redirect GET / to this URL. Otherwise returns 404. */
+    rootRedirectUrl?: string;
 }
 export interface HttpHandle {
     url: string;