@blueprint-chart/mcp 0.1.0 → 0.1.3

package/dist/render/diagnose.test.js

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { samples } from '@blueprint-chart/lib';
+import { diagnoseRender } from './diagnose';
+describe('diagnoseRender', () => {
+    it('returns ok for every shipped sample', () => {
+        for (const s of samples) {
+            const r = diagnoseRender(s.dsl);
+            expect(r.ok, `sample ${s.id}: ${JSON.stringify(r)}`).toBe(true);
+        }
+    });
+    it('reports E_UNKNOWN_CHART_TYPE for chart bar', () => {
+        const r = diagnoseRender('chart bar { data { "E" = 1 } }');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            const issue = r.diagnostics.find(d => d.code === 'E_UNKNOWN_CHART_TYPE');
+            expect(issue).toBeDefined();
+            expect(issue.suggestion).toMatch(/^bar-/);
+        }
+    });
+    it('reports E_NO_DATA when data is empty', () => {
+        const r = diagnoseRender('chart bar-vertical {}');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.diagnostics.some(d => d.code === 'E_NO_DATA')).toBe(true);
+        }
+    });
+    it('reports E_UNKNOWN_SCENE_INDEX when sceneIndex is out of range', () => {
+        const r = diagnoseRender('chart bar-vertical { data { "E" = 1 } }', { sceneIndex: 5 });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            const issue = r.diagnostics.find(d => d.code === 'E_UNKNOWN_SCENE_INDEX');
+            expect(issue).toBeDefined();
+            expect(issue.context?.availableSceneCount).toBe(0);
+        }
+    });
+    it('reports E_UNRESOLVED_COLORIZE when colorize target is not a label', () => {
+        const r = diagnoseRender('chart bar-vertical { data { "E" = 1 } colorize "Z" { color = "red" } }');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            const issue = r.diagnostics.find(d => d.code === 'E_UNRESOLVED_COLORIZE');
+            expect(issue).toBeDefined();
+            expect(issue.context?.target).toBe('Z');
+            expect(issue.context?.availableLabels).toEqual(['E']);
+        }
+    });
+    it('reports E_PARSE on malformed source', () => {
+        const r = diagnoseRender('@@@ not valid');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.diagnostics[0].code).toBe('E_PARSE');
+        }
+    });
+});

package/dist/render/frame.d.ts

@@ -0,0 +1,10 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+export interface FrameMetadata {
+    title?: string;
+    description?: string;
+    byline?: string;
+    source?: string;
+    sourceUrl?: string;
+    note?: string;
+}
+export declare function extractFrameMetadata(ast: ChartNode): FrameMetadata;

package/dist/render/frame.js

@@ -0,0 +1,10 @@
+const FRAME_KEYS = ['title', 'description', 'byline', 'source', 'sourceUrl', 'note'];
+export function extractFrameMetadata(ast) {
+    const frame = {};
+    for (const prop of ast.properties ?? []) {
+        if (FRAME_KEYS.includes(prop.key)) {
+            frame[prop.key] = String(prop.value).replace(/^"|"$/g, '');
+        }
+    }
+    return frame;
+}

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

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

package/dist/render/frame.test.js

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import { parse } from '@blueprint-chart/lib';
+import { extractFrameMetadata } from './frame';
+describe('extractFrameMetadata', () => {
+    it('pulls frame keys off the chart AST and strips surrounding quotes', () => {
+        const ast = parse('chart bar-vertical {\n  title = "Hi"\n  source = "ICIJ"\n  data {\n    "A" = 1\n  }\n}\n');
+        const frame = extractFrameMetadata(ast);
+        expect(frame.title).toBe('Hi');
+        expect(frame.source).toBe('ICIJ');
+        expect(frame.byline).toBeUndefined();
+    });
+});

package/dist/render/jsdomEnv.d.ts

@@ -2,7 +2,8 @@ import { type DOMWindow } from 'jsdom';
 export interface JsdomEnv {
     window: DOMWindow;
     container: HTMLElement;
-    serialize: () => string;
+    serializeSvg: () => string;
+    serializeFrame: () => string | undefined;
     cleanup: () => void;
 }
 export interface JsdomEnvOptions {

package/dist/render/jsdomEnv.js

@@ -19,10 +19,23 @@ export function createJsdomEnv(opts) {
     return {
         window: dom.window,
         container,
-        serialize: () => {
+        serializeSvg: () => {
+            // When thumbnail=false the lib wraps the SVG in a div.bc-frame. The chart
+            // SVG lives inside div.bc-frame-body. Extract it precisely so we don't
+            // accidentally grab the small logo SVG in the footer.
+            const frameBody = container.querySelector('.bc-frame-body');
+            if (frameBody) {
+                const svg = frameBody.querySelector('svg');
+                return svg ? svg.outerHTML : '';
+            }
+            // Fallback for bare renders (no frame): grab the direct SVG.
             const svg = container.querySelector('svg');
             return svg ? svg.outerHTML : '';
         },
+        serializeFrame: () => {
+            const frame = container.querySelector('.bc-frame');
+            return frame ? frame.outerHTML : undefined;
+        },
         cleanup: () => dom.window.close(),
     };
 }

package/dist/render/jsdomEnv.test.js

@@ -7,12 +7,46 @@ describe('createJsdomEnv', () => {
         expect(env.container.ownerDocument).toBeDefined();
         expect(env.window.SVGElement).toBeDefined();
     });
-    it('exposes a serialize() that returns SVG markup', () => {
+    it('serializeSvg() returns bare SVG markup', () => {
         const env = createJsdomEnv({ width: 600, height: 400 });
         const svg = env.window.document.createElementNS('http://www.w3.org/2000/svg', 'svg');
         svg.setAttribute('viewBox', '0 0 100 100');
         env.container.appendChild(svg);
-        expect(env.serialize()).toMatch(/<svg[^>]*viewBox="0 0 100 100"/);
+        const result = env.serializeSvg();
+        expect(result).toMatch(/<svg[^>]*viewBox="0 0 100 100"/);
+        expect(result).toMatch(/^<svg/);
+    });
+    it('serializeFrame() returns undefined when no bc-frame is present', () => {
+        const env = createJsdomEnv({ width: 600, height: 400 });
+        const svg = env.window.document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        env.container.appendChild(svg);
+        expect(env.serializeFrame()).toBeUndefined();
+    });
+    it('serializeFrame() returns frame outerHTML when bc-frame is present', () => {
+        const env = createJsdomEnv({ width: 600, height: 400 });
+        const frame = env.window.document.createElement('div');
+        frame.className = 'bc-frame';
+        frame.innerHTML = '<div class="bc-frame-body"><svg></svg></div>';
+        env.container.appendChild(frame);
+        const result = env.serializeFrame();
+        expect(result).toBeDefined();
+        expect(result).toContain('<div class="bc-frame"');
+        expect(result).toContain('<svg>');
+    });
+    it('serializeSvg() extracts inner svg from bc-frame-body when frame is present', () => {
+        const env = createJsdomEnv({ width: 600, height: 400 });
+        const frame = env.window.document.createElement('div');
+        frame.className = 'bc-frame';
+        const body = env.window.document.createElement('div');
+        body.className = 'bc-frame-body';
+        const svg = env.window.document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        svg.setAttribute('viewBox', '0 0 200 200');
+        body.appendChild(svg);
+        frame.appendChild(body);
+        env.container.appendChild(frame);
+        const result = env.serializeSvg();
+        expect(result).toMatch(/^<svg/);
+        expect(result).toMatch(/viewBox="0 0 200 200"/);
     });
     it('cleanup() closes the window', () => {
         const env = createJsdomEnv({ width: 100, height: 100 });

package/dist/render/renderSceneState.d.ts

@@ -4,6 +4,10 @@ export interface RenderSceneStateOptions {
     height: number;
     theme?: string;
 }
+export interface RenderSceneStateResult {
+    svg: string;
+    html?: string;
+}
 /**
  * Render a `.bpc` source string to SVG markup in a headless jsdom environment.
  *
@@ -18,4 +22,4 @@ export interface RenderSceneStateOptions {
  * Throws when `renderBpc` cannot produce SVG output (invalid source, etc.) —
  * callers (the `render` tool) catch and translate to a structured ToolResult.
  */
-export declare function renderSceneState(source: string, opts: RenderSceneStateOptions): string;
+export declare function renderSceneState(source: string, opts: RenderSceneStateOptions): RenderSceneStateResult;

package/dist/render/renderSceneState.js

@@ -49,7 +49,7 @@ export function renderSceneState(source, opts) {
         try {
             renderBpc(env.container, source, {
                 sceneIndex: opts.sceneIndex,
-                thumbnail: true,
+                thumbnail: false,
                 transition: false,
                 theme: opts.theme,
             });
@@ -59,11 +59,12 @@ export function renderSceneState(source, opts) {
                 globals[key] = prev[key];
             }
         }
-        const svg = env.serialize();
+        const svg = env.serializeSvg();
         if (!svg) {
             throw new Error('renderBpc produced no SVG output');
         }
-        return svg;
+        const html = env.serializeFrame();
+        return { svg, html };
     }
     finally {
         env.cleanup();

package/dist/render/renderSceneState.test.js

@@ -2,15 +2,21 @@ import { describe, expect, it } from 'vitest';
 import { samples } from '@blueprint-chart/lib';
 import { renderSceneState } from './renderSceneState';
 describe('renderSceneState', () => {
-    it('returns non-empty SVG for the first sample, scene 0', () => {
-        const svg = renderSceneState(samples[0].dsl, { sceneIndex: 0, width: 800, height: 500 });
-        expect(svg).toMatch(/^<svg/);
-        expect(svg).toMatch(/<\/svg>$/);
-        expect(svg.length).toBeGreaterThan(500);
+    it('returns pure SVG (no HTML wrapper) for the first sample, scene 0', () => {
+        const result = renderSceneState(samples[0].dsl, { sceneIndex: 0, width: 800, height: 500 });
+        expect(result.svg).toMatch(/^<svg/);
+        expect(result.svg).toContain('</svg>');
+        expect(result.svg.length).toBeGreaterThan(500);
+    });
+    it('returns frame html containing bc-frame and the svg', () => {
+        const result = renderSceneState(samples[0].dsl, { sceneIndex: 0, width: 800, height: 500 });
+        expect(result.html).toBeDefined();
+        expect(result.html).toContain('<div class="bc-frame"');
+        expect(result.html).toContain('<svg');
     });
     it('clamps sceneIndex when out of bounds', () => {
-        const svg = renderSceneState(samples[0].dsl, { sceneIndex: 999, width: 400, height: 300 });
-        expect(svg).toMatch(/^<svg/);
+        const result = renderSceneState(samples[0].dsl, { sceneIndex: 999, width: 400, height: 300 });
+        expect(result.svg).toMatch(/^<svg/);
     });
     it('throws for unparseable input (callers catch)', () => {
         expect(() => renderSceneState('@@@ nope', { width: 400, height: 300 })).toThrow();

package/dist/render/validatePipeline.d.ts

@@ -0,0 +1,23 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+import { type ToolResult } from '../errors';
+export type ValidatePipelineResult = {
+    ok: true;
+    ast: ChartNode;
+} | {
+    ok: false;
+    error: Extract<ToolResult<never>, {
+        ok: false;
+    }>;
+};
+export interface ValidatePipelineOptions {
+    sceneIndex?: number;
+}
+/**
+ * Run the three-layer validation a renderable chart must pass:
+ *   1. parse (E_PARSE)
+ *   2. semantic validation — unknown types/props, empty data (E_SEMANTIC)
+ *   3. render diagnostic — colorize/highlight resolution, scene index (E_RENDER)
+ * On success returns the parsed AST. On failure returns the structured error
+ * exactly as `render` would, so callers share one set of error semantics.
+ */
+export declare function validatePipeline(source: string, opts?: ValidatePipelineOptions): ValidatePipelineResult;

package/dist/render/validatePipeline.js

@@ -0,0 +1,41 @@
+import { parseDsl } from '../parse';
+import { validateAst } from '../dsl/validate';
+import { diagnoseRender } from './diagnose';
+import { ErrorCode, toolError } from '../errors';
+/**
+ * Run the three-layer validation a renderable chart must pass:
+ *   1. parse (E_PARSE)
+ *   2. semantic validation — unknown types/props, empty data (E_SEMANTIC)
+ *   3. render diagnostic — colorize/highlight resolution, scene index (E_RENDER)
+ * On success returns the parsed AST. On failure returns the structured error
+ * exactly as `render` would, so callers share one set of error semantics.
+ */
+export function validatePipeline(source, opts = {}) {
+    const parseResult = parseDsl(source);
+    if (!parseResult.ok) {
+        return { ok: false, error: parseResult };
+    }
+    const issues = validateAst(parseResult.data.ast);
+    if (issues.length > 0) {
+        const entries = issues.map(i => ({
+            code: i.code,
+            path: i.path,
+            message: i.message,
+            suggestion: i.suggestion,
+            context: i.context,
+        }));
+        return { ok: false, error: toolError(ErrorCode.E_SEMANTIC, entries) };
+    }
+    const diag = diagnoseRender(source, { sceneIndex: opts.sceneIndex });
+    if (!diag.ok) {
+        const entries = diag.diagnostics.map(d => ({
+            code: d.code,
+            path: d.path,
+            message: d.message,
+            suggestion: d.suggestion,
+            context: d.context,
+        }));
+        return { ok: false, error: toolError(ErrorCode.E_RENDER, entries) };
+    }
+    return { ok: true, ast: parseResult.data.ast };
+}

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

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

package/dist/render/validatePipeline.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { validatePipeline } from './validatePipeline';
+import { ErrorCode } from '../errors';
+describe('validatePipeline', () => {
+    it('returns ok with the parsed AST for a valid source', () => {
+        const result = validatePipeline('chart bar-vertical {\n  data {\n    "A" = 1\n  }\n}\n');
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.ast.chartType).toBe('bar-vertical');
+        }
+    });
+    it('returns E_PARSE on a syntax error', () => {
+        const result = validatePipeline('chart bar-vertical {');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe(ErrorCode.E_PARSE);
+        }
+    });
+    it('returns E_SEMANTIC for an unknown chart type', () => {
+        const result = validatePipeline('chart not-a-chart {\n  data {\n    "A" = 1\n  }\n}\n');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe(ErrorCode.E_SEMANTIC);
+            expect(result.error.errors[0]?.suggestion).toBeDefined();
+        }
+    });
+    it('returns E_RENDER when a render diagnostic fails (unresolved highlight)', () => {
+        const result = validatePipeline('chart bar-vertical {\n  highlight "Z"\n  data {\n    "A" = 1\n  }\n}\n');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe(ErrorCode.E_RENDER);
+        }
+    });
+});

package/dist/resources/docsReader.d.ts

@@ -1,10 +1,13 @@
-import { type DocEntry } from '@blueprint-chart/docs';
+import { type DocGroup, type DocEntry } from '@blueprint-chart/docs';
 export interface UriResource {
     uri: string;
     name: string;
     description?: string;
     mimeType: string;
+    docsUrl?: string;
 }
+/** Public docs page URL for a docs group + slug, or undefined when docs base is unset. */
+export declare function publicDocUrl(group: DocGroup, slug: string): string | undefined;
 export declare function listAllResources(): UriResource[];
 export declare function readResource(uri: string): {
     uri: string;

package/dist/resources/docsReader.js

@@ -1,4 +1,6 @@
 import { getDoc, listDocs } from '@blueprint-chart/docs';
+import { getDocsBaseUrl } from '../links/editorConfig';
+import { buildDocUrl } from '../links/buildUrls';
 const GROUP_TO_URI = {
     'handbook': 'bpc://handbook/',
     'guide': 'bpc://guide/',
@@ -8,14 +10,29 @@ const GROUP_TO_URI = {
 };
 const URI_TO_GROUP = Object.entries(GROUP_TO_URI).map(([group, prefix]) => ({ prefix, group }));
 const GRAMMAR_URI = 'bpc://grammar';
+/** Public docs page URL for a docs group + slug, or undefined when docs base is unset. */
+export function publicDocUrl(group, slug) {
+    const base = getDocsBaseUrl();
+    if (!base) {
+        return undefined;
+    }
+    return buildDocUrl(group, slug, base);
+}
 export function listAllResources() {
     const groups = Object.keys(GROUP_TO_URI);
-    const docResources = groups.flatMap(group => listDocs(group).map(entry => ({
-        uri: `${GROUP_TO_URI[group]}${entry.slug}`,
-        name: entry.title,
-        description: entry.blurb,
-        mimeType: 'text/markdown',
-    })));
+    const docResources = groups.flatMap(group => listDocs(group).map((entry) => {
+        const resource = {
+            uri: `${GROUP_TO_URI[group]}${entry.slug}`,
+            name: entry.title,
+            description: entry.blurb,
+            mimeType: 'text/markdown',
+        };
+        const docsUrl = publicDocUrl(group, entry.slug);
+        if (docsUrl) {
+            resource.docsUrl = docsUrl;
+        }
+        return resource;
+    }));
     return [
         {
             uri: GRAMMAR_URI,

package/dist/resources/docsReader.test.js

@@ -1,5 +1,30 @@
-import { describe, expect, it } from 'vitest';
-import { listAllResources, readResource } from './docsReader';
+import { afterEach, describe, expect, it } from 'vitest';
+import { listAllResources, publicDocUrl, readResource } from './docsReader';
+afterEach(() => {
+    delete process.env.BLUEPRINT_CHART_DOCS_URL;
+});
+describe('publicDocUrl', () => {
+    it('returns undefined when docs base is unset', () => {
+        expect(publicDocUrl('charts', 'bar-vertical')).toBeUndefined();
+    });
+    it('builds a public docs URL when configured', () => {
+        process.env.BLUEPRINT_CHART_DOCS_URL = 'https://docs.blueprintchart.com';
+        expect(publicDocUrl('charts', 'bar-vertical')).toBe('https://docs.blueprintchart.com/charts/bar-vertical');
+    });
+});
+describe('listAllResources docsUrl', () => {
+    it('omits docsUrl when docs base is unset', () => {
+        const grammar = listAllResources().find(r => r.uri === 'bpc://grammar');
+        const charts = listAllResources().find(r => r.uri.startsWith('bpc://chart-types/'));
+        expect(grammar?.docsUrl).toBeUndefined();
+        expect(charts?.docsUrl).toBeUndefined();
+    });
+    it('includes docsUrl on doc resources when configured', () => {
+        process.env.BLUEPRINT_CHART_DOCS_URL = 'https://docs.blueprintchart.com';
+        const charts = listAllResources().find(r => r.uri.startsWith('bpc://chart-types/'));
+        expect(charts?.docsUrl).toMatch(/^https:\/\/docs\.blueprintchart\.com\/charts\//);
+    });
+});
 describe('docsReader', () => {
     it('lists handbook entries', () => {
         const list = listAllResources();

package/dist/resources/index.d.ts

@@ -1,4 +1,4 @@
-export declare function listResources(): import("./docsReader").UriResource[];
+export declare function listResources(): import("./samples").SampleResource[];
 export declare function readResource(uri: string): {
     uri: string;
     mimeType: string;

package/dist/resources/samples.d.ts

@@ -1,4 +1,4 @@
-interface SampleResource {
+export interface SampleResource {
     uri: string;
     name: string;
     description?: string;
@@ -10,4 +10,3 @@ export declare function readSampleResource(uri: string): {
     mimeType: string;
     text: string;
 };
-export {};

package/dist/server.d.ts

@@ -1,2 +1,11 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { zodToJsonSchema } from './lib/zodToJsonSchema';
+import type { ToolResult } from './errors';
+interface ToolDef {
+    description: string;
+    inputSchema: Parameters<typeof zodToJsonSchema>[0];
+    handler: (args: unknown) => ToolResult<unknown> | Promise<ToolResult<unknown>>;
+}
+export declare const TOOLS: Record<string, ToolDef>;
 export declare function createServer(): Server;
+export {};

package/dist/server.js

@@ -1,20 +1,45 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { validateDsl, ValidateInputSchema } from './tools/validate';
 import { inspectDsl, InspectInputSchema } from './tools/inspect';
 import { recommendChartType, RecommendInputSchema } from './tools/recommend';
 import { renderTool, RenderInputSchema } from './tools/render';
+import { listChartTypes, ListChartTypesInputSchema } from './tools/listChartTypes';
+import { describeChartType, DescribeChartTypeInputSchema } from './tools/describeChartType';
+import { getExample, GetExampleInputSchema } from './tools/getExample';
+import { getGrammar, GetGrammarInputSchema } from './tools/getGrammar';
+import { exportChart, ExportChartInputSchema } from './tools/exportChart';
 import { listResources, readResource } from './resources/index';
 import { authorChartPrompt } from './prompts/authorChart';
 import { zodToJsonSchema } from './lib/zodToJsonSchema';
-const TOOLS = {
+// Server metadata is embedded into every `initialize` response's `serverInfo`.
+// Icons are advertised only when `MCP_PUBLIC_URL` is set (e.g. on a hosted
+// deployment) — they must be absolute URLs because some MCP clients reject
+// `data:` URIs. For stdio / local use the env var is typically unset and the
+// `icons` field is omitted entirely.
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+function buildServerIcons() {
+    const baseUrl = process.env.MCP_PUBLIC_URL?.trim().replace(/\/+$/, '');
+    if (!baseUrl) {
+        return undefined;
+    }
+    return [
+        { src: `${baseUrl}/favicon.svg`, mimeType: 'image/svg+xml' },
+        { src: `${baseUrl}/favicon.png`, mimeType: 'image/png', sizes: ['256x256'] },
+    ];
+}
+export const TOOLS = {
     validate_dsl: {
-        description: 'Parse a .bpc source string. Return ok or precise parse errors with line/column.',
+        description: 'Parse and semantically validate a .bpc source. Returns { valid, errors[], warnings[] }. Errors include unknown chart types, unknown properties, and empty data blocks with nearest-neighbour suggestions.',
         inputSchema: ValidateInputSchema,
         handler: args => validateDsl(args),
     },
     inspect_dsl: {
-        description: 'Parse a .bpc source and return a structured summary: chartType, scenes, series count, annotations, etc.',
+        description: 'Parse a .bpc source and return a structured summary: chartType, scenes, data (rowCount, entryCount, labels, seriesNames, multiSeries), annotation/colorize/highlight/area-fill presence flags, series count.',
         inputSchema: InspectInputSchema,
         handler: args => inspectDsl(args),
     },
@@ -24,10 +49,35 @@ const TOOLS = {
         handler: args => recommendChartType(args),
     },
     render: {
-        description: 'Render a .bpc source to SVG (default) or PNG. Accepts scene index, width, height.',
+        description: 'Render a .bpc source to SVG (default), PNG, or HTML. Always returns structured frame metadata (title, description, byline, source, sourceUrl, note). Pass `save: <path>` to write the primary output to disk and omit it from the response — useful when the LLM client cannot display binary payloads inline. Saving requires MCP_ALLOW_FS_WRITE=1.',
         inputSchema: RenderInputSchema,
         handler: args => renderTool(args),
     },
+    list_chart_types: {
+        description: 'List every chart type the renderer supports, with aliases and one-line summaries. Call this before writing .bpc if unsure which type to use.',
+        inputSchema: ListChartTypesInputSchema,
+        handler: () => listChartTypes(),
+    },
+    describe_chart_type: {
+        description: 'Return everything an LLM needs to write a .bpc for a given chart type. Input: { chartType: "bar-horizontal" } (or any canonical/alias name from list_chart_types). Returns summary, when-to-use, when-NOT-to-use, full property list with enum choices, data-shape example, and a pointer to a canonical sample.',
+        inputSchema: DescribeChartTypeInputSchema,
+        handler: args => describeChartType(args),
+    },
+    get_example: {
+        description: 'Return a canonical .bpc example. Pass { name } for a specific sample id, { chartType } for the first sample of that type, or no args for a starter sample.',
+        inputSchema: GetExampleInputSchema,
+        handler: args => getExample(args),
+    },
+    get_grammar: {
+        description: 'Return the .bpc DSL grammar as markdown. Pass { section: "chart" | "data" | "properties" | "scenes" | "annotations" } for a focused subset, or no args for the full grammar.',
+        inputSchema: GetGrammarInputSchema,
+        handler: args => getGrammar(args),
+    },
+    export_chart: {
+        description: 'Turn a validated .bpc source into shareable editor URLs. Validates the source through the same parse/semantic/render pipeline as `render`; on success returns { copyUrl, embedUrl, frame }. copyUrl opens an editable copy in the editor ("anyone can open this to view and copy"); embedUrl is a read-only render target suitable as an iframe src. Returns E_CONFIG if the server has no editor base URL configured (BLUEPRINT_CHART_EDITOR_URL).',
+        inputSchema: ExportChartInputSchema,
+        handler: args => exportChart(args),
+    },
 };
 function formatToolResult(result) {
     if (result.ok) {
@@ -39,7 +89,15 @@ function formatToolResult(result) {
     };
 }
 export function createServer() {
-    const server = new Server({ name: '@blueprint-chart/mcp', version: '0.1.0' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+    const icons = buildServerIcons();
+    const server = new Server({
+        name: '@blueprint-chart/mcp',
+        title: 'Blueprint Chart',
+        version: PKG.version,
+        description: PKG.description,
+        websiteUrl: PKG.homepage,
+        ...(icons && { icons }),
+    }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: Object.entries(TOOLS).map(([name, def]) => ({
             name,