@nowline/mcp 0.6.0 → 0.8.0

package/dist/server.js

@@ -1,65 +1,65 @@
 // @nowline/mcp server factory.
 //
-// Creates and configures an McpServer instance with all eight tools and two
-// resources (nowline://reference + nowline://examples).  The factory is shared
-// by the entry-point bin (npx @nowline/mcp) and the CLI's --mcp flag so both
-// paths expose an identical surface.
+// Creates and configures an McpServer instance with all tools, resources, and
+// prompts.  The factory is shared by the entry-point bin (npx @nowline/mcp)
+// and the CLI's --mcp flag so both paths expose an identical surface.
 //
-// Spec: specs/mcp.md.  Plan: export_determinism s8 + s9.
+// Spec: specs/mcp.md.
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
+import { getUiCapability, RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from '@modelcontextprotocol/ext-apps/server';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { collectDocumentDiagnostics, createNowlineServices } from '@nowline/core';
+import { parseNowlineJson, printNowlineFile } from '@nowline/core';
 import { exportDocument, } from '@nowline/export';
 import { resolveFonts } from '@nowline/export-core';
-import { URI } from 'langium';
+import { buildShareLink } from '@nowline/share-link';
 import { z } from 'zod';
-import { EXAMPLES, REFERENCE_MAN_PAGE } from './generated/resources.js';
-function collectMcpDiagnostics(doc, filePath) {
-    const raw = collectDocumentDiagnostics(doc);
-    const out = [];
-    for (const d of raw) {
-        if (d.origin === 'lexer' || d.origin === 'parser') {
-            out.push({
-                file: filePath,
-                line: 1,
-                column: 1,
-                severity: 'error',
-                code: d.origin === 'lexer' ? 'lexing-error' : 'parsing-error',
-                message: d.error.message,
-            });
-        }
-        else {
-            const diag = d.diagnostic;
-            const range = diag.range;
-            out.push({
-                file: filePath,
-                line: (range?.start.line ?? 0) + 1,
-                column: (range?.start.character ?? 0) + 1,
-                severity: diag.severity === 1 ? 'error' : 'warning',
-                code: String(diag.code ?? 'unknown'),
-                message: diag.message,
-            });
-        }
-    }
-    return out;
-}
-// ---- Langium services -------------------------------------------------------
-let cachedServices;
-let docCounter = 0;
-function getServices() {
-    if (!cachedServices)
-        cachedServices = createNowlineServices();
-    return cachedServices;
+import { NOWLINE_MCP_ICONS } from './branding.js';
+import { CAPABILITIES } from './capabilities.js';
+import { buildDocument, collectMcpDiagnostics, collectMcpLayoutInsights, DEFAULT_RENDER_WIDTH, diagnosticsErrorBlock, LAYOUT_INSIGHT_HINT, REVIEW_MAX_WIDTH, toolDescriptionWithSyntax, } from './diagnostics.js';
+import { CONVERSIONS_GUIDE, EXAMPLES, REFERENCE_MAN_PAGE, } from './generated/resources.js';
+import { PREVIEW_HTML } from './generated/ui-bundle.js';
+import { registerPrompts } from './prompts.js';
+import { REFERENCE_CHEATSHEET } from './reference-cheatsheet.js';
+import { SCHEMA_VOCABULARY } from './schema-vocab.js';
+import { CapabilitiesOutputSchema, ConvertOutputSchema, CreateOutputSchema, DeleteOutputSchema, ExamplesOutputSchema, ExportOutputSchema, ListItemsOutputSchema, ListOutputSchema, ReadOutputSchema, ReferenceOutputSchema, RenderOutputSchema, SchemaOutputSchema, UpdateOutputSchema, ValidateOutputSchema, } from './schemas.js';
+// ---- MCP Apps UI (in-chat live preview) -------------------------------------
+//
+// Official MCP Apps model (SEP-1865): a pre-declared ui:// resource serves
+// static HTML; the render tool declares _meta.ui.resourceUri; per-call data
+// flows through the ontoolresult handshake. When an MCP Apps host is active,
+// render returns a lean nowline.preview JSON payload (no inline SVG/PNG) so
+// results stay under the host's ~150K inline cap. Non-apps hosts still get
+// the full SVG/PNG inline (graceful degradation).
+/** SEP-1865 UI extension capability id; also probed under common short keys. */
+const MCP_APPS_UI_CAPABILITY = 'io.modelcontextprotocol/ui';
+/** Versioned URI doubles as a cache key — bump suffix on bundle changes. */
+export const PREVIEW_UI_URI = 'ui://nowline/preview-v1';
+function clientSupportsAppsUi(server) {
+    // SEP-1724 negotiated extensions: canonical id under `extensions`.
+    const caps = server.server.getClientCapabilities();
+    if (!caps)
+        return false;
+    if (getUiCapability(caps))
+        return true;
+    // Hosts also advertise under `experimental` or short `ui` / `apps` aliases.
+    const buckets = [caps.extensions, caps.experimental].filter((bucket) => Boolean(bucket));
+    return buckets.some((bucket) => Boolean(bucket[MCP_APPS_UI_CAPABILITY] || bucket.ui || bucket.apps));
 }
-async function buildDocument(source) {
-    const services = getServices();
-    const uri = URI.parse(`memory:///mcp-${++docCounter}.nowline`);
-    const doc = services.shared.workspace.LangiumDocumentFactory.fromString(source, uri);
-    await services.shared.workspace.DocumentBuilder.build([doc], { validation: true });
-    return doc;
+function leanPreviewBlock(payload) {
+    return {
+        type: 'text',
+        text: JSON.stringify({
+            kind: 'nowline.preview',
+            source: payload.source,
+            theme: payload.theme,
+            now: payload.now,
+            width: payload.width,
+            locale: payload.locale,
+        }),
+    };
 }
-// ---- Allowed-root enforcement -----------------------------------------------
+// ---- Server factory ---------------------------------------------------------
 function resolveAndGuard(filePath, allowedRoot) {
     const abs = path.resolve(allowedRoot, filePath);
     const guard = path.resolve(allowedRoot);
@@ -84,7 +84,6 @@ function createNodeHostEnv(sourcePath) {
             return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
         },
         async loadWasm() {
-            // Resolve resvg.wasm relative to @nowline/export-png/dist/ at runtime.
             const { createRequire } = await import('node:module');
             const req = createRequire(import.meta.url);
             const entry = req.resolve('@resvg/resvg-wasm');
@@ -100,6 +99,13 @@ function todayUtc() {
     const now = new Date();
     return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
 }
+function exampleShortName(fullName) {
+    return fullName.endsWith('.nowline') ? fullName.slice(0, -'.nowline'.length) : fullName;
+}
+function findExample(name) {
+    const withExt = name.endsWith('.nowline') ? name : `${name}.nowline`;
+    return EXAMPLES.find((e) => e.name === withExt || e.name === name);
+}
 async function sourceAndPath(args, allowedRoot) {
     if (args.source !== undefined && args.path === undefined) {
         return { source: args.source, filePath: path.join(allowedRoot, 'unnamed.nowline') };
@@ -115,7 +121,15 @@ export function createMcpServer(opts = {}) {
     const allowedRoot = opts.allowedRoot ?? process.cwd();
     const server = new McpServer({
         name: opts.name ?? 'nowline',
-        version: opts.version ?? '0.5.1',
+        version: opts.version ?? '0.6.0',
+        icons: [...NOWLINE_MCP_ICONS],
+    }, {
+        instructions: 'Nowline manages roadmaps written in the .nowline plain-text DSL — NOT JSON or any other ' +
+            'structured format. All `source` parameters expect `.nowline` DSL text (starts with `nowline v1`). ' +
+            'Workflow: 1. call `reference` or `examples` to learn syntax → 2. write `.nowline` → ' +
+            '3. call `render` (validates + renders; or `validate` alone) → 4. fix errors keyed on `NL.E####` ' +
+            'and re-render → 5. review returned layout `insights` (what reflowed) → 6. when uncertain, ' +
+            'call `render` with `review:true` for a final visual check. JSON in `convert` is AST conversion only.',
     });
     // ---- Resources ----------------------------------------------------------
     server.registerResource('nowline-reference', 'nowline://reference', {
@@ -136,9 +150,34 @@ export function createMcpServer(opts = {}) {
             mimeType: 'text/plain',
         })),
     }));
+    server.registerResource('nowline-conversions', 'nowline://conversions', {
+        description: 'LLM-mediated conversion guide: how to translate Mermaid gantt, MS Project, Excel, Google Sheets timeline, and generic CSV into Nowline DSL.',
+        mimeType: 'text/plain',
+    }, async () => ({
+        contents: [
+            {
+                uri: 'nowline://conversions',
+                text: CONVERSIONS_GUIDE,
+                mimeType: 'text/plain',
+            },
+        ],
+    }));
+    registerAppResource(server, 'nowline-preview', PREVIEW_UI_URI, {
+        description: 'Interactive in-chat roadmap preview (MCP Apps). Hydrates via ontoolresult.',
+    }, async () => ({
+        contents: [
+            {
+                uri: PREVIEW_UI_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: PREVIEW_HTML,
+            },
+        ],
+    }));
+    // ---- Prompts ------------------------------------------------------------
+    registerPrompts(server);
     // ---- validate -----------------------------------------------------------
     server.registerTool('validate', {
-        description: 'Parse and validate a .nowline roadmap. Returns ok=true and an empty diagnostics array if valid, or ok=false with structured diagnostics.',
+        description: toolDescriptionWithSyntax('Parse and validate a .nowline roadmap. Returns ok=true with optional layout insights when valid, or ok=false with structured diagnostics.'),
         inputSchema: z.object({
             source: z.string().optional().describe('Inline .nowline source text to validate.'),
             path: z
@@ -146,13 +185,32 @@ export function createMcpServer(opts = {}) {
                 .optional()
                 .describe('Absolute or relative path to a .nowline file to validate.'),
         }),
+        outputSchema: ValidateOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
     }, async (args) => {
         const { source, filePath } = await sourceAndPath(args, allowedRoot);
         const doc = await buildDocument(source);
         const diagnostics = collectMcpDiagnostics(doc, filePath);
         const ok = diagnostics.every((d) => d.severity !== 'error');
+        const insights = ok
+            ? await collectMcpLayoutInsights({
+                source,
+                filePath,
+                today: todayUtc(),
+                locale: 'en-US',
+                readFile: createNodeHostEnv(filePath).readSource,
+                doc,
+            })
+            : [];
+        const structured = { ok, diagnostics, ...(insights.length > 0 ? { insights } : {}) };
         return {
-            content: [{ type: 'text', text: JSON.stringify({ ok, diagnostics }, null, 2) }],
+            content: [
+                { type: 'text', text: JSON.stringify(structured, null, 2) },
+                ...(insights.length > 0
+                    ? [{ type: 'text', text: LAYOUT_INSIGHT_HINT }]
+                    : []),
+            ],
+            structuredContent: structured,
         };
     });
     // ---- read ---------------------------------------------------------------
@@ -163,75 +221,61 @@ export function createMcpServer(opts = {}) {
                 .string()
                 .describe('Absolute or relative path to the .nowline file to read.'),
         }),
+        outputSchema: ReadOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
     }, async (args) => {
         const abs = resolveAndGuard(args.path, allowedRoot);
         const source = await fs.readFile(abs, 'utf-8');
+        const structured = { path: abs, source };
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({ path: abs, source }, null, 2),
-                },
-            ],
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     });
     // ---- create -------------------------------------------------------------
     server.registerTool('create', {
-        description: 'Write a new .nowline file after validation. Overwrites if the path already exists.',
+        description: toolDescriptionWithSyntax('Write a new .nowline file after validation. Overwrites if the path already exists.'),
         inputSchema: z.object({
             path: z.string().describe('Absolute or relative path to write the .nowline file.'),
             source: z.string().describe('The .nowline source text to write.'),
         }),
+        outputSchema: CreateOutputSchema,
+        // Overwrites silently → destructive; same source always produces same file → idempotent.
+        annotations: { destructiveHint: true, idempotentHint: true },
     }, async (args) => {
         const abs = resolveAndGuard(args.path, allowedRoot);
-        const doc = await buildDocument(args.source);
-        const diagnostics = collectMcpDiagnostics(doc, abs);
-        const errors = diagnostics.filter((d) => d.severity === 'error');
-        if (errors.length > 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ ok: false, path: abs, diagnostics }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
-        }
+        const blocked = await diagnosticsErrorBlock(args.source, abs);
+        if (!blocked.ok)
+            return blocked.response;
         await fs.mkdir(path.dirname(abs), { recursive: true });
         await fs.writeFile(abs, args.source, 'utf-8');
+        const structured = { ok: true, path: abs };
         return {
-            content: [{ type: 'text', text: JSON.stringify({ ok: true, path: abs }, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     });
     // ---- update -------------------------------------------------------------
     server.registerTool('update', {
-        description: 'Replace an existing .nowline file after validation.',
+        description: toolDescriptionWithSyntax('Replace an existing .nowline file after validation.'),
         inputSchema: z.object({
             path: z
                 .string()
                 .describe('Absolute or relative path of the .nowline file to update.'),
             source: z.string().describe('The new .nowline source text.'),
         }),
+        outputSchema: UpdateOutputSchema,
+        annotations: { idempotentHint: true },
     }, async (args) => {
         const abs = resolveAndGuard(args.path, allowedRoot);
-        const doc = await buildDocument(args.source);
-        const diagnostics = collectMcpDiagnostics(doc, abs);
-        const errors = diagnostics.filter((d) => d.severity === 'error');
-        if (errors.length > 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ ok: false, path: abs, diagnostics }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
-        }
+        const blocked = await diagnosticsErrorBlock(args.source, abs);
+        if (!blocked.ok)
+            return blocked.response;
         await fs.writeFile(abs, args.source, 'utf-8');
+        const structured = { ok: true, path: abs };
         return {
-            content: [{ type: 'text', text: JSON.stringify({ ok: true, path: abs }, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     });
     // ---- delete -------------------------------------------------------------
@@ -242,11 +286,15 @@ export function createMcpServer(opts = {}) {
                 .string()
                 .describe('Absolute or relative path of the .nowline file to delete.'),
         }),
+        outputSchema: DeleteOutputSchema,
+        annotations: { destructiveHint: true },
     }, async (args) => {
         const abs = resolveAndGuard(args.path, allowedRoot);
         await fs.unlink(abs);
+        const structured = { path: abs };
         return {
-            content: [{ type: 'text', text: JSON.stringify({ path: abs }, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     });
     // ---- list ---------------------------------------------------------------
@@ -262,20 +310,30 @@ export function createMcpServer(opts = {}) {
                 .optional()
                 .describe('Whether to scan subdirectories. Defaults to false.'),
         }),
+        outputSchema: ListOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
     }, async (args) => {
         const dir = args.directory ? resolveAndGuard(args.directory, allowedRoot) : allowedRoot;
         const recursive = args.recursive ?? false;
         const paths = await listNowlineFiles(dir, recursive);
+        const structured = { paths };
         return {
-            content: [{ type: 'text', text: JSON.stringify({ paths }, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     });
     // ---- render -------------------------------------------------------------
-    server.registerTool('render', {
-        description: 'Render a .nowline roadmap to SVG or PNG using the shared export kernel. Byte-identical to `nowline -f svg/png` for the same source and inputs.',
+    registerAppTool(server, 'render', {
+        description: toolDescriptionWithSyntax('Validate then render a .nowline roadmap to SVG or PNG (combined validate+render+share). ' +
+            'Returns structured diagnostics on error-severity input instead of a raw kernel error.'),
         inputSchema: z.object({
             source: z.string().optional().describe('Inline .nowline source text.'),
-            path: z.string().optional().describe('Path to the .nowline file.'),
+            path: z
+                .string()
+                .optional()
+                .describe('Real local filesystem path to the .nowline file (e.g. /Users/name/Desktop/foo.nowline). ' +
+                'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                'those do not exist on the host filesystem. Pass `source` instead.'),
             format: z
                 .enum(['svg', 'png'])
                 .optional()
@@ -296,10 +354,33 @@ export function createMcpServer(opts = {}) {
             output: z
                 .string()
                 .optional()
-                .describe('Write output to this path instead of returning inline.'),
+                .describe('Real local filesystem path to write the output file (e.g. /Users/name/Desktop/roadmap.svg). ' +
+                'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                'omit this parameter to receive output inline instead.'),
+            share: z
+                .boolean()
+                .optional()
+                .describe('When true, include a shareUrl pointing to https://free.nowline.io/open.'),
+            review: z
+                .boolean()
+                .optional()
+                .describe('When true, also attach a downscaled PNG so a multimodal model can visually check layout (label overflow, lane crowding, off-range now-line). Off by default.'),
+            preview: z
+                .boolean()
+                .optional()
+                .describe('When true, force the in-chat MCP Apps preview. On MCP Apps hosts the preview auto-renders via _meta.ui without this flag.'),
         }),
+        outputSchema: RenderOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        _meta: {
+            ui: { resourceUri: PREVIEW_UI_URI },
+            'openai/outputTemplate': PREVIEW_UI_URI,
+        },
     }, async (args) => {
         const { source, filePath } = await sourceAndPath(args, allowedRoot);
+        const blocked = await diagnosticsErrorBlock(source, filePath);
+        if (!blocked.ok)
+            return blocked.response;
         const format = args.format ?? 'svg';
         const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
         const inputs = {
@@ -310,26 +391,81 @@ export function createMcpServer(opts = {}) {
             width: args.width,
             pngScale: args.scale,
         };
-        if (format === 'png') {
+        const host = createNodeHostEnv(filePath);
+        const appActive = args.preview === true || clientSupportsAppsUi(server);
+        // Skip the full render when the bytes won't be used: apps host with
+        // no write-to-disk path and no review attachment requested.
+        const needsRender = !appActive || !!args.output || args.review === true;
+        if (needsRender && (format === 'png' || args.review === true)) {
             const result = await resolveFonts({ headless: true });
             inputs.fonts = { sans: result.sans, mono: result.mono };
         }
-        const host = createNodeHostEnv(filePath);
-        const bytes = await exportDocument(source, format, inputs, host);
+        const bytes = needsRender
+            ? await exportDocument(source, format, inputs, host)
+            : new Uint8Array(0);
+        const shareUrl = args.share
+            ? (buildShareLink({ source, share: true }) ?? undefined)
+            : undefined;
+        const insights = await collectMcpLayoutInsights({
+            source,
+            filePath,
+            today,
+            theme: args.theme ?? 'light',
+            width: args.width,
+            locale: 'en-US',
+            readFile: host.readSource,
+            doc: blocked.doc,
+        });
+        const previewPayload = {
+            source,
+            theme: args.theme,
+            now: args.now,
+            width: args.width,
+            locale: 'en-US',
+        };
+        const reviewBlocks = args.review === true
+            ? await buildReviewContentBlocks(source, format, bytes, inputs, host)
+            : [];
+        const insightHintBlocks = insights.length > 0 ? [{ type: 'text', text: LAYOUT_INSIGHT_HINT }] : [];
+        const insightsField = insights.length > 0 ? { insights } : {};
         if (args.output) {
             const outAbs = resolveAndGuard(args.output, allowedRoot);
             await fs.mkdir(path.dirname(outAbs), { recursive: true });
             await fs.writeFile(outAbs, bytes);
+            const structured = {
+                format,
+                path: outAbs,
+                bytes: bytes.byteLength,
+                shareUrl,
+                ...insightsField,
+            };
             return {
                 content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ path: outAbs, bytes: bytes.byteLength }),
-                    },
+                    ...(appActive ? [leanPreviewBlock(previewPayload)] : []),
+                    { type: 'text', text: JSON.stringify(structured, null, 2) },
+                    ...insightHintBlocks,
+                    ...reviewBlocks,
+                ],
+                structuredContent: structured,
+            };
+        }
+        if (appActive) {
+            const structured = {
+                format,
+                shareUrl,
+                ...insightsField,
+            };
+            return {
+                content: [
+                    leanPreviewBlock(previewPayload),
+                    ...insightHintBlocks,
+                    ...reviewBlocks,
                 ],
+                structuredContent: structured,
             };
         }
         if (format === 'png') {
+            const structured = { format, bytes: bytes.byteLength, shareUrl, ...insightsField };
             return {
                 content: [
                     {
@@ -337,17 +473,21 @@ export function createMcpServer(opts = {}) {
                         data: Buffer.from(bytes).toString('base64'),
                         mimeType: 'image/png',
                     },
+                    ...insightHintBlocks,
+                    ...reviewBlocks,
                 ],
+                structuredContent: structured,
             };
         }
+        const svgText = new TextDecoder('utf-8').decode(bytes);
+        const structured = { format, shareUrl, ...insightsField };
         return {
             content: [
-                {
-                    type: 'text',
-                    text: new TextDecoder('utf-8').decode(bytes),
-                    mimeType: 'image/svg+xml',
-                },
+                { type: 'text', text: svgText, mimeType: 'image/svg+xml' },
+                ...insightHintBlocks,
+                ...reviewBlocks,
             ],
+            structuredContent: structured,
         };
     });
     // ---- export -------------------------------------------------------------
@@ -356,14 +496,22 @@ export function createMcpServer(opts = {}) {
         description: 'Export a .nowline roadmap to any of the eight canonical formats. Byte-identical to `nowline -f <format>` for the same source and inputs.',
         inputSchema: z.object({
             source: z.string().optional().describe('Inline .nowline source text.'),
-            path: z.string().optional().describe('Path to the .nowline file.'),
+            path: z
+                .string()
+                .optional()
+                .describe('Real local filesystem path to the .nowline file (e.g. /Users/name/Desktop/foo.nowline). ' +
+                'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                'those do not exist on the host filesystem. Pass `source` instead.'),
             format: z
                 .enum(EXPORT_FORMATS)
                 .describe('Export format: pdf, html, mermaid, xlsx, msproj, or png.'),
             output: z
                 .string()
                 .optional()
-                .describe('Path to write the output file. Required for binary formats.'),
+                .describe('Real local filesystem path to write the output (e.g. /Users/name/Desktop/roadmap.pdf). ' +
+                'Required for binary formats (pdf, xlsx, msproj, png). ' +
+                'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                'those do not exist on the host filesystem.'),
             now: z.string().optional().describe('Now-line date as YYYY-MM-DD (UTC).'),
             theme: z.enum(['light', 'dark', 'grayscale']).optional(),
             scale: z.number().optional().describe('PNG scale factor.'),
@@ -377,9 +525,18 @@ export function createMcpServer(opts = {}) {
                 .string()
                 .optional()
                 .describe('MS Project start date override (YYYY-MM-DD).'),
+            share: z
+                .boolean()
+                .optional()
+                .describe('When true, include a shareUrl pointing to https://free.nowline.io/open.'),
         }),
+        outputSchema: ExportOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
     }, async (args) => {
         const { source, filePath } = await sourceAndPath(args, allowedRoot);
+        const blocked = await diagnosticsErrorBlock(source, filePath);
+        if (!blocked.ok)
+            return blocked.response;
         const format = args.format;
         const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
         const inputs = {
@@ -399,19 +556,19 @@ export function createMcpServer(opts = {}) {
         }
         const host = createNodeHostEnv(filePath);
         const bytes = await exportDocument(source, format, inputs, host);
+        const shareUrl = args.share
+            ? (buildShareLink({ source, share: true }) ?? undefined)
+            : undefined;
         const BINARY_FORMATS = new Set(['png', 'pdf', 'xlsx']);
         const isBinary = BINARY_FORMATS.has(format);
         if (args.output) {
             const outAbs = resolveAndGuard(args.output, allowedRoot);
             await fs.mkdir(path.dirname(outAbs), { recursive: true });
             await fs.writeFile(outAbs, bytes);
+            const structured = { format, path: outAbs, bytes: bytes.byteLength, shareUrl };
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ path: outAbs, bytes: bytes.byteLength }),
-                    },
-                ],
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
             };
         }
         if (isBinary) {
@@ -420,6 +577,7 @@ export function createMcpServer(opts = {}) {
                 pdf: 'application/pdf',
                 xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
             };
+            const structured = { format, bytes: bytes.byteLength, shareUrl };
             return {
                 content: [
                     {
@@ -428,20 +586,272 @@ export function createMcpServer(opts = {}) {
                         mimeType: mimeMap[format] ?? 'application/octet-stream',
                     },
                 ],
+                structuredContent: structured,
             };
         }
+        const text = new TextDecoder('utf-8').decode(bytes);
+        const structured = { format, shareUrl };
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: structured,
+        };
+    });
+    // ---- convert ------------------------------------------------------------
+    server.registerTool('convert', {
+        description: 'Convert between .nowline source text and its JSON AST representation. `to:json` serializes a .nowline file to the JSON AST; `to:nowline` pretty-prints a JSON AST back to canonical .nowline source.',
+        inputSchema: z.object({
+            source: z.string().optional().describe('Inline source text to convert.'),
+            path: z
+                .string()
+                .optional()
+                .describe('Real local filesystem path to the source file. ' +
+                'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                'pass `source` instead.'),
+            to: z
+                .enum(['json', 'nowline'])
+                .describe('"json" — serialize .nowline text to JSON AST. "nowline" — pretty-print a JSON AST back to .nowline source.'),
+        }),
+        outputSchema: ConvertOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async (args) => {
+        if (args.to === 'json') {
+            const { source, filePath } = await sourceAndPath(args, allowedRoot);
+            const host = createNodeHostEnv(filePath);
+            const jsonBytes = await exportDocument(source, 'json', {
+                sourcePath: filePath,
+                today: todayUtc(),
+                locale: 'en-US',
+                theme: 'light',
+            }, host);
+            const result = new TextDecoder('utf-8').decode(jsonBytes);
+            const structured = { to: 'json', result };
+            return {
+                content: [{ type: 'text', text: result }],
+                structuredContent: structured,
+            };
+        }
+        // to: 'nowline' — input is a JSON AST string
+        const jsonSource = args.source ??
+            (args.path
+                ? await fs.readFile(resolveAndGuard(args.path, allowedRoot), 'utf-8')
+                : null);
+        if (!jsonSource) {
+            throw new Error('At least one of `source` or `path` is required.');
+        }
+        const { ast } = parseNowlineJson(jsonSource, args.path ?? 'input.json');
+        const result = printNowlineFile(ast);
+        const structured = { to: 'nowline', result };
+        return {
+            content: [{ type: 'text', text: result }],
+            structuredContent: structured,
+        };
+    });
+    // ---- capabilities -------------------------------------------------------
+    server.registerTool('capabilities', {
+        description: 'Return all supported themes, icons, locales, export formats, and template names in a single response.',
+        inputSchema: z.object({}),
+        outputSchema: CapabilitiesOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = {
+            themes: [...CAPABILITIES.themes],
+            icons: [...CAPABILITIES.icons],
+            locales: [...CAPABILITIES.locales],
+            formats: [...CAPABILITIES.formats],
+            templates: [...CAPABILITIES.templates],
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    });
+    // ---- list-themes --------------------------------------------------------
+    server.registerTool('list-themes', {
+        description: 'List supported color themes: light, dark, grayscale.',
+        inputSchema: z.object({}),
+        outputSchema: ListItemsOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = { items: [...CAPABILITIES.themes] };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    });
+    // ---- list-icons ---------------------------------------------------------
+    server.registerTool('list-icons', {
+        description: 'List built-in capacity-icon names usable in the `capacity-icon:` style property.',
+        inputSchema: z.object({}),
+        outputSchema: ListItemsOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = { items: [...CAPABILITIES.icons] };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    });
+    // ---- list-locales -------------------------------------------------------
+    server.registerTool('list-locales', {
+        description: 'List supported BCP-47 locale tags.',
+        inputSchema: z.object({}),
+        outputSchema: ListItemsOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = { items: [...CAPABILITIES.locales] };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    });
+    // ---- list-formats -------------------------------------------------------
+    server.registerTool('list-formats', {
+        description: 'List all supported export formats (svg, png, pdf, html, mermaid, xlsx, msproj, json).',
+        inputSchema: z.object({}),
+        outputSchema: ListItemsOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = { items: [...CAPABILITIES.formats] };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    });
+    // ---- list-templates -----------------------------------------------------
+    server.registerTool('list-templates', {
+        description: 'List built-in template names usable with `nowline --init --template`.',
+        inputSchema: z.object({}),
+        outputSchema: ListItemsOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = { items: [...CAPABILITIES.templates] };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    });
+    // ---- reference / examples / schema (discovery tools) --------------------
+    server.registerTool('reference', {
+        description: 'Return the Nowline DSL reference (condensed cheatsheet or full man page). Callable alternative to the nowline://reference resource.',
+        inputSchema: z.object({
+            format: z
+                .enum(['condensed', 'full'])
+                .optional()
+                .describe('Reference format. Defaults to condensed.'),
+        }),
+        outputSchema: ReferenceOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async (args) => {
+        const format = args.format ?? 'condensed';
+        const text = format === 'full' ? REFERENCE_MAN_PAGE : REFERENCE_CHEATSHEET;
+        const structured = { format, text };
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: structured,
+        };
+    });
+    server.registerTool('examples', {
+        description: 'Return canonical .nowline example sources. Callable alternative to the nowline://examples resource.',
+        inputSchema: z.object({
+            name: z
+                .string()
+                .optional()
+                .describe('Example name. Omit for the catalog plus minimal inline.'),
+        }),
+        outputSchema: ExamplesOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async (args) => {
+        const exampleNames = EXAMPLES.map((e) => exampleShortName(e.name));
+        if (args.name) {
+            const ex = findExample(args.name);
+            if (!ex) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: `Unknown example "${args.name}".`,
+                                names: exampleNames,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const structured = { name: exampleShortName(ex.name), source: ex.content };
+            return {
+                content: [{ type: 'text', text: ex.content }],
+                structuredContent: structured,
+            };
+        }
+        const minimal = findExample('minimal') ?? EXAMPLES[0];
+        const structured = {
+            names: exampleNames,
+            name: exampleShortName(minimal.name),
+            source: minimal.content,
+        };
         return {
             content: [
                 {
                     type: 'text',
-                    text: new TextDecoder('utf-8').decode(bytes),
+                    text: `# Examples\n\n${exampleNames.map((n) => `- ${n}`).join('\n')}\n\n## ${structured.name}\n\n${minimal.content}`,
                 },
             ],
+            structuredContent: structured,
+        };
+    });
+    server.registerTool('schema', {
+        description: 'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties).',
+        inputSchema: z.object({}),
+        outputSchema: SchemaOutputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async () => {
+        const structured = {
+            directiveKeys: [...SCHEMA_VOCABULARY.directiveKeys],
+            entityTypes: [...SCHEMA_VOCABULARY.entityTypes],
+            itemPropertyKeys: [...SCHEMA_VOCABULARY.itemPropertyKeys],
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     });
     return server;
 }
-// ---- Helpers ----------------------------------------------------------------
+async function buildReviewContentBlocks(source, format, artifactBytes, inputs, host) {
+    const blocks = [
+        {
+            type: 'text',
+            text: 'Review this raster for layout issues (truncated labels, crowded lanes, ' +
+                'now-line position) before finalizing.',
+        },
+    ];
+    const artifactWidth = inputs.width ?? DEFAULT_RENDER_WIDTH;
+    let inspectionBytes;
+    if (format === 'png' && artifactWidth <= REVIEW_MAX_WIDTH) {
+        inspectionBytes = artifactBytes;
+    }
+    else {
+        const reviewInputs = {
+            ...inputs,
+            width: Math.min(artifactWidth, REVIEW_MAX_WIDTH),
+            pngScale: 1,
+        };
+        if (!reviewInputs.fonts) {
+            const fonts = await resolveFonts({ headless: true });
+            reviewInputs.fonts = { sans: fonts.sans, mono: fonts.mono };
+        }
+        inspectionBytes = await exportDocument(source, 'png', reviewInputs, host);
+    }
+    if (format !== 'png' || inspectionBytes.byteLength !== artifactBytes.byteLength) {
+        blocks.push({
+            type: 'image',
+            data: Buffer.from(inspectionBytes).toString('base64'),
+            mimeType: 'image/png',
+        });
+    }
+    return blocks;
+}
 async function listNowlineFiles(dir, recursive) {
     const results = [];
     try {