@nowline/mcp 0.8.5 → 0.9.0

package/src/http.ts

@@ -0,0 +1,28 @@
+// Streamable HTTP request handler shared by `npx @nowline/mcp --port` and
+// `nowline --mcp --port`.
+//
+// The HTTP transport is stateless (no session IDs), so every request gets its
+// own McpServer and transport. Sharing one pair across requests could deliver
+// one HTTP client's messages to another, and since
+// @modelcontextprotocol/server 2.3.0 the SDK throws on reuse.
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+import type { McpServer } from '@modelcontextprotocol/server';
+
+export function createMcpHttpHandler(
+    createServer: () => McpServer,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+    return async (req, res) => {
+        const server = createServer();
+        const transport = new NodeStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    };
+}

package/src/index.ts

@@ -15,8 +15,8 @@ import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { createMcpHttpHandler } from './http.js';
 import { expandRootPath } from './root-path.js';
 import { createMcpServer } from './server.js';
 
@@ -96,22 +96,15 @@ if (help) {
 // (optional field left unset) collapses to undefined → cwd fallback, inline.
 const expandedRoot = expandRootPath(root);
 
-const server = createMcpServer({
+const serverOptions = {
     allowedRoot: expandedRoot,
     rootConfigured: expandedRoot !== undefined,
     version: PKG_VERSION,
-});
+};
 
 if (port !== undefined) {
-    // Streamable HTTP transport — stateless (no session management).
-    const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: undefined,
-    });
-    await server.connect(transport);
-
-    const httpServer = createServer(async (req, res) => {
-        await transport.handleRequest(req, res);
-    });
+    // Streamable HTTP transport — stateless, one server per request.
+    const httpServer = createServer(createMcpHttpHandler(() => createMcpServer(serverOptions)));
 
     httpServer.listen(port, '127.0.0.1', () => {
         process.stderr.write(
@@ -127,5 +120,5 @@ if (port !== undefined) {
 } else {
     // Default: stdio transport.
     const transport = new StdioServerTransport();
-    await server.connect(transport);
+    await createMcpServer(serverOptions).connect(transport);
 }

package/src/options.ts

@@ -0,0 +1,79 @@
+// How an MCP tool call's arguments become render options: the shared schema
+// from `@nowline/config`, over one `argument` layer (specs/surface-options.md
+// §3.2). MCP keeps its own wording for a bad value.
+
+import {
+    type OptionError,
+    type OptionLayer,
+    resolveSurfaceOptions,
+    type SurfaceOptions,
+} from '@nowline/config';
+import { type NormalizedZone, normalizeZone, type ThemeName, TimezoneError } from '@nowline/layout';
+import { InputRequiredError } from './diagnostics.js';
+
+/** The option arguments a tool takes; each tool offers the subset it needs. */
+export interface McpOptionArguments {
+    theme?: string;
+    width?: number;
+    now?: string;
+    /** Zone for the default now-line date; accepts what the CLI's `--timezone` does. */
+    timezone?: string;
+    nonWorking?: string;
+    pageSize?: string;
+}
+
+export interface McpResolvedOptions {
+    options: SurfaceOptions;
+    /** The theme argument, when the caller passed one; the preview picks its own otherwise. */
+    theme?: ThemeName;
+}
+
+/**
+ * Resolve a tool's option arguments. Throws `InputRequiredError` (the tool's
+ * input-error result) for the first bad value. An omitted `now` draws the
+ * now-line at today's civil date in the `timezone` argument's zone, or the
+ * server's local zone without one, as on every other surface. `clock` is a
+ * test seam.
+ */
+export function resolveMcpOptions(
+    args: McpOptionArguments,
+    clock?: () => Date,
+): McpResolvedOptions {
+    const zone = readZone(args.timezone);
+    const layer: OptionLayer = {
+        source: (key) => ({ kind: 'argument', name: key }),
+        values: {
+            theme: args.theme,
+            width: args.width,
+            now: args.now,
+            nonWorking: args.nonWorking,
+            pageSize: args.pageSize,
+        },
+    };
+    const { options, errors } = resolveSurfaceOptions([layer], { theme: 'light' }, { zone, clock });
+    const [first] = errors;
+    if (first) throw new InputRequiredError(describeOptionError(first));
+    return { options, theme: args.theme === undefined ? undefined : options.theme };
+}
+
+// `--timezone`'s forms, through the same parser; the parser's text names the CLI.
+function readZone(raw: string | undefined): NormalizedZone | undefined {
+    if (raw === undefined) return undefined;
+    try {
+        return normalizeZone(raw);
+    } catch (err) {
+        if (!(err instanceof TimezoneError)) throw err;
+        throw new InputRequiredError(`Invalid timezone: ${err.message.replace(/^nowline: /, '')}`);
+    }
+}
+
+function describeOptionError(error: OptionError): string {
+    const raw = String(error.raw);
+    if (error.key === 'theme' && error.expected) {
+        return `Unknown theme "${raw}". Expected one of: ${error.expected.join(', ')}.`;
+    }
+    if (error.expected) {
+        return `Invalid ${error.key} "${raw}". Expected one of: ${error.expected.join(', ')}.`;
+    }
+    return `Invalid ${error.key} "${raw}": ${error.detail}`;
+}

package/src/prompts.ts

@@ -1,7 +1,7 @@
 // MCP prompt registrations for @nowline/mcp.
 // Wired into the server via registerPrompts(server).
 
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
 export function registerPrompts(server: McpServer): void {
@@ -13,13 +13,13 @@ export function registerPrompts(server: McpServer): void {
             title: 'Create Roadmap from Description',
             description:
                 'Generate a new .nowline roadmap from a plain-English description. Composes the DSL reference and example files so the LLM has full context.',
-            argsSchema: {
+            argsSchema: z.object({
                 description: z
                     .string()
                     .describe(
                         'Plain-English description of the roadmap you want to create (teams, timeline, key milestones, etc.).',
                     ),
-            },
+            }),
         },
         ({ description }) => ({
             messages: [
@@ -64,7 +64,7 @@ export function registerPrompts(server: McpServer): void {
             title: 'Fix Roadmap Diagnostics',
             description:
                 'Fix validation errors in a .nowline file. Describe the validate→fix→re-validate loop keyed on NL.E#### diagnostic codes.',
-            argsSchema: {
+            argsSchema: z.object({
                 source: z
                     .string()
                     .describe('The .nowline source text that contains validation errors.'),
@@ -74,7 +74,7 @@ export function registerPrompts(server: McpServer): void {
                     .describe(
                         'JSON array of diagnostic objects from the validate tool. Omit to let the LLM call validate itself.',
                     ),
-            },
+            }),
         },
         ({ source, diagnostics }) => {
             const diagSection = diagnostics
@@ -113,7 +113,7 @@ export function registerPrompts(server: McpServer): void {
             title: 'Convert to Nowline',
             description:
                 'Convert a gantt/timeline from another format (Mermaid gantt, MS Project, Excel, Google Sheets, CSV) into Nowline DSL. Uses the conversion guide resource for format-specific rules.',
-            argsSchema: {
+            argsSchema: z.object({
                 source: z
                     .string()
                     .describe('The source content to convert (paste the raw text/CSV/XML here).'),
@@ -130,7 +130,7 @@ export function registerPrompts(server: McpServer): void {
                     .describe(
                         'Source format hint. Use "auto" (default) to let the LLM detect the format.',
                     ),
-            },
+            }),
         },
         ({ source, from }) => {
             const formatHint =

package/src/reference-cheatsheet.ts

@@ -19,13 +19,13 @@ swimlane <id> "<title>"
   item <id> "<title>" duration:3w
 \`\`\`
 
-Entity types: \`swimlane\`, \`group\`, \`parallel\`, \`item\`, \`milestone\`, \`anchor\`.
+Entity types: \`swimlane\`, \`group\`, \`parallel\`, \`item\`, \`wave\`, \`milestone\`, \`anchor\`.
 
 Items need \`duration:\` or \`size:\`. Use 2-space indentation under parents.
 
 ## Item properties
 
-\`duration:\` (or \`size:\`), \`status:\`, \`remaining:\`, \`owner:\`, \`after:\`, \`before:\`, \`labels:\`, \`link:\`, \`style:\`.
+\`duration:\` (or \`size:\`), \`status:\`, \`remaining:\`, \`owner:\`, \`wave:\`, \`after:\`, \`before:\`, \`labels:\`, \`link:\`, \`style:\`.
 
 There is NO \`progress:\` or \`color:\` key. Show completion with \`status:\` + \`remaining:\`; set visuals with a \`style:\` reference (see full reference).
 
@@ -39,6 +39,31 @@ item api "API redesign" duration:4w status:in-progress remaining:40%
 
 \`remaining:\` is the work *left*, written as a percent (\`40%\`) or an effort literal (\`1w\`). So an item that is 60% complete is \`remaining:40%\`. Omit \`remaining:\` for a fully open or fully done bar.
 
+## Waves
+
+\`\`\`
+wave build "Build"
+wave launch "Launch"
+swimlane api "API"
+  item core "Core" duration:3w wave:build
+  group wave:launch
+    item docs "Docs" duration:1w
+milestone ship "Ship" after:launch
+\`\`\`
+
+A wave is a strict barrier across every swimlane: no item in the next wave starts until every item in this one ends. Items without \`wave:\` are background work, never held back, drawn hatched.
+
+## Working calendar
+
+\`\`\`
+config
+
+non-working thanksgiving "Thanksgiving" start:2026-11-26 end:2026-11-27
+working crunch "Crunch Saturday" date:2026-01-10
+\`\`\`
+
+\`non-working\` takes \`date:\`, \`start:\` with \`end:\`, or \`every:\` (weekday names, \`every:[sat, sun]\`); \`working\` gives days back. Durations count working days only. \`default roadmap non-working:hide\` (the default) collapses closed days to a seam; \`show\` draws them as bands. A dated declaration with a title is labelled in the marker row: a closure as \`Thanksgiving · 2d\` (working days removed), a \`working\` one as \`Crunch Saturday · +1d\` (days added, no cut line). Titles on \`every:\` recurrences are not drawn.
+
 ## Config / includes (before roadmap)
 
 \`config\` blocks, \`include "path.nowline"\` — see full reference for ordering rules.

package/src/schema-vocab.ts

@@ -31,9 +31,17 @@ export const SCHEMA_VOCABULARY = {
         'label',
         'size',
         'status',
+        'wave',
         'milestone',
         'footnote',
     ],
+    // Keywords of the `config` section. `non-working` and `working` declare
+    // calendar days (specs/working-calendar.md); the others configure the
+    // chart's scale, calendar, styles, symbols and per-entity defaults.
+    configKeywords: ['scale', 'calendar', 'style', 'symbol', 'default', 'non-working', 'working'],
+    // Properties of a `non-working` / `working` declaration: one day (`date`),
+    // a range (`start`, `end`), or a recurring weekday (`every`).
+    calendarDeclarationKeys: ['date', 'start', 'end', 'every'],
     // Properties valid on `item` declarations: item-specific keys plus the
     // universal properties (`labels`, `link`, `style`, `description`).
     // Visual treatment is a single `style:` reference — raw color/style
@@ -41,6 +49,7 @@ export const SCHEMA_VOCABULARY = {
     itemPropertyKeys: [
         'status',
         'owner',
+        'wave',
         'after',
         'before',
         'size',

package/src/schemas.ts

@@ -105,4 +105,6 @@ export const SchemaOutputSchema = z.object({
     directiveKeys: z.array(z.string()),
     entityTypes: z.array(z.string()),
     itemPropertyKeys: z.array(z.string()),
+    configKeywords: z.array(z.string()),
+    calendarDeclarationKeys: z.array(z.string()),
 });