@blueprint-chart/mcp 0.1.0

package/dist/server.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, it } 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';
+async function connectInMemory() {
+    const server = createServer();
+    const [clientT, serverT] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverT);
+    const client = new Client({ name: 'test', version: '0' }, { capabilities: {} });
+    await client.connect(clientT);
+    return { client, server };
+}
+describe('server', () => {
+    it('lists 4 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']);
+    });
+    it('calls validate_dsl successfully for a sample', async () => {
+        const { client } = await connectInMemory();
+        const r = await client.callTool({
+            name: 'validate_dsl',
+            arguments: { source: samples[0].dsl },
+        });
+        expect(r.isError).toBeFalsy();
+    });
+    it('calls validate_dsl with parse error', async () => {
+        const { client } = await connectInMemory();
+        const r = await client.callTool({ name: 'validate_dsl', arguments: { source: '@@@' } });
+        const content = r.content;
+        const text = content?.[0]?.text ?? '';
+        expect(text).toMatch(/E_PARSE/);
+    });
+    it('lists at least 30 resources across 5 URI families', async () => {
+        const { client } = await connectInMemory();
+        const r = await client.listResources();
+        expect(r.resources.length).toBeGreaterThanOrEqual(30);
+        const prefixes = new Set(r.resources.map(rs => rs.uri.split('/').slice(0, 3).join('/')));
+        expect(prefixes.has('bpc://handbook')).toBe(true);
+        expect(prefixes.has('bpc://guide')).toBe(true);
+        expect(prefixes.has('bpc://chart-types')).toBe(true);
+    });
+    it('reads a handbook resource', async () => {
+        const { client } = await connectInMemory();
+        const list = await client.listResources();
+        const handbook = list.resources.find(r => r.uri.startsWith('bpc://handbook/'));
+        const r = await client.readResource({ uri: handbook.uri });
+        const first = r.contents[0];
+        expect(first.text).toMatch(/.{50,}/);
+    });
+    it('exposes bpc://samples/<id> with .bpc content', async () => {
+        const { client } = await connectInMemory();
+        const list = await client.listResources();
+        const sample = list.resources.find(r => r.uri.startsWith('bpc://samples/'));
+        const r = await client.readResource({ uri: sample.uri });
+        const first = r.contents[0];
+        expect(first.text).toMatch(/chart\s+\w/);
+    });
+    it('exposes author_chart prompt', async () => {
+        const { client } = await connectInMemory();
+        const prompts = await client.listPrompts();
+        expect(prompts.prompts.some(p => p.name === 'author_chart')).toBe(true);
+        const got = await client.getPrompt({ name: 'author_chart' });
+        expect(got.messages.length).toBeGreaterThan(0);
+    });
+});

package/dist/smoke.test.d.ts

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

package/dist/smoke.test.js

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { parse } from '@blueprint-chart/lib';
+import { listDocs } from '@blueprint-chart/docs';
+describe('smoke', () => {
+    it('@blueprint-chart/lib parse() is importable', () => {
+        expect(typeof parse).toBe('function');
+    });
+    it('@blueprint-chart/docs listDocs() returns entries', () => {
+        expect(listDocs('handbook').length).toBeGreaterThan(0);
+    });
+});

package/dist/tools/inspect.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const InspectInputSchema: z.ZodObject<{
+    source: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+}, {
+    source: string;
+}>;
+export type InspectInput = z.infer<typeof InspectInputSchema>;
+export interface SceneSummary {
+    index: number;
+    name?: string;
+    hasTransition: boolean;
+}
+export interface InspectOutput {
+    chartType: string;
+    scenes: SceneSummary[];
+    hasAnnotations: boolean;
+    hasColorizes: boolean;
+    hasHighlights: boolean;
+    hasAreaFills: boolean;
+    seriesCount: number;
+    rowCount: number;
+}
+export declare function inspectDsl(input: InspectInput): ToolResult<InspectOutput>;

package/dist/tools/inspect.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { astToDefinition } from '@blueprint-chart/lib';
+import { parseDsl } from '../parse';
+import { toolOk } from '../errors';
+export const InspectInputSchema = z.object({
+    source: z.string(),
+});
+function summarizeScenes(ast) {
+    const scenes = (ast.scenes ?? []);
+    if (scenes.length === 0) {
+        return [{ index: 0, hasTransition: false }];
+    }
+    return scenes.map((scene, i) => ({
+        index: i,
+        name: scene.name ?? undefined,
+        // SceneNode has no explicit `transition` field; transforms power animated
+        // transitions in the lib, so non-empty transforms imply a transition.
+        hasTransition: (scene.transforms?.length ?? 0) > 0,
+    }));
+}
+export function inspectDsl(input) {
+    const parsed = parseDsl(input.source);
+    if (!parsed.ok) {
+        return parsed;
+    }
+    const def = astToDefinition(parsed.data.ast);
+    return toolOk({
+        chartType: def.chartType,
+        scenes: summarizeScenes(parsed.data.ast),
+        hasAnnotations: (def.annotations?.length ?? 0) > 0,
+        hasColorizes: (def.colorizes?.length ?? 0) > 0,
+        hasHighlights: (def.highlights?.length ?? 0) > 0,
+        hasAreaFills: (def.areaFills?.length ?? 0) > 0,
+        seriesCount: def.data.series?.length ?? 0,
+        rowCount: def.data.labels?.length ?? 0,
+    });
+}

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

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

package/dist/tools/inspect.test.js

@@ -0,0 +1,29 @@
+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', () => {
+        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);
+            }
+        }
+    });
+    it('forwards parse errors', () => {
+        const r = inspectDsl({ source: '@@@ not valid' });
+        expect(r.ok).toBe(false);
+    });
+});

package/dist/tools/recommend.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { type ChartRecommendation } from '@blueprint-chart/lib';
+import { type ToolResult } from '../errors';
+export declare const RecommendInputSchema: z.ZodObject<{
+    columnTypes: z.ZodArray<z.ZodEnum<["string", "number", "date"]>, "many">;
+    rowCount: z.ZodNumber;
+    goal: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    columnTypes: ("string" | "number" | "date")[];
+    rowCount: number;
+    goal?: string | undefined;
+}, {
+    columnTypes: ("string" | "number" | "date")[];
+    rowCount: number;
+    goal?: string | undefined;
+}>;
+export type RecommendInput = z.infer<typeof RecommendInputSchema>;
+export interface RecommendOutput {
+    recommendations: ChartRecommendation[];
+}
+export declare function recommendChartType(input: unknown): ToolResult<RecommendOutput>;

package/dist/tools/recommend.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { recommendCharts } from '@blueprint-chart/lib';
+import { ErrorCode, toolError, toolOk } from '../errors';
+const ColumnTypeSchema = z.enum(['string', 'number', 'date']);
+export const RecommendInputSchema = z.object({
+    columnTypes: z.array(ColumnTypeSchema),
+    rowCount: z.number().int().nonnegative(),
+    goal: z.string().optional(),
+});
+export function recommendChartType(input) {
+    const parsed = RecommendInputSchema.safeParse(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);
+    return toolOk({ recommendations });
+}

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

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

package/dist/tools/recommend.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { recommendChartType } from './recommend';
+describe('recommend_chart_type', () => {
+    it('recommends a line chart for 1 date + 1 number', () => {
+        const r = recommendChartType({ columnTypes: ['date', 'number'], rowCount: 12 });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.recommendations[0]?.chartType).toBe('line');
+            expect(r.data.recommendations[0]?.fitness).toBe('best');
+        }
+    });
+    it('returns empty list for empty columns', () => {
+        const r = recommendChartType({ columnTypes: [], rowCount: 0 });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.recommendations).toEqual([]);
+        }
+    });
+    it('rejects unknown column types', () => {
+        const r = recommendChartType({ columnTypes: ['unknown'], rowCount: 1 });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+        }
+    });
+    it('rejects negative row counts', () => {
+        const r = recommendChartType({ columnTypes: ['string', 'number'], rowCount: -1 });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+        }
+    });
+});

package/dist/tools/render.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const RenderInputSchema: z.ZodObject<{
+    source: z.ZodString;
+    format: z.ZodDefault<z.ZodEnum<["svg", "png"]>>;
+    scene: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    width: number;
+    height: number;
+    format: "svg" | "png";
+    scene?: number | undefined;
+}, {
+    source: string;
+    width?: number | undefined;
+    height?: number | undefined;
+    format?: "svg" | "png" | undefined;
+    scene?: number | undefined;
+}>;
+export type RenderInput = z.infer<typeof RenderInputSchema>;
+export interface RenderOutput {
+    svg: string;
+    png?: string;
+    mimeType: 'image/svg+xml' | 'image/png';
+}
+/**
+ * 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

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { parseDsl } from '../parse';
+import { renderSceneState } from '../render/renderSceneState';
+import { rasterizeToPng } from '../render/rasterize';
+import { ErrorCode, toolError, toolOk } from '../errors';
+export const RenderInputSchema = z.object({
+    source: z.string(),
+    format: z.enum(['svg', 'png']).default('svg'),
+    scene: z.number().int().nonnegative().optional(),
+    width: z.number().int().positive().default(800),
+    height: z.number().int().positive().default(500),
+});
+/**
+ * `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 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;
+    }
+    let svg;
+    try {
+        svg = renderSceneState(source, { sceneIndex: scene, width, height });
+    }
+    catch (err) {
+        return toolError(ErrorCode.E_RENDER, [
+            { path: 'render', message: err instanceof Error ? err.message : String(err) },
+        ]);
+    }
+    if (format === 'svg') {
+        return toolOk({ svg, mimeType: 'image/svg+xml' });
+    }
+    try {
+        const png = await rasterizeToPng(ensureSvgNamespace(svg), { width });
+        return toolOk({ svg, png: png.toString('base64'), mimeType: 'image/png' });
+    }
+    catch (err) {
+        return toolError(ErrorCode.E_RENDER, [
+            { path: 'rasterize', message: err instanceof Error ? err.message : String(err) },
+        ]);
+    }
+}

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

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

package/dist/tools/render.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { samples } from '@blueprint-chart/lib';
+import { renderTool } from './render';
+describe('render', () => {
+    it('returns 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();
+        }
+    });
+    it('returns both SVG and PNG when format=png', async () => {
+        const r = await renderTool({ source: samples[0].dsl, format: 'png', width: 600, height: 400 });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.mimeType).toBe('image/png');
+            expect(r.data.svg).toMatch(/^<svg/);
+            expect(r.data.png).toBeTypeOf('string'); // base64
+            expect(r.data.png.length).toBeGreaterThan(100);
+        }
+    });
+    it('forwards parse errors', async () => {
+        const r = await renderTool({ source: '@@@' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_PARSE');
+        }
+    });
+    it('returns E_INPUT for invalid zod input', async () => {
+        const r = await renderTool({ source: samples[0].dsl, width: -10 });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+            expect(r.errors.length).toBeGreaterThan(0);
+        }
+    });
+});

package/dist/tools/validate.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const ValidateInputSchema: z.ZodObject<{
+    source: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+}, {
+    source: string;
+}>;
+export type ValidateInput = z.infer<typeof ValidateInputSchema>;
+export declare function validateDsl(input: ValidateInput): ToolResult<{
+    valid: true;
+}>;

package/dist/tools/validate.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { parseDsl } from '../parse';
+import { toolOk } from '../errors';
+export const ValidateInputSchema = z.object({
+    source: z.string(),
+});
+export function validateDsl(input) {
+    const parsed = parseDsl(input.source);
+    if (!parsed.ok) {
+        return parsed;
+    }
+    return toolOk({ valid: true });
+}

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

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

package/dist/tools/validate.test.js

@@ -0,0 +1,27 @@
+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', () => {
+        for (const s of samples) {
+            const r = validateDsl({ source: s.dsl });
+            expect(r.ok, `sample "${s.id}" should validate`).toBe(true);
+        }
+    });
+    it('returns parse error with line/column', () => {
+        const r = validateDsl({ source: 'chart not-a-real-thing\n@@@' });
+        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');
+        }
+    });
+});

package/dist/transports/http.d.ts

@@ -0,0 +1,21 @@
+export interface StartHttpOptions {
+    port: number;
+    host?: string;
+    /** If set, require `Authorization: Bearer <token>` on every /mcp 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. */
+    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;
+}
+export interface HttpHandle {
+    url: string;
+    close: () => Promise<void>;
+}
+export declare function startHttp(opts: StartHttpOptions): Promise<HttpHandle>;