@nowline/mcp 0.7.0 → 0.8.1

package/dist/server.js

@@ -7,128 +7,81 @@
 // 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, parseNowlineJson, printNowlineFile, } from '@nowline/core';
+import { parseNowlineJson, printNowlineFile } from '@nowline/core';
 import { exportDocument, } from '@nowline/export';
 import { resolveFonts } from '@nowline/export-core';
 import { buildShareLink } from '@nowline/share-link';
-import { URI } from 'langium';
 import { z } from 'zod';
+import { NOWLINE_MCP_ICONS } from './branding.js';
 import { CAPABILITIES } from './capabilities.js';
-import { CONVERSIONS_GUIDE, EXAMPLES, REFERENCE_MAN_PAGE } from './generated/resources.js';
-import { UI_BUNDLE } from './generated/ui-bundle.js';
+import { buildDocument, collectMcpDiagnostics, collectMcpLayoutInsights, DEFAULT_RENDER_WIDTH, diagnosticsErrorBlock, handleToolError, InputRequiredError, LAYOUT_INSIGHT_HINT, PathOutsideRootError, 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 { CapabilitiesOutputSchema, ConvertOutputSchema, CreateOutputSchema, DeleteOutputSchema, ExportOutputSchema, ListItemsOutputSchema, ListOutputSchema, ReadOutputSchema, RenderOutputSchema, UpdateOutputSchema, ValidateOutputSchema, } from './schemas.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) -------------------------------------
 //
-// The MCP Apps extension (SEP-1865) lets a tool return an interactive HTML
-// resource the host renders in a sandboxed iframe. We use the embedded-resource
-// form: `render` returns a self-contained text/html resource that inlines the
-// browser preview bundle (UI_BUNDLE, the @nowline/browser + @nowline/preview-
-// shell pipeline) plus the injected source. It is emitted only when the client
-// advertises the UI extension capability or the caller passes `preview: true`,
-// so plain stdio operation is unchanged and non-UI hosts still receive the
-// SVG/PNG content block alongside it (graceful degradation).
+// 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';
-const PREVIEW_UI_URI = 'ui://nowline/preview';
-/** SEP-1865 mandates the text/html;profile=mcp-app media type for UI resources. */
-const PREVIEW_UI_MIME = 'text/html;profile=mcp-app';
+/** Versioned URI doubles as a cache key — bump suffix on bundle changes. */
+export const PREVIEW_UI_URI = 'ui://nowline/preview-v1';
 function clientSupportsAppsUi(server) {
-    // Extension capabilities are negotiated under `experimental` in SDK 1.29
-    // (it does not yet model SEP-1724 extensions as a first-class field), so
-    // probe the canonical id plus the short `ui` / `apps` aliases some hosts use.
-    const experimental = server.server.getClientCapabilities()?.experimental;
-    if (!experimental)
+    // SEP-1724 negotiated extensions: canonical id under `extensions`.
+    const caps = server.server.getClientCapabilities();
+    if (!caps)
         return false;
-    return Boolean(experimental[MCP_APPS_UI_CAPABILITY] || experimental.ui || experimental.apps);
+    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));
 }
-function buildPreviewHtml(payload) {
-    // The payload (including the .nowline source) is injected as a JSON
-    // <script> block rather than interpolated into executable JS, so source
-    // text with quotes/backticks can't break out. Escaping `<` as \u003c keeps
-    // any embedded "</script>" from closing the block early; JSON.parse in the
-    // bundle decodes it back. The bundle injects its own stylesheet at runtime,
-    // so only the root-element sizing CSS is inlined here.
-    const data = JSON.stringify(payload).replace(/</g, '\\u003c');
-    return [
-        '<!doctype html>',
-        '<html lang="en">',
-        '<head>',
-        '<meta charset="utf-8" />',
-        '<meta name="viewport" content="width=device-width, initial-scale=1" />',
-        '<title>Nowline preview</title>',
-        '<style>html,body,#nl-preview-root{margin:0;padding:0;height:100%;width:100%;overflow:hidden;}</style>',
-        '</head>',
-        '<body>',
-        '<div id="nl-preview-root"></div>',
-        `<script id="nl-preview-data" type="application/json">${data}</script>`,
-        `<script>${UI_BUNDLE}</script>`,
-        '</body>',
-        '</html>',
-        '',
-    ].join('\n');
-}
-function previewResourceBlock(payload) {
+function leanPreviewBlock(payload) {
     return {
-        type: 'resource',
-        resource: {
-            uri: PREVIEW_UI_URI,
-            mimeType: PREVIEW_UI_MIME,
-            text: buildPreviewHtml(payload),
-        },
+        type: 'text',
+        text: JSON.stringify({
+            kind: 'nowline.preview',
+            source: payload.source,
+            theme: payload.theme,
+            now: payload.now,
+            width: payload.width,
+            locale: payload.locale,
+        }),
     };
 }
-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;
+// ---- Tool annotation presets (Anthropic Software Directory Policy § 5.E) ---
+function readOnlyTool(title) {
+    return {
+        title,
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    };
 }
-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 mutatingTool(title, opts) {
+    return {
+        title,
+        destructiveHint: opts.destructiveHint,
+        ...(opts.idempotentHint ? { idempotentHint: true } : {}),
+        openWorldHint: false,
+    };
 }
-// ---- Allowed-root enforcement -----------------------------------------------
+// ---- Server factory ---------------------------------------------------------
 function resolveAndGuard(filePath, allowedRoot) {
     const abs = path.resolve(allowedRoot, filePath);
     const guard = path.resolve(allowedRoot);
     if (!abs.startsWith(guard + path.sep) && abs !== guard) {
-        throw new Error(`Path ${filePath} is outside the allowed root ${allowedRoot}`);
+        throw new PathOutsideRootError(filePath, allowedRoot);
     }
     return abs;
 }
@@ -163,6 +116,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') };
@@ -172,16 +132,25 @@ async function sourceAndPath(args, allowedRoot) {
         const source = args.source ?? (await fs.readFile(abs, 'utf-8'));
         return { source, filePath: abs };
     }
-    throw new Error('At least one of `source` or `path` is required.');
+    throw new InputRequiredError('At least one of `source` or `path` is required.');
 }
 export function createMcpServer(opts = {}) {
     const allowedRoot = opts.allowedRoot ?? process.cwd();
     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 ----------------------------------------------------------
     server.registerResource('nowline-reference', 'nowline://reference', {
+        title: 'Roadmap Reference',
         description: 'Full DSL reference (nowline.5 man page): syntax, directives, and examples.',
         mimeType: 'text/plain',
     }, async () => ({
@@ -190,6 +159,7 @@ export function createMcpServer(opts = {}) {
         ],
     }));
     server.registerResource('nowline-examples', 'nowline://examples', {
+        title: 'Roadmap Examples',
         description: 'Canonical example .nowline files from the official examples/ directory.',
         mimeType: 'text/plain',
     }, async () => ({
@@ -200,6 +170,7 @@ export function createMcpServer(opts = {}) {
         })),
     }));
     server.registerResource('nowline-conversions', 'nowline://conversions', {
+        title: 'Conversion Guide',
         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 () => ({
@@ -211,11 +182,23 @@ export function createMcpServer(opts = {}) {
             },
         ],
     }));
+    registerAppResource(server, 'nowline-preview', PREVIEW_UI_URI, {
+        title: 'Roadmap Preview',
+        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
@@ -224,17 +207,41 @@ export function createMcpServer(opts = {}) {
                 .describe('Absolute or relative path to a .nowline file to validate.'),
         }),
         outputSchema: ValidateOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('Validate Roadmap'),
     }, 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 structured = { ok, diagnostics };
-        return {
-            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        try {
+            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(structured, null, 2) },
+                    ...(insights.length > 0
+                        ? [{ type: 'text', text: LAYOUT_INSIGHT_HINT }]
+                        : []),
+                ],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- read ---------------------------------------------------------------
     server.registerTool('read', {
@@ -245,53 +252,55 @@ export function createMcpServer(opts = {}) {
                 .describe('Absolute or relative path to the .nowline file to read.'),
         }),
         outputSchema: ReadOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('Read Roadmap'),
     }, 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(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        try {
+            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(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- 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 },
+        annotations: mutatingTool('Create Roadmap', {
+            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) {
+        try {
+            const abs = resolveAndGuard(args.path, allowedRoot);
+            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: false, path: abs, diagnostics }, null, 2),
-                    },
-                ],
-                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
             };
         }
-        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(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- 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()
@@ -299,29 +308,26 @@ export function createMcpServer(opts = {}) {
             source: z.string().describe('The new .nowline source text.'),
         }),
         outputSchema: UpdateOutputSchema,
-        annotations: { idempotentHint: true },
+        annotations: mutatingTool('Update Roadmap', {
+            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) {
+        try {
+            const abs = resolveAndGuard(args.path, allowedRoot);
+            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: false, path: abs, diagnostics }, null, 2),
-                    },
-                ],
-                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
             };
         }
-        await fs.writeFile(abs, args.source, 'utf-8');
-        const structured = { ok: true, path: abs };
-        return {
-            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- delete -------------------------------------------------------------
     server.registerTool('delete', {
@@ -332,15 +338,20 @@ export function createMcpServer(opts = {}) {
                 .describe('Absolute or relative path of the .nowline file to delete.'),
         }),
         outputSchema: DeleteOutputSchema,
-        annotations: { destructiveHint: true },
+        annotations: mutatingTool('Delete Roadmap', { 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(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        try {
+            const abs = resolveAndGuard(args.path, allowedRoot);
+            await fs.unlink(abs);
+            const structured = { path: abs };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- list ---------------------------------------------------------------
     server.registerTool('list', {
@@ -356,23 +367,36 @@ export function createMcpServer(opts = {}) {
                 .describe('Whether to scan subdirectories. Defaults to false.'),
         }),
         outputSchema: ListOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('List Roadmaps'),
     }, 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(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        try {
+            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(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return handleToolError(err, args.directory);
+        }
     });
     // ---- 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()
@@ -393,20 +417,43 @@ 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, also return an interactive in-chat HTML preview (MCP Apps UI). Auto-enabled when the client advertises MCP Apps UI support.'),
+                .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 },
+        annotations: readOnlyTool('Render Roadmap'),
+        _meta: {
+            ui: { resourceUri: PREVIEW_UI_URI },
+            'openai/outputTemplate': PREVIEW_UI_URI,
+        },
     }, async (args) => {
-        const { source, filePath } = await sourceAndPath(args, allowedRoot);
+        // Only the filesystem touchpoints (reading the input, writing the
+        // output) map to structured NL.MCP.* errors; a kernel render fault
+        // bubbles unchanged so it is never mislabeled as a path/IO failure.
+        let source;
+        let filePath;
+        try {
+            ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
+        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 = {
@@ -417,45 +464,91 @@ 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;
-        // Optional MCP Apps in-chat preview. Emitted alongside the normal
-        // content so non-UI hosts still get the SVG/PNG; the bundle renders
-        // the live SVG itself, so the preview is format-agnostic.
-        const wantPreview = args.preview === true || clientSupportsAppsUi(server);
-        const previewBlocks = wantPreview
-            ? [
-                previewResourceBlock({
-                    source,
-                    theme: args.theme,
-                    now: args.now,
-                    width: args.width,
-                    locale: 'en-US',
-                }),
-            ]
+        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 };
+            try {
+                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: [
+                        ...(appActive ? [leanPreviewBlock(previewPayload)] : []),
+                        { type: 'text', text: JSON.stringify(structured, null, 2) },
+                        ...insightHintBlocks,
+                        ...reviewBlocks,
+                    ],
+                    structuredContent: structured,
+                };
+            }
+            catch (err) {
+                return handleToolError(err, args.output);
+            }
+        }
+        if (appActive) {
+            const structured = {
+                format,
+                shareUrl,
+                ...insightsField,
+            };
             return {
                 content: [
-                    { type: 'text', text: JSON.stringify(structured, null, 2) },
-                    ...previewBlocks,
+                    leanPreviewBlock(previewPayload),
+                    ...insightHintBlocks,
+                    ...reviewBlocks,
                 ],
                 structuredContent: structured,
             };
         }
         if (format === 'png') {
-            const structured = { format, bytes: bytes.byteLength, shareUrl };
+            const structured = {
+                format,
+                bytes: bytes.byteLength,
+                shareUrl,
+                ...insightsField,
+            };
             return {
                 content: [
                     {
@@ -463,17 +556,19 @@ export function createMcpServer(opts = {}) {
                         data: Buffer.from(bytes).toString('base64'),
                         mimeType: 'image/png',
                     },
-                    ...previewBlocks,
+                    ...insightHintBlocks,
+                    ...reviewBlocks,
                 ],
                 structuredContent: structured,
             };
         }
         const svgText = new TextDecoder('utf-8').decode(bytes);
-        const structured = { format, shareUrl };
+        const structured = { format, shareUrl, ...insightsField };
         return {
             content: [
                 { type: 'text', text: svgText, mimeType: 'image/svg+xml' },
-                ...previewBlocks,
+                ...insightHintBlocks,
+                ...reviewBlocks,
             ],
             structuredContent: structured,
         };
@@ -484,14 +579,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.'),
@@ -511,9 +614,22 @@ export function createMcpServer(opts = {}) {
                 .describe('When true, include a shareUrl pointing to https://free.nowline.io/open.'),
         }),
         outputSchema: ExportOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('Export Roadmap'),
     }, async (args) => {
-        const { source, filePath } = await sourceAndPath(args, allowedRoot);
+        // Only the filesystem touchpoints (reading the input, writing the
+        // output) map to structured NL.MCP.* errors; a kernel export fault
+        // bubbles unchanged so it is never mislabeled as a path/IO failure.
+        let source;
+        let filePath;
+        try {
+            ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
+        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 = {
@@ -539,14 +655,19 @@ export function createMcpServer(opts = {}) {
         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(structured, null, 2) }],
-                structuredContent: structured,
-            };
+            try {
+                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(structured, null, 2) }],
+                    structuredContent: structured,
+                };
+            }
+            catch (err) {
+                return handleToolError(err, args.output);
+            }
         }
         if (isBinary) {
             const mimeMap = {
@@ -578,52 +699,62 @@ export function createMcpServer(opts = {}) {
         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('Path to the source file.'),
+            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 },
+        annotations: readOnlyTool('Convert Roadmap'),
     }, 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 };
+        try {
+            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 InputRequiredError('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,
             };
         }
-        // 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.');
+        catch (err) {
+            return handleToolError(err, args.path);
         }
-        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 },
+        annotations: readOnlyTool('View Roadmap Capabilities'),
     }, async () => {
         const structured = {
             themes: [...CAPABILITIES.themes],
@@ -642,7 +773,7 @@ export function createMcpServer(opts = {}) {
         description: 'List supported color themes: light, dark, grayscale.',
         inputSchema: z.object({}),
         outputSchema: ListItemsOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('List Themes'),
     }, async () => {
         const structured = { items: [...CAPABILITIES.themes] };
         return {
@@ -655,7 +786,7 @@ export function createMcpServer(opts = {}) {
         description: 'List built-in capacity-icon names usable in the `capacity-icon:` style property.',
         inputSchema: z.object({}),
         outputSchema: ListItemsOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('List Icons'),
     }, async () => {
         const structured = { items: [...CAPABILITIES.icons] };
         return {
@@ -668,7 +799,7 @@ export function createMcpServer(opts = {}) {
         description: 'List supported BCP-47 locale tags.',
         inputSchema: z.object({}),
         outputSchema: ListItemsOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('List Locales'),
     }, async () => {
         const structured = { items: [...CAPABILITIES.locales] };
         return {
@@ -681,7 +812,7 @@ export function createMcpServer(opts = {}) {
         description: 'List all supported export formats (svg, png, pdf, html, mermaid, xlsx, msproj, json).',
         inputSchema: z.object({}),
         outputSchema: ListItemsOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('List Export Formats'),
     }, async () => {
         const structured = { items: [...CAPABILITIES.formats] };
         return {
@@ -694,7 +825,7 @@ export function createMcpServer(opts = {}) {
         description: 'List built-in template names usable with `nowline --init --template`.',
         inputSchema: z.object({}),
         outputSchema: ListItemsOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('List Templates'),
     }, async () => {
         const structured = { items: [...CAPABILITIES.templates] };
         return {
@@ -702,9 +833,128 @@ export function createMcpServer(opts = {}) {
             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: readOnlyTool('View Roadmap Reference'),
+    }, 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: readOnlyTool('View Roadmap Examples'),
+    }, 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: `# 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: readOnlyTool('View Roadmap Schema'),
+    }, 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 {