@nowline/mcp 0.6.0 → 0.8.0

package/src/server.ts

@@ -1,16 +1,21 @@
 // @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, type NowlineFile } from '@nowline/core';
+import { parseNowlineJson, printNowlineFile } from '@nowline/core';
 import {
     type ExportFormat,
     exportDocument,
@@ -18,75 +23,104 @@ import {
     type RenderInputs,
 } 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';
-
-// ---- Diagnostic helpers -----------------------------------------------------
+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,
+    type ExampleFile,
+    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';
 
-interface McpDiagnostic {
-    file: string;
-    line: number;
-    column: number;
-    severity: 'error' | 'warning';
-    code: string;
-    message: string;
-}
+// ---- 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).
 
-function collectMcpDiagnostics(
-    doc: Awaited<ReturnType<typeof buildDocument>>,
-    filePath: string,
-): McpDiagnostic[] {
-    const raw = collectDocumentDiagnostics(doc);
-    const out: McpDiagnostic[] = [];
-    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;
-}
+/** 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';
 
-// ---- Langium services -------------------------------------------------------
+function clientSupportsAppsUi(server: McpServer): boolean {
+    // SEP-1724 negotiated extensions: canonical id under `extensions`.
+    const caps = server.server.getClientCapabilities() as
+        | {
+              experimental?: Record<string, unknown>;
+              extensions?: Record<string, unknown>;
+          }
+        | undefined;
+    if (!caps) return false;
+    if (getUiCapability(caps as Parameters<typeof getUiCapability>[0])) return true;
 
-let cachedServices: ReturnType<typeof createNowlineServices> | undefined;
-let docCounter = 0;
+    // Hosts also advertise under `experimental` or short `ui` / `apps` aliases.
+    const buckets = [caps.extensions, caps.experimental].filter(
+        (bucket): bucket is Record<string, unknown> => Boolean(bucket),
+    );
+    return buckets.some((bucket) =>
+        Boolean(bucket[MCP_APPS_UI_CAPABILITY] || bucket.ui || bucket.apps),
+    );
+}
 
-function getServices() {
-    if (!cachedServices) cachedServices = createNowlineServices();
-    return cachedServices;
+interface PreviewPayload {
+    source: string;
+    theme?: string;
+    now?: string;
+    width?: number;
+    locale?: string;
 }
 
-async function buildDocument(source: string) {
-    const services = getServices();
-    const uri = URI.parse(`memory:///mcp-${++docCounter}.nowline`);
-    const doc = services.shared.workspace.LangiumDocumentFactory.fromString<NowlineFile>(
-        source,
-        uri,
-    );
-    await services.shared.workspace.DocumentBuilder.build([doc], { validation: true });
-    return doc;
+function leanPreviewBlock(payload: PreviewPayload) {
+    return {
+        type: 'text' as const,
+        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: string, allowedRoot: string): string {
     const abs = path.resolve(allowedRoot, filePath);
@@ -114,7 +148,6 @@ function createNodeHostEnv(sourcePath: string): HostEnv {
             return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
         },
         async loadWasm(): Promise<ArrayBuffer> {
-            // 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');
@@ -133,6 +166,15 @@ function todayUtc(): Date {
     return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
 }
 
+function exampleShortName(fullName: string): string {
+    return fullName.endsWith('.nowline') ? fullName.slice(0, -'.nowline'.length) : fullName;
+}
+
+function findExample(name: string): ExampleFile | undefined {
+    const withExt = name.endsWith('.nowline') ? name : `${name}.nowline`;
+    return EXAMPLES.find((e) => e.name === withExt || e.name === name);
+}
+
 async function sourceAndPath(
     args: { source?: string; path?: string },
     allowedRoot: string,
@@ -161,10 +203,22 @@ export interface McpServerOptions {
 
 export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     const allowedRoot = opts.allowedRoot ?? process.cwd();
-    const server = new McpServer({
-        name: opts.name ?? 'nowline',
-        version: opts.version ?? '0.5.1',
-    });
+    const server = new McpServer(
+        {
+            name: opts.name ?? 'nowline',
+            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 ----------------------------------------------------------
 
@@ -199,13 +253,56 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         }),
     );
 
+    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
@@ -213,14 +310,33 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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' as const, text: LAYOUT_INSIGHT_HINT }]
+                        : []),
+                ],
+                structuredContent: structured,
             };
         },
     );
@@ -236,17 +352,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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,
             };
         },
     );
@@ -256,33 +371,27 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     server.registerTool(
         'create',
         {
-            description:
+            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,
             };
         },
     );
@@ -292,33 +401,27 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     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,
             };
         },
     );
@@ -334,12 +437,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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,
             };
         },
     );
@@ -362,27 +469,41 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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(
+    registerAppTool(
+        server,
         '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.',
+            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()
@@ -403,11 +524,42 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 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: ExportFormat = args.format ?? 'svg';
             const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
             const inputs: RenderInputs = {
@@ -418,28 +570,90 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 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: 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' as const, 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' as const, 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: [
                         {
@@ -447,17 +661,21 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                             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,
             };
         },
     );
@@ -474,14 +692,26 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 '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.'),
@@ -495,10 +725,21 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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: ExportFormat = args.format as NonRenderFormat;
             const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
             const inputs: RenderInputs = {
@@ -518,6 +759,9 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             }
             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<ExportFormat>(['png', 'pdf', 'xlsx']);
             const isBinary = BINARY_FORMATS.has(format);
@@ -526,13 +770,10 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 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,
                 };
             }
 
@@ -542,6 +783,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     pdf: 'application/pdf',
                     xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
                 };
+                const structured = { format, bytes: bytes.byteLength, shareUrl };
                 return {
                     content: [
                         {
@@ -550,15 +792,310 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                             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' as const, 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' as const, 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,
             };
         },
     );
@@ -568,6 +1105,55 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
 // ---- Helpers ----------------------------------------------------------------
 
+type ContentBlock =
+    | { type: 'text'; text: string; mimeType?: string }
+    | { type: 'image'; data: string; mimeType: string };
+
+async function buildReviewContentBlocks(
+    source: string,
+    format: ExportFormat,
+    artifactBytes: Uint8Array,
+    inputs: RenderInputs,
+    host: HostEnv,
+): Promise<ContentBlock[]> {
+    const blocks: ContentBlock[] = [
+        {
+            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: Uint8Array;
+
+    if (format === 'png' && artifactWidth <= REVIEW_MAX_WIDTH) {
+        inspectionBytes = artifactBytes;
+    } else {
+        const reviewInputs: RenderInputs = {
+            ...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: string, recursive: boolean): Promise<string[]> {
     const results: string[] = [];
     try {