@nowline/mcp 0.8.2 → 0.8.3

package/src/index.ts

@@ -17,6 +17,7 @@ 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 { expandRootPath } from './root-path.js';
 import { createMcpServer } from './server.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -90,7 +91,16 @@ if (help) {
     process.exit(0);
 }
 
-const server = createMcpServer({ allowedRoot: root, version: PKG_VERSION });
+// Expand mcpb tokens (${HOME}/~/env vars) so a literal default from the
+// .mcpb directory picker resolves to a real path. An empty/blank value
+// (optional field left unset) collapses to undefined → cwd fallback, inline.
+const expandedRoot = expandRootPath(root);
+
+const server = createMcpServer({
+    allowedRoot: expandedRoot,
+    rootConfigured: expandedRoot !== undefined,
+    version: PKG_VERSION,
+});
 
 if (port !== undefined) {
     // Streamable HTTP transport — stateless (no session management).

package/src/root-path.ts

@@ -0,0 +1,64 @@
+// Resolves the --root argument into a real absolute path.
+//
+// Claude Desktop's .mcpb variable substitution is single-pass: a `user_config`
+// default like "${HOME}/Downloads" can reach the server with `${HOME}` still
+// unexpanded when the user installs the bundle without opening the directory
+// picker (the optional field's raw default is used verbatim for the
+// `${user_config.*}` substitution, and the nested token is never re-expanded).
+// To stay robust regardless of host behavior we expand the mcpb special tokens,
+// a leading `~`, and generic environment variables here.
+//
+// Spec: specs/mcp.md ".mcpb bundle packaging".
+
+import { homedir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+
+/**
+ * Expands `--root` into an absolute path, or returns `undefined` when no
+ * usable root was provided (undefined or empty — e.g. an optional `.mcpb`
+ * directory field left blank, which the host passes as an empty string).
+ *
+ * Handled tokens:
+ * - mcpb specials: `${HOME}`, `${DESKTOP}`, `${DOCUMENTS}`, `${DOWNLOADS}`,
+ *   `${pathSeparator}`, `${/}`
+ * - generic environment variables: `${NAME}` / `$NAME` (uppercase)
+ * - a leading `~` / `~/`
+ */
+export function expandRootPath(raw: string | undefined): string | undefined {
+    if (raw === undefined) return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === '') return undefined;
+
+    const home = homedir();
+    const specials: Record<string, string> = {
+        HOME: home,
+        DESKTOP: join(home, 'Desktop'),
+        DOCUMENTS: join(home, 'Documents'),
+        DOWNLOADS: join(home, 'Downloads'),
+    };
+
+    let out = trimmed;
+
+    // mcpb path-separator tokens.
+    out = out.replace(/\$\{pathSeparator\}/g, sep).replace(/\$\{\/\}/g, sep);
+
+    // ${NAME} / $NAME — mcpb special dirs first, then generic env vars.
+    out = out.replace(
+        /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g,
+        (match, braced: string | undefined, bare: string | undefined) => {
+            const name = braced ?? bare ?? '';
+            if (name in specials) return specials[name];
+            const env = process.env[name];
+            return env !== undefined ? env : match;
+        },
+    );
+
+    // Leading ~ / ~/.
+    if (out === '~') {
+        out = home;
+    } else if (out.startsWith('~/') || out.startsWith(`~${sep}`)) {
+        out = join(home, out.slice(2));
+    }
+
+    return resolve(out);
+}

package/src/schemas.ts

@@ -60,7 +60,6 @@ export const RenderOutputSchema = z.object({
     /** Set when the output was written to disk. */
     path: z.string().optional(),
     bytes: z.number().optional(),
-    shareUrl: z.string().optional(),
     insights: z.array(InsightSchema).optional(),
 });
 
@@ -68,7 +67,10 @@ export const ExportOutputSchema = z.object({
     format: z.string(),
     path: z.string().optional(),
     bytes: z.number().optional(),
-    shareUrl: z.string().optional(),
+});
+
+export const ShareOutputSchema = z.object({
+    shareUrl: z.string(),
 });
 
 export const ConvertOutputSchema = z.object({

package/src/server.ts

@@ -15,7 +15,7 @@ import {
     registerAppTool,
 } from '@modelcontextprotocol/ext-apps/server';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { parseNowlineJson, printNowlineFile } from '@nowline/core';
+import { type NowlineFile, parseNowlineJson, printNowlineFile } from '@nowline/core';
 import {
     type ExportFormat,
     exportDocument,
@@ -63,6 +63,7 @@ import {
     ReferenceOutputSchema,
     RenderOutputSchema,
     SchemaOutputSchema,
+    ShareOutputSchema,
     UpdateOutputSchema,
     ValidateOutputSchema,
 } from './schemas.js';
@@ -218,6 +219,8 @@ async function sourceAndPath(
 export interface McpServerOptions {
     /** Working directory — all file paths are resolved relative to this root. Defaults to process.cwd(). */
     allowedRoot?: string;
+    /** Whether the allowed root was explicitly configured (vs. defaulting to cwd). Controls smart export delivery for binary formats. Defaults to false. */
+    rootConfigured?: boolean;
     /** Server name shown in the MCP client. Defaults to 'nowline'. */
     name?: string;
     /** Server version. Defaults to package version. */
@@ -226,6 +229,7 @@ export interface McpServerOptions {
 
 export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     const allowedRoot = opts.allowedRoot ?? process.cwd();
+    const rootConfigured = opts.rootConfigured ?? false;
     const server = new McpServer(
         {
             name: opts.name ?? 'nowline',
@@ -239,7 +243,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 '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.',
+                'call `render` with `review:true` for a final visual check. JSON in `convert` is AST conversion only. ' +
+                'Presenting output: default to `render` (in-chat preview / inline image) — the primary presentation. ' +
+                'The in-chat preview is view-only (no download/export button). Use `export` to produce a file. ' +
+                'Export files: binary formats (pdf, xlsx, png) are auto-saved to the configured folder — omit `delivery` ' +
+                'and omit `output` to let the server save the file; never use `delivery:"inline"` for pdf/xlsx on Claude ' +
+                'Desktop (the host cannot display inline documents, so nothing appears). For svg/html/mermaid exports, ' +
+                'present the returned text to the user as a downloadable artifact of the matching type ' +
+                '(.svg / .html / .mermaid) so they can save it. ' +
+                'Use the `share` tool only when the user explicitly wants a link they can open or share ' +
+                '(opens the free Nowline web app, where they can also export).',
         },
     );
 
@@ -554,8 +567,9 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         '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.',
+                'Validate then render a .nowline roadmap to SVG or PNG (combined validate+render). ' +
+                    'Returns structured diagnostics on error-severity input instead of a raw kernel error. ' +
+                    'On MCP Apps hosts the in-chat preview is view-only (no download/export button); use `export` for files and the `share` tool for an openable link.',
             ),
             inputSchema: z.object({
                 source: z.string().optional().describe('Inline .nowline source text.'),
@@ -592,12 +606,6 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                             '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()
@@ -655,9 +663,6 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             const bytes = needsRender
                 ? await exportDocument(source, format, inputs, host)
                 : new Uint8Array(0);
-            const shareUrl = args.share
-                ? (buildShareLink({ source, share: true }) ?? undefined)
-                : undefined;
 
             const insights = await collectMcpLayoutInsights({
                 source,
@@ -696,7 +701,6 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                         format,
                         path: outAbs,
                         bytes: bytes.byteLength,
-                        shareUrl,
                         ...insightsField,
                     };
                     return {
@@ -716,7 +720,6 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             if (appActive) {
                 const structured = {
                     format,
-                    shareUrl,
                     ...insightsField,
                 };
                 return {
@@ -733,7 +736,6 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 const structured = {
                     format,
                     bytes: bytes.byteLength,
-                    shareUrl,
                     ...insightsField,
                 };
                 return {
@@ -750,7 +752,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 };
             }
             const svgText = new TextDecoder('utf-8').decode(bytes);
-            const structured = { format, shareUrl, ...insightsField };
+            const structured = { format, ...insightsField };
             return {
                 content: [
                     { type: 'text', text: svgText, mimeType: 'image/svg+xml' },
@@ -764,14 +766,17 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
     // ---- export -------------------------------------------------------------
 
-    const EXPORT_FORMATS = ['pdf', 'html', 'mermaid', 'xlsx', 'msproj', 'png'] as const;
+    const EXPORT_FORMATS = ['svg', 'pdf', 'html', 'mermaid', 'xlsx', 'msproj', 'png'] as const;
     type NonRenderFormat = (typeof EXPORT_FORMATS)[number];
 
     server.registerTool(
         'export',
         {
             description:
-                'Export a .nowline roadmap to any of the eight canonical formats. Byte-identical to `nowline -f <format>` for the same source and inputs.',
+                'Export a .nowline roadmap to any of the eight canonical formats. Byte-identical to `nowline -f <format>` for the same source and inputs. ' +
+                'For pdf/xlsx/png: omit `delivery` and omit `output` — the server auto-saves to the configured folder and returns the path. ' +
+                'Never use `delivery:"inline"` for binary formats on Claude Desktop (inline binary cannot be displayed). ' +
+                'For svg/html/mermaid: the text is returned inline — present it to the user as a downloadable artifact of the matching type.',
             inputSchema: z.object({
                 source: z.string().optional().describe('Inline .nowline source text.'),
                 path: z
@@ -784,15 +789,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     ),
                 format: z
                     .enum(EXPORT_FORMATS)
-                    .describe('Export format: pdf, html, mermaid, xlsx, msproj, or png.'),
+                    .describe('Export format: svg, pdf, html, mermaid, xlsx, msproj, or png.'),
                 output: z
                     .string()
                     .optional()
                     .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.',
+                        'Optional path to write the output file. Omit for binary formats (pdf, xlsx, png) — ' +
+                            'the server auto-saves to the configured folder as <roadmap-id>.<ext>. ' +
+                            'To choose a filename, pass a bare filename (e.g. "roadmap.pdf") — it is saved into the configured folder. ' +
+                            '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(),
@@ -807,11 +813,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .string()
                     .optional()
                     .describe('MS Project start date override (YYYY-MM-DD).'),
-                share: z
-                    .boolean()
+                delivery: z
+                    .enum(['file', 'inline', 'both'])
                     .optional()
                     .describe(
-                        'When true, include a shareUrl pointing to https://free.nowline.io/open.',
+                        '"file" — write to disk and return the path (no inline bytes). ' +
+                            '"inline" — return bytes in the response (embedded resource for pdf/xlsx, image for png, text for other formats). ' +
+                            '"both" — write to disk and also attach inline bytes. ' +
+                            'Default is smart per format: pdf/xlsx/png write to disk when a root folder is configured, else return inline; text formats (svg/html/mermaid/msproj) always return inline. ' +
+                            'IMPORTANT — for pdf/xlsx/png on Claude Desktop, prefer omitting `delivery` entirely (smart default saves the file). ' +
+                            'Do NOT use delivery:"inline" for pdf/xlsx — Claude Desktop silently drops inline documents, so nothing appears to the user.',
                     ),
             }),
             outputSchema: ExportOutputSchema,
@@ -851,50 +862,157 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             }
             const host = createNodeHostEnv(filePath);
             const bytes = await exportDocument(source, format, inputs, host);
-            const shareUrl = args.share
-                ? (buildShareLink({ source, share: true }) ?? undefined)
-                : undefined;
 
             const BINARY_FORMATS = new Set<ExportFormat>(['png', 'pdf', 'xlsx']);
             const isBinary = BINARY_FORMATS.has(format);
 
-            if (args.output) {
+            // Default filename: <roadmap-id>.<ext>, used when no output path is given.
+            const FORMAT_EXT: Record<string, string> = {
+                svg: '.svg',
+                pdf: '.pdf',
+                xlsx: '.xlsx',
+                png: '.png',
+                html: '.html',
+                mermaid: '.md',
+                msproj: '.xml',
+            };
+            const ext = FORMAT_EXT[format] ?? `.${format}`;
+            const roadmapId =
+                (blocked.doc.parseResult.value as NowlineFile).roadmapDecl?.name ?? 'roadmap';
+            const defaultFilename = `${roadmapId}${ext}`;
+
+            // Resolve delivery mode.
+            const hasExplicitOutput = !!args.output;
+            const delivery = args.delivery;
+            let doWrite: boolean;
+            let doInline: boolean;
+
+            if (hasExplicitOutput) {
+                doWrite = true;
+                doInline = delivery === 'both';
+            } else if (delivery === 'file') {
+                doWrite = true;
+                doInline = false;
+            } else if (delivery === 'inline') {
+                doWrite = false;
+                doInline = true;
+            } else if (delivery === 'both') {
+                doWrite = true;
+                doInline = true;
+            } else {
+                // Smart default: binary formats (pdf/xlsx/png) write to the configured root
+                // (return a reference, not bytes — the idiomatic MCP pattern). Text formats
+                // (svg/html/mermaid/msproj) always return inline so Claude can surface them
+                // as downloadable artifacts.
+                if (format === 'pdf' || format === 'xlsx' || format === 'png') {
+                    doWrite = rootConfigured;
+                    doInline = !rootConfigured;
+                } else {
+                    // svg/html/mermaid/msproj: always inline text.
+                    doWrite = false;
+                    doInline = true;
+                }
+            }
+
+            // Write to disk if needed.
+            const outTarget = args.output ?? path.join(allowedRoot, defaultFilename);
+            let writtenPath: string | undefined;
+            if (doWrite) {
                 try {
-                    const outAbs = resolveAndGuard(args.output, allowedRoot);
+                    const outAbs = resolveAndGuard(outTarget, 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,
-                    };
+                    writtenPath = outAbs;
                 } catch (err) {
-                    return handleToolError(err, args.output);
+                    return handleToolError(err, args.output ?? outTarget);
                 }
             }
 
-            if (isBinary) {
-                const mimeMap: Record<string, string> = {
-                    png: 'image/png',
-                    pdf: 'application/pdf',
-                    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-                };
-                const structured = { format, bytes: bytes.byteLength, shareUrl };
-                return {
-                    content: [
-                        {
-                            type: 'image',
-                            data: Buffer.from(bytes).toString('base64'),
-                            mimeType: mimeMap[format] ?? 'application/octet-stream',
-                        },
-                    ],
-                    structuredContent: structured,
-                };
+            // Build response content.
+            const contentBlocks: ContentBlock[] = [];
+            if (writtenPath !== undefined) {
+                contentBlocks.push({
+                    type: 'text',
+                    text: `Saved to \`${writtenPath}\` (${bytes.byteLength} bytes).`,
+                });
+            }
+            if (doInline) {
+                if (isBinary) {
+                    contentBlocks.push(
+                        ...buildExportInlineContentBlocks(format, bytes, !doWrite, rootConfigured),
+                    );
+                } else {
+                    const TEXT_MIME: Record<string, string> = {
+                        svg: 'image/svg+xml',
+                        html: 'text/html',
+                        mermaid: 'text/markdown',
+                        msproj: 'application/xml',
+                    };
+                    const text = new TextDecoder('utf-8').decode(bytes);
+                    const mt = TEXT_MIME[format];
+                    contentBlocks.push({ type: 'text', text, ...(mt ? { mimeType: mt } : {}) });
+                }
+            }
+
+            const structured: Record<string, unknown> = { format };
+            if (writtenPath !== undefined) {
+                structured.path = writtenPath;
+                structured.bytes = bytes.byteLength;
+            } else if (doInline && isBinary) {
+                structured.bytes = bytes.byteLength;
             }
-            const text = new TextDecoder('utf-8').decode(bytes);
-            const structured = { format, shareUrl };
+
             return {
-                content: [{ type: 'text', text }],
+                content: contentBlocks,
+                structuredContent: structured,
+            };
+        },
+    );
+
+    // ---- share --------------------------------------------------------------
+
+    server.registerTool(
+        'share',
+        {
+            description:
+                'Generate a shareable link for a roadmap. The roadmap source is encoded into the URL fragment ' +
+                '(client-side; no upload, no account, no network call) and opens in the free Nowline web app ' +
+                '(free.nowline.io/open), where anyone with the link can view it and export to PDF/PNG/SVG. ' +
+                'Prefer `render` to show a roadmap in chat — that is the default. Use `share` only when the user ' +
+                'explicitly asks for a link to open, send, or export elsewhere.',
+            inputSchema: z.object({
+                source: z.string().optional().describe('Inline .nowline source text.'),
+                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.',
+                    ),
+            }),
+            outputSchema: ShareOutputSchema,
+            annotations: readOnlyTool('Share Roadmap'),
+        },
+        async (args) => {
+            let source: string;
+            let filePath: string;
+            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;
+
+            // buildShareLink returns null only for share:false/'none'; this tool
+            // always requests share:true, so the result is always a link.
+            const shareUrl = buildShareLink({ source, share: true }) as string;
+
+            const structured = { shareUrl };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
                 structuredContent: structured,
             };
         },
@@ -1207,7 +1325,62 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
 type ContentBlock =
     | { type: 'text'; text: string; mimeType?: string }
-    | { type: 'image'; data: string; mimeType: string };
+    | { type: 'image'; data: string; mimeType: string }
+    | {
+          type: 'resource';
+          resource: { uri: string; mimeType: string; blob: string };
+      };
+
+const EXPORT_BINARY_SHARE_HINT_NO_ROOT =
+    'No file was written. To save a file, pass `output: "/path/to/roadmap.pdf"` or `delivery: "file"` ' +
+    '(on Claude Desktop, configure an output folder in the server settings so the server can auto-save). ' +
+    'For a shareable link the user can view and export from, call the `share` tool.';
+
+const EXPORT_BINARY_SHARE_HINT_ROOT_CONFIGURED =
+    'No file was written because `delivery:"inline"` was requested. ' +
+    'Claude Desktop cannot display inline pdf/xlsx documents, so nothing appeared. ' +
+    'Omit `delivery` (or use `delivery:"file"`) to let the server save the file to the configured output folder — ' +
+    'then share that local path with the user. Alternatively call the `share` tool for an openable link.';
+
+function buildExportInlineContentBlocks(
+    format: ExportFormat,
+    bytes: Uint8Array,
+    showHint = true,
+    rootConfigured = false,
+): ContentBlock[] {
+    const mimeMap: Record<string, string> = {
+        png: 'image/png',
+        pdf: 'application/pdf',
+        xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    };
+    const mimeType = mimeMap[format] ?? 'application/octet-stream';
+    const base64 = Buffer.from(bytes).toString('base64');
+
+    // PNG renders inline as an image — no resource wrapper or share hint needed.
+    if (format === 'png') {
+        return [{ type: 'image', data: base64, mimeType }];
+    }
+
+    // pdf/xlsx: embedded resource block, and optionally a hint pointing the agent
+    // at output:/delivery:'file' when no file was also written.
+    const blocks: ContentBlock[] = [
+        {
+            type: 'resource',
+            resource: {
+                uri: `nowline://export/roadmap.${format}`,
+                mimeType,
+                blob: base64,
+            },
+        },
+    ];
+    if (showHint) {
+        const hint = rootConfigured
+            ? EXPORT_BINARY_SHARE_HINT_ROOT_CONFIGURED
+            : EXPORT_BINARY_SHARE_HINT_NO_ROOT;
+        blocks.push({ type: 'text', text: hint });
+    }
+    return blocks;
+}
 
 async function buildReviewContentBlocks(
     source: string,