@nowline/mcp 0.8.0 → 0.8.1

package/dist/server.js

@@ -16,7 +16,7 @@ import { buildShareLink } from '@nowline/share-link';
 import { z } from 'zod';
 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 { 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';
@@ -59,12 +59,29 @@ function leanPreviewBlock(payload) {
         }),
     };
 }
+// ---- Tool annotation presets (Anthropic Software Directory Policy § 5.E) ---
+function readOnlyTool(title) {
+    return {
+        title,
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    };
+}
+function mutatingTool(title, opts) {
+    return {
+        title,
+        destructiveHint: opts.destructiveHint,
+        ...(opts.idempotentHint ? { idempotentHint: true } : {}),
+        openWorldHint: false,
+    };
+}
 // ---- 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;
 }
@@ -115,7 +132,7 @@ 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();
@@ -133,6 +150,7 @@ export function createMcpServer(opts = {}) {
     });
     // ---- 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 () => ({
@@ -141,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 () => ({
@@ -151,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 () => ({
@@ -163,6 +183,7 @@ 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: [
@@ -186,32 +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 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,
-        };
+        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', {
@@ -222,15 +252,20 @@ 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', {
@@ -241,19 +276,27 @@ export function createMcpServer(opts = {}) {
         }),
         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 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(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        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(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- update -------------------------------------------------------------
     server.registerTool('update', {
@@ -265,18 +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 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(structured, null, 2) }],
-            structuredContent: structured,
-        };
+        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(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
+        catch (err) {
+            return handleToolError(err, args.path);
+        }
     });
     // ---- delete -------------------------------------------------------------
     server.registerTool('delete', {
@@ -287,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', {
@@ -311,16 +367,23 @@ 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 -------------------------------------------------------------
     registerAppTool(server, 'render', {
@@ -371,13 +434,23 @@ export function createMcpServer(opts = {}) {
                 .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;
@@ -429,43 +502,53 @@ export function createMcpServer(opts = {}) {
         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);
+            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,
-                path: outAbs,
-                bytes: bytes.byteLength,
                 shareUrl,
                 ...insightsField,
             };
             return {
                 content: [
-                    ...(appActive ? [leanPreviewBlock(previewPayload)] : []),
-                    { type: 'text', text: JSON.stringify(structured, null, 2) },
+                    leanPreviewBlock(previewPayload),
                     ...insightHintBlocks,
                     ...reviewBlocks,
                 ],
                 structuredContent: structured,
             };
         }
-        if (appActive) {
+        if (format === 'png') {
             const structured = {
                 format,
+                bytes: bytes.byteLength,
                 shareUrl,
                 ...insightsField,
             };
-            return {
-                content: [
-                    leanPreviewBlock(previewPayload),
-                    ...insightHintBlocks,
-                    ...reviewBlocks,
-                ],
-                structuredContent: structured,
-            };
-        }
-        if (format === 'png') {
-            const structured = { format, bytes: bytes.byteLength, shareUrl, ...insightsField };
             return {
                 content: [
                     {
@@ -531,9 +614,19 @@ 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;
@@ -562,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 = {
@@ -612,46 +710,51 @@ export function createMcpServer(opts = {}) {
                 .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],
@@ -670,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 {
@@ -683,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 {
@@ -696,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 {
@@ -709,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 {
@@ -722,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 {
@@ -740,7 +843,7 @@ export function createMcpServer(opts = {}) {
                 .describe('Reference format. Defaults to condensed.'),
         }),
         outputSchema: ReferenceOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('View Roadmap Reference'),
     }, async (args) => {
         const format = args.format ?? 'condensed';
         const text = format === 'full' ? REFERENCE_MAN_PAGE : REFERENCE_CHEATSHEET;
@@ -759,7 +862,7 @@ export function createMcpServer(opts = {}) {
                 .describe('Example name. Omit for the catalog plus minimal inline.'),
         }),
         outputSchema: ExamplesOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('View Roadmap Examples'),
     }, async (args) => {
         const exampleNames = EXAMPLES.map((e) => exampleShortName(e.name));
         if (args.name) {
@@ -804,7 +907,7 @@ export function createMcpServer(opts = {}) {
         description: 'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties).',
         inputSchema: z.object({}),
         outputSchema: SchemaOutputSchema,
-        annotations: { readOnlyHint: true, idempotentHint: true },
+        annotations: readOnlyTool('View Roadmap Schema'),
     }, async () => {
         const structured = {
             directiveKeys: [...SCHEMA_VOCABULARY.directiveKeys],