@nowline/mcp 0.8.5 → 0.9.0

package/src/server.ts

@@ -14,15 +14,20 @@ import {
     registerAppResource,
     registerAppTool,
 } from '@modelcontextprotocol/ext-apps/server';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
+import type { SurfaceOptions } from '@nowline/config';
 import { type NowlineFile, parseNowlineJson, printNowlineFile } from '@nowline/core';
 import {
+    acceptStagedRoadmap,
     type ExportFormat,
     exportDocument,
+    exportStaged,
     type HostEnv,
+    IncludeResolveError,
     type RenderInputs,
 } from '@nowline/export';
 import { resolveFonts } from '@nowline/export-core';
+import { NON_WORKING_DISPLAYS, THEME_NAMES } from '@nowline/layout';
 import { buildShareLink } from '@nowline/share-link';
 import { z } from 'zod';
 import { NOWLINE_MCP_ICONS } from './branding.js';
@@ -30,14 +35,20 @@ import { CAPABILITIES } from './capabilities.js';
 import {
     buildDocument,
     collectMcpDiagnostics,
-    collectMcpLayoutInsights,
     DEFAULT_RENDER_WIDTH,
     diagnosticsErrorBlock,
+    diagnosticsErrorResponse,
     handleToolError,
     InputRequiredError,
+    includeDiagnosticsResponse,
     LAYOUT_INSIGHT_HINT,
+    layoutInsightsFromStage,
+    type McpInsight,
     PathOutsideRootError,
     REVIEW_MAX_WIDTH,
+    routedResolveDiagnosticsToMcp,
+    stageMcpRoadmap,
+    stageRoutedDiagnostics,
     toolDescriptionWithSyntax,
 } from './diagnostics.js';
 import {
@@ -47,6 +58,7 @@ import {
     REFERENCE_MAN_PAGE,
 } from './generated/resources.js';
 import { PREVIEW_HTML } from './generated/ui-bundle.js';
+import { type McpResolvedOptions, resolveMcpOptions } from './options.js';
 import { registerPrompts } from './prompts.js';
 import { REFERENCE_CHEATSHEET } from './reference-cheatsheet.js';
 import { SCHEMA_VOCABULARY } from './schema-vocab.js';
@@ -107,9 +119,24 @@ interface PreviewPayload {
     theme?: string;
     now?: string;
     width?: number;
+    nonWorking?: 'hide' | 'show';
     locale?: string;
 }
 
+/**
+ * The preview payload's now-line. An explicit `now` passes through. With only a
+ * `timezone`, the payload carries the date that zone resolved to: the preview
+ * draws an omitted `now` at the viewer's own date and cannot read the zone.
+ */
+function previewNow(
+    args: { now?: string; timezone?: string },
+    today: Date | undefined,
+): string | undefined {
+    if (args.now !== undefined) return args.now;
+    if (args.timezone !== undefined && today) return today.toISOString().slice(0, 10);
+    return undefined;
+}
+
 function leanPreviewBlock(payload: PreviewPayload) {
     return {
         type: 'text' as const,
@@ -119,6 +146,7 @@ function leanPreviewBlock(payload: PreviewPayload) {
             theme: payload.theme,
             now: payload.now,
             width: payload.width,
+            nonWorking: payload.nonWorking,
             locale: payload.locale,
         }),
     };
@@ -185,11 +213,6 @@ function createNodeHostEnv(sourcePath: string): HostEnv {
 
 // ---- Helpers ----------------------------------------------------------------
 
-function todayUtc(): Date {
-    const now = new 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;
 }
@@ -335,6 +358,43 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
     registerPrompts(server);
 
+    const nonWorkingSchema = z
+        .enum(NON_WORKING_DISPLAYS)
+        .optional()
+        .describe(
+            "How a business calendar's non-working days appear: hide collapses them, " +
+                "show draws them as shaded bands. Overrides the file's `default roadmap non-working:` key; " +
+                'omit to let the key apply (then hide). The schedule exports (mermaid, msproj, xlsx) are the same either way.',
+        );
+
+    // A string, not an enum, so `Greyscale` and the `greyscale` alias reach
+    // `resolveMcpOptions`, which rejects an unknown name with the theme list.
+    const themeSchema = z
+        .string()
+        .optional()
+        .describe(
+            `Color theme: ${THEME_NAMES.join(', ')} ("greyscale" is accepted). Defaults to light.`,
+        );
+
+    const nowSchema = z
+        .string()
+        .regex(/^(\d{4}-\d{2}-\d{2}|-)$/, 'Expected YYYY-MM-DD or "-".')
+        .optional()
+        .describe(
+            "Now-line date as YYYY-MM-DD. Omit to draw it at today's date in `timezone` " +
+                "(the server's local zone when `timezone` is omitted too); " +
+                'pass "-" to suppress the now-line (same as the CLI\'s `--now -`).',
+        );
+
+    const timezoneSchema = z
+        .string()
+        .optional()
+        .describe(
+            "Timezone that decides today's date when `now` is omitted (ignored when `now` is a date): " +
+                '"local" (the default), "UTC", an ISO 8601 offset ("+05:30", "-07:00", "Z"), ' +
+                'or an IANA name ("America/Los_Angeles"). The same forms as the CLI\'s `--timezone`.',
+        );
+
     // ---- validate -----------------------------------------------------------
 
     server.registerTool(
@@ -349,26 +409,39 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .string()
                     .optional()
                     .describe('Absolute or relative path to a .nowline file to validate.'),
+                now: nowSchema,
+                timezone: timezoneSchema,
             }),
             outputSchema: ValidateOutputSchema,
             annotations: readOnlyTool('Validate Roadmap'),
         },
         async (args) => {
             try {
+                const { options } = resolveMcpOptions(args);
                 const { source, filePath } = await sourceAndPath(args, allowedRoot);
                 const doc = await buildDocument(source);
                 const diagnostics = collectMcpDiagnostics(doc, filePath);
+                // One stage: the routed (wave-rule) include diagnostics join
+                // the validator's, with the file and line they point into
+                // (specs/waves.md §6.1), and the insights come from the same
+                // layout, logo included.
+                let insights: McpInsight[] = [];
+                if (diagnostics.every((d) => d.severity !== 'error')) {
+                    const stage = await stageMcpRoadmap(
+                        doc,
+                        source,
+                        {
+                            sourcePath: filePath,
+                            today: options.today,
+                            locale: 'en-US',
+                            theme: 'light',
+                        },
+                        createNodeHostEnv(filePath),
+                    );
+                    diagnostics.push(...stageRoutedDiagnostics(stage));
+                    if (stage.kind === 'staged') insights = layoutInsightsFromStage(stage);
+                }
                 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,
@@ -585,15 +658,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .enum(['svg', 'png'])
                     .optional()
                     .describe('Output format. Defaults to svg.'),
-                theme: z
-                    .enum(['light', 'dark', 'grayscale'])
-                    .optional()
-                    .describe('Color theme. Defaults to light.'),
-                now: z
-                    .string()
+                theme: themeSchema,
+                now: nowSchema,
+                timezone: timezoneSchema,
+                width: z
+                    .number()
                     .optional()
-                    .describe('Now-line date as YYYY-MM-DD (UTC). Omit to suppress.'),
-                width: z.number().optional().describe('Canvas width in px.'),
+                    .describe(
+                        'Maximum canvas width in px, an integer of at least 320. Unset fits the content; a wider roadmap shrinks its timeline to fit.',
+                    ),
+                nonWorking: nonWorkingSchema,
                 scale: z
                     .number()
                     .optional()
@@ -616,7 +690,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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.',
+                        'When true, force the in-chat MCP Apps preview; when false, return inline output even on an MCP Apps host. ' +
+                            'Omit to follow the host: on MCP Apps hosts the preview auto-renders via _meta.ui.',
                     ),
             }),
             outputSchema: RenderOutputSchema,
@@ -630,6 +705,13 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             // 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 resolved: McpResolvedOptions;
+            try {
+                resolved = resolveMcpOptions(args);
+            } catch (err) {
+                return handleToolError(err);
+            }
+            const { theme, options } = resolved;
             let source: string;
             let filePath: string;
             try {
@@ -642,17 +724,19 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             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 today = options.today;
             const inputs: RenderInputs = {
                 sourcePath: filePath,
                 today,
                 locale: 'en-US',
-                theme: args.theme ?? 'light',
-                width: args.width,
+                theme: options.theme,
+                width: options.width,
+                nonWorking: options.nonWorking,
                 pngScale: args.scale,
             };
             const host = createNodeHostEnv(filePath);
-            const appActive = args.preview === true || clientSupportsAppsUi(server);
+            // Explicit true/false wins; undefined follows the host's capabilities.
+            const appActive = args.preview ?? 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;
@@ -660,32 +744,49 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 const result = await resolveFonts({ headless: true });
                 inputs.fonts = { sans: result.sans, mono: result.mono };
             }
-            const bytes = needsRender
-                ? await exportDocument(source, format, inputs, host)
-                : new Uint8Array(0);
-
-            const insights = await collectMcpLayoutInsights({
-                source,
-                filePath,
-                today,
-                theme: args.theme ?? 'light',
-                width: args.width,
-                locale: 'en-US',
-                readFile: host.readSource,
-                doc: blocked.doc,
-            });
+            // One stage serves the render, the insights and the include check.
+            const stage = await stageMcpRoadmap(blocked.doc, source, inputs, host);
+            if (stage.kind === 'invalid') {
+                return diagnosticsErrorResponse(
+                    filePath,
+                    collectMcpDiagnostics(blocked.doc, filePath),
+                );
+            }
+            // Wave-rule include errors are reported as diagnostics. An uncoded
+            // include error throws from a render, as the kernel's does; the
+            // preview path, which draws nothing here, keeps the preview it
+            // returned before waves existed (specs/waves.md §6.1).
+            const routed = stageRoutedDiagnostics(stage);
+            if (routed.some((d) => d.severity === 'error')) {
+                return includeDiagnosticsResponse(blocked.doc, filePath, routed);
+            }
+            if (stage.kind === 'include-error' && needsRender) acceptStagedRoadmap(stage, inputs);
+            const staged = stage.kind === 'staged' ? stage : undefined;
+            const insights = staged ? layoutInsightsFromStage(staged) : [];
+            const bytes =
+                needsRender && staged
+                    ? await exportStaged(staged, format, inputs, host)
+                    : new Uint8Array(0);
 
             const previewPayload: PreviewPayload = {
                 source,
-                theme: args.theme,
-                now: args.now,
-                width: args.width,
+                theme,
+                now: previewNow(args, options.today),
+                width: options.width,
+                nonWorking: options.nonWorking,
                 locale: 'en-US',
             };
 
             const reviewBlocks =
                 args.review === true
-                    ? await buildReviewContentBlocks(source, format, bytes, inputs, host)
+                    ? await buildReviewContentBlocks(
+                          blocked.doc,
+                          source,
+                          format,
+                          bytes,
+                          inputs,
+                          host,
+                      )
                     : [];
 
             const insightHintBlocks =
@@ -800,10 +901,17 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                             'Never pass a virtual or sandbox path such as /home/claude/…, /mnt/user-data/…, or any path ' +
                             'outside the configured output folder — 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(),
+                now: nowSchema,
+                timezone: timezoneSchema,
+                theme: themeSchema,
+                nonWorking: nonWorkingSchema,
                 scale: z.number().optional().describe('PNG scale factor.'),
-                pageSize: z.string().optional().describe('PDF page size.'),
+                pageSize: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'PDF page size: a preset name, "content", or <W>x<H><unit> (e.g. 8.5x11in). Validated for every format.',
+                    ),
                 orientation: z
                     .enum(['portrait', 'landscape', 'auto'])
                     .optional()
@@ -832,6 +940,12 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             // 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 options: SurfaceOptions;
+            try {
+                ({ options } = resolveMcpOptions(args));
+            } catch (err) {
+                return handleToolError(err);
+            }
             let source: string;
             let filePath: string;
             try {
@@ -844,14 +958,14 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             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 = {
                 sourcePath: filePath,
-                today,
+                today: options.today,
                 locale: 'en-US',
-                theme: args.theme ?? 'light',
+                theme: options.theme,
+                nonWorking: options.nonWorking,
                 pngScale: args.scale,
-                pageSize: args.pageSize,
+                pageSize: options.pageSize,
                 orientation: args.orientation,
                 marginPt: args.marginPt,
                 msprojStart: args.msprojStart,
@@ -861,7 +975,21 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 inputs.fonts = { sans: result.sans, mono: result.mono };
             }
             const host = createNodeHostEnv(filePath);
-            const bytes = await exportDocument(source, format, inputs, host);
+            let bytes: Uint8Array;
+            try {
+                const staged = acceptStagedRoadmap(
+                    await stageMcpRoadmap(blocked.doc, source, inputs, host),
+                    inputs,
+                );
+                bytes = await exportStaged(staged, format, inputs, host);
+            } catch (err) {
+                if (!(err instanceof IncludeResolveError)) throw err;
+                return includeDiagnosticsResponse(
+                    blocked.doc,
+                    filePath,
+                    routedResolveDiagnosticsToMcp(err.diagnostics),
+                );
+            }
 
             const BINARY_FORMATS = new Set<ExportFormat>(['png', 'pdf', 'xlsx']);
             const isBinary = BINARY_FORMATS.has(format);
@@ -1049,12 +1177,15 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 if (args.to === 'json') {
                     const { source, filePath } = await sourceAndPath(args, allowedRoot);
                     const host = createNodeHostEnv(filePath);
+                    // The JSON AST does not depend on today's date, so convert
+                    // takes no `now`; the kernel still wants a concrete one.
+                    const { options } = resolveMcpOptions({});
                     const jsonBytes = await exportDocument(
                         source,
                         'json',
                         {
                             sourcePath: filePath,
-                            today: todayUtc(),
+                            today: options.today,
                             locale: 'en-US',
                             theme: 'light',
                         },
@@ -1121,7 +1252,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     server.registerTool(
         'list-themes',
         {
-            description: 'List supported color themes: light, dark, grayscale.',
+            description: `List supported color themes: ${THEME_NAMES.join(', ')}.`,
             inputSchema: z.object({}),
             outputSchema: ListItemsOutputSchema,
             annotations: readOnlyTool('List Themes'),
@@ -1300,7 +1431,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         'schema',
         {
             description:
-                'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties).',
+                'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties, config keywords, calendar declaration keys).',
             inputSchema: z.object({}),
             outputSchema: SchemaOutputSchema,
             annotations: readOnlyTool('View Roadmap Schema'),
@@ -1310,6 +1441,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 directiveKeys: [...SCHEMA_VOCABULARY.directiveKeys],
                 entityTypes: [...SCHEMA_VOCABULARY.entityTypes],
                 itemPropertyKeys: [...SCHEMA_VOCABULARY.itemPropertyKeys],
+                configKeywords: [...SCHEMA_VOCABULARY.configKeywords],
+                calendarDeclarationKeys: [...SCHEMA_VOCABULARY.calendarDeclarationKeys],
             };
             return {
                 content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
@@ -1383,6 +1516,7 @@ function buildExportInlineContentBlocks(
 }
 
 async function buildReviewContentBlocks(
+    doc: Awaited<ReturnType<typeof buildDocument>>,
     source: string,
     format: ExportFormat,
     artifactBytes: Uint8Array,
@@ -1413,7 +1547,13 @@ async function buildReviewContentBlocks(
             const fonts = await resolveFonts({ headless: true });
             reviewInputs.fonts = { sans: fonts.sans, mono: fonts.mono };
         }
-        inspectionBytes = await exportDocument(source, 'png', reviewInputs, host);
+        // A narrower review width is a different layout, so it stages again
+        // (the parsed document is reused).
+        const reviewStage = acceptStagedRoadmap(
+            await stageMcpRoadmap(doc, source, reviewInputs, host),
+            reviewInputs,
+        );
+        inspectionBytes = await exportStaged(reviewStage, 'png', reviewInputs, host);
     }
 
     if (format !== 'png' || inspectionBytes.byteLength !== artifactBytes.byteLength) {

package/src/ui/entry.ts

@@ -25,12 +25,15 @@
 declare const __MCP_VERSION__: string;
 
 import { App } from '@modelcontextprotocol/ext-apps';
+import { normalizeThemeName } from '@nowline/layout';
 import { type LivePreviewHandle, mountLivePreview } from '@nowline/preview';
 import type { NowOverride, ThemeOverride } from '@nowline/preview-shell';
 import {
     type PreviewPayload,
     parsePreviewFromArguments,
     parsePreviewFromContent,
+    toNonWorkingOverride,
+    toNowOverride,
 } from './payload.js';
 
 function readPayload(): PreviewPayload | undefined {
@@ -45,16 +48,7 @@ function readPayload(): PreviewPayload | undefined {
 
 /** Coerce a raw theme token from the payload to the shell's ThemeOverride. */
 function toThemeOverride(theme: string | undefined): ThemeOverride {
-    switch (theme) {
-        case 'light':
-        case 'dark':
-        case 'grayscale':
-        case 'greyscale':
-        case 'auto':
-            return theme;
-        default:
-            return 'auto';
-    }
+    return (theme !== undefined ? normalizeThemeName(theme) : undefined) ?? 'auto';
 }
 
 let mounted = false;
@@ -87,7 +81,8 @@ function mountFromPayload(payload: PreviewPayload, app: App): void {
         mode: hostTheme(app) ?? 'system',
         initialView: {
             theme: toThemeOverride(payload.theme),
-            now: (payload.now ?? 'today') as NowOverride,
+            now: toNowOverride(payload.now) as NowOverride,
+            nonWorking: toNonWorkingOverride(payload.nonWorking),
             showLinks: payload.showLinks !== false,
         },
         renderOptions: {

package/src/ui/payload.ts

@@ -13,6 +13,8 @@ export interface PreviewPayload {
     theme?: string;
     now?: string;
     width?: number;
+    /** The render-time non-working display; absent lets the file's own key apply. */
+    nonWorking?: 'hide' | 'show';
     locale?: string;
     showLinks?: boolean;
     showMinimap?: boolean;
@@ -53,11 +55,35 @@ export function parsePreviewFromArguments(
     args: Record<string, unknown> | undefined,
 ): PreviewPayload | undefined {
     if (!args || typeof args.source !== 'string') return undefined;
+    // A `timezone` without a `now` names a date only the server can resolve;
+    // wait for the result payload, which carries it.
+    if (typeof args.timezone === 'string' && typeof args.now !== 'string') return undefined;
     return {
         source: args.source,
         theme: typeof args.theme === 'string' ? args.theme : undefined,
         now: typeof args.now === 'string' ? args.now : undefined,
         width: typeof args.width === 'number' ? args.width : undefined,
+        nonWorking:
+            args.nonWorking === 'hide' || args.nonWorking === 'show' ? args.nonWorking : undefined,
         locale: 'en-US',
     };
 }
+
+/**
+ * The shell's non-working dropdown value for a payload. A payload with no
+ * `nonWorking` maps to `'file'` (no override), so the file's own key applies;
+ * anything other than `hide` or `show` is treated as unset.
+ */
+export function toNonWorkingOverride(nonWorking: unknown): 'file' | 'hide' | 'show' {
+    return nonWorking === 'hide' || nonWorking === 'show' ? nonWorking : 'file';
+}
+
+/**
+ * The shell's now-line value for a payload's `now`. Omitted means today; `-`
+ * (the CLI's `--now -` sentinel, also accepted by the `render` tool) hides the
+ * now-line; a date passes through.
+ */
+export function toNowOverride(now: unknown): string {
+    if (now === '-') return 'hide';
+    return typeof now === 'string' && now.length > 0 ? now : 'today';
+}