@nowline/mcp 0.9.0 → 0.10.0

package/src/index.ts

@@ -80,7 +80,8 @@ if (help) {
             'Start the Nowline MCP server.',
             '',
             'Options:',
-            '  --root <path>   Allowed root for file operations. Defaults to cwd.',
+            '  --root <path>   Allowed root for file operations. Defaults to the',
+            "                  client's MCP roots, else cwd.",
             '  --port <N>      Listen on localhost:<N> using Streamable HTTP transport.',
             '                  When omitted, uses stdio transport (default).',
             '  --version, -v   Print version and exit.',

package/src/server.ts

@@ -79,6 +79,7 @@ import {
     UpdateOutputSchema,
     ValidateOutputSchema,
 } from './schemas.js';
+import { createWorkspaceRoots, isInsideRoots, type WorkspaceRoots } from './workspace-roots.js';
 
 // ---- MCP Apps UI (in-chat live preview) -------------------------------------
 //
@@ -174,11 +175,10 @@ function mutatingTool(title: string, opts: { destructiveHint: boolean; idempoten
 
 // ---- Server factory ---------------------------------------------------------
 
-function resolveAndGuard(filePath: string, allowedRoot: string): string {
-    const abs = path.resolve(allowedRoot, filePath);
-    const guard = path.resolve(allowedRoot);
-    if (!abs.startsWith(guard + path.sep) && abs !== guard) {
-        throw new PathOutsideRootError(filePath, allowedRoot);
+function resolveAndGuard(filePath: string, roots: WorkspaceRoots): string {
+    const abs = path.resolve(roots.primary, filePath);
+    if (!isInsideRoots(abs, roots)) {
+        throw new PathOutsideRootError(filePath, roots.allowed.join(', '));
     }
     return abs;
 }
@@ -224,13 +224,13 @@ function findExample(name: string): ExampleFile | undefined {
 
 async function sourceAndPath(
     args: { source?: string; path?: string },
-    allowedRoot: string,
+    roots: WorkspaceRoots,
 ): Promise<{ source: string; filePath: string }> {
     if (args.source !== undefined && args.path === undefined) {
-        return { source: args.source, filePath: path.join(allowedRoot, 'unnamed.nowline') };
+        return { source: args.source, filePath: path.join(roots.primary, 'unnamed.nowline') };
     }
     if (args.path !== undefined) {
-        const abs = resolveAndGuard(args.path, allowedRoot);
+        const abs = resolveAndGuard(args.path, roots);
         const source = args.source ?? (await fs.readFile(abs, 'utf-8'));
         return { source, filePath: abs };
     }
@@ -240,7 +240,10 @@ async function sourceAndPath(
 // ---- Server factory ---------------------------------------------------------
 
 export interface McpServerOptions {
-    /** Working directory — all file paths are resolved relative to this root. Defaults to process.cwd(). */
+    /**
+     * Working directory: all file paths resolve relative to this root. When omitted, the
+     * server uses the client's MCP roots if it advertises them, else 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;
@@ -251,7 +254,6 @@ export interface McpServerOptions {
 }
 
 export function createMcpServer(opts: McpServerOptions = {}): McpServer {
-    const allowedRoot = opts.allowedRoot ?? process.cwd();
     const rootConfigured = opts.rootConfigured ?? false;
     const server = new McpServer(
         {
@@ -279,6 +281,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
     );
 
+    const workspaceRoots = createWorkspaceRoots(server, opts.allowedRoot);
+
     // ---- Resources ----------------------------------------------------------
 
     server.registerResource(
@@ -418,7 +422,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         async (args) => {
             try {
                 const { options } = resolveMcpOptions(args);
-                const { source, filePath } = await sourceAndPath(args, allowedRoot);
+                const { source, filePath } = await sourceAndPath(args, await workspaceRoots());
                 const doc = await buildDocument(source);
                 const diagnostics = collectMcpDiagnostics(doc, filePath);
                 // One stage: the routed (wave-rule) include diagnostics join
@@ -478,7 +482,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             try {
-                const abs = resolveAndGuard(args.path, allowedRoot);
+                const abs = resolveAndGuard(args.path, await workspaceRoots());
                 const source = await fs.readFile(abs, 'utf-8');
                 const structured = { path: abs, source };
                 return {
@@ -512,7 +516,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             try {
-                const abs = resolveAndGuard(args.path, allowedRoot);
+                const abs = resolveAndGuard(args.path, await workspaceRoots());
                 const blocked = await diagnosticsErrorBlock(args.source, abs);
                 if (!blocked.ok) return blocked.response;
                 await fs.mkdir(path.dirname(abs), { recursive: true });
@@ -550,7 +554,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             try {
-                const abs = resolveAndGuard(args.path, allowedRoot);
+                const abs = resolveAndGuard(args.path, await workspaceRoots());
                 const blocked = await diagnosticsErrorBlock(args.source, abs);
                 if (!blocked.ok) return blocked.response;
                 await fs.writeFile(abs, args.source, 'utf-8');
@@ -581,7 +585,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             try {
-                const abs = resolveAndGuard(args.path, allowedRoot);
+                const abs = resolveAndGuard(args.path, await workspaceRoots());
                 await fs.unlink(abs);
                 const structured = { path: abs };
                 return {
@@ -605,7 +609,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .string()
                     .optional()
                     .describe(
-                        'Directory to scan. Defaults to the allowed root (cwd or --root). Absolute or relative.',
+                        "Directory to scan. Defaults to the project root (--root, else the client's first MCP root, else cwd). Absolute or relative.",
                     ),
                 recursive: z
                     .boolean()
@@ -617,9 +621,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             try {
-                const dir = args.directory
-                    ? resolveAndGuard(args.directory, allowedRoot)
-                    : allowedRoot;
+                const roots = await workspaceRoots();
+                const dir = args.directory ? resolveAndGuard(args.directory, roots) : roots.primary;
                 const recursive = args.recursive ?? false;
                 const paths = await listNowlineFiles(dir, recursive);
                 const structured = { paths };
@@ -715,7 +718,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             let source: string;
             let filePath: string;
             try {
-                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+                ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
             } catch (err) {
                 return handleToolError(err, args.path);
             }
@@ -795,7 +798,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
             if (args.output) {
                 try {
-                    const outAbs = resolveAndGuard(args.output, allowedRoot);
+                    const outAbs = resolveAndGuard(args.output, await workspaceRoots());
                     await fs.mkdir(path.dirname(outAbs), { recursive: true });
                     await fs.writeFile(outAbs, bytes);
                     const structured = {
@@ -949,7 +952,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             let source: string;
             let filePath: string;
             try {
-                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+                ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
             } catch (err) {
                 return handleToolError(err, args.path);
             }
@@ -1043,11 +1046,12 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             }
 
             // Write to disk if needed.
-            const outTarget = args.output ?? path.join(allowedRoot, defaultFilename);
+            const roots = await workspaceRoots();
+            const outTarget = args.output ?? path.join(roots.primary, defaultFilename);
             let writtenPath: string | undefined;
             if (doWrite) {
                 try {
-                    const outAbs = resolveAndGuard(outTarget, allowedRoot);
+                    const outAbs = resolveAndGuard(outTarget, roots);
                     await fs.mkdir(path.dirname(outAbs), { recursive: true });
                     await fs.writeFile(outAbs, bytes);
                     writtenPath = outAbs;
@@ -1126,7 +1130,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             let source: string;
             let filePath: string;
             try {
-                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+                ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
             } catch (err) {
                 return handleToolError(err, args.path);
             }
@@ -1175,7 +1179,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         async (args) => {
             try {
                 if (args.to === 'json') {
-                    const { source, filePath } = await sourceAndPath(args, allowedRoot);
+                    const { source, filePath } = await sourceAndPath(args, await workspaceRoots());
                     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.
@@ -1203,7 +1207,10 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 const jsonSource =
                     args.source ??
                     (args.path
-                        ? await fs.readFile(resolveAndGuard(args.path, allowedRoot), 'utf-8')
+                        ? await fs.readFile(
+                              resolveAndGuard(args.path, await workspaceRoots()),
+                              'utf-8',
+                          )
                         : null);
                 if (!jsonSource) {
                     throw new InputRequiredError('At least one of `source` or `path` is required.');

package/src/workspace-roots.ts

@@ -0,0 +1,99 @@
+// Where the server's file tools resolve paths.
+//
+// An explicit root (`--root`, or `allowedRoot` from an embedder) always wins
+// and the client is never asked. Without one, the server asks a client that
+// advertises the MCP `roots` capability for its roots, because a harness may
+// start the server somewhere other than the project (a plugin cache, the app
+// bundle). A client without roots, an empty or non-`file://` list, or a failed
+// `roots/list` falls back to `process.cwd()`.
+//
+// Multiple roots: every root is allowed, and relative paths resolve against
+// the first. The answer is cached until the client sends
+// `notifications/roots/list_changed`.
+//
+// Spec: specs/mcp.md "Shared tool contract".
+
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { McpServer } from '@modelcontextprotocol/server';
+
+export interface WorkspaceRoots {
+    /** Relative paths resolve against this root; `list` and default export output use it. */
+    readonly primary: string;
+    /** Every root a path may land in. Always contains `primary`. */
+    readonly allowed: readonly string[];
+}
+
+/** Bounds a `roots/list` round trip so a client that never answers can't hang a tool call. */
+const LIST_ROOTS_TIMEOUT_MS = 5_000;
+
+export function staticRoots(root: string): WorkspaceRoots {
+    const abs = path.resolve(root);
+    return { primary: abs, allowed: [abs] };
+}
+
+/**
+ * Converts a `roots/list` result to filesystem roots. Non-`file://` and
+ * malformed URIs are skipped; duplicates collapse. Returns `undefined` when
+ * nothing usable remains.
+ */
+export function rootsFromUris(uris: readonly string[]): WorkspaceRoots | undefined {
+    const paths: string[] = [];
+    for (const uri of uris) {
+        let abs: string;
+        try {
+            if (!uri.startsWith('file:')) continue;
+            abs = path.resolve(fileURLToPath(uri));
+        } catch {
+            continue;
+        }
+        if (!paths.includes(abs)) paths.push(abs);
+    }
+    return paths.length > 0 ? { primary: paths[0], allowed: paths } : undefined;
+}
+
+/**
+ * Returns a function yielding the current roots for `server`. With
+ * `configuredRoot` set the result is fixed; otherwise it follows the client's
+ * roots as described above. Never rejects.
+ */
+export function createWorkspaceRoots(
+    server: McpServer,
+    configuredRoot: string | undefined,
+): () => Promise<WorkspaceRoots> {
+    if (configuredRoot !== undefined) {
+        const fixed = staticRoots(configuredRoot);
+        return async () => fixed;
+    }
+
+    let cached: Promise<WorkspaceRoots> | undefined;
+    server.server.setNotificationHandler('notifications/roots/list_changed', () => {
+        cached = undefined;
+    });
+
+    async function fetchRoots(): Promise<WorkspaceRoots> {
+        const fallback = staticRoots(process.cwd());
+        if (!server.server.getClientCapabilities()?.roots) return fallback;
+        try {
+            const { roots } = await server.server.listRoots(undefined, {
+                timeout: LIST_ROOTS_TIMEOUT_MS,
+            });
+            return rootsFromUris(roots.map((r) => r.uri)) ?? fallback;
+        } catch {
+            return fallback;
+        }
+    }
+
+    return () => {
+        cached ??= fetchRoots();
+        return cached;
+    };
+}
+
+/** Whether the absolute path `abs` is one of the allowed roots or inside one. */
+export function isInsideRoots(abs: string, roots: WorkspaceRoots): boolean {
+    return roots.allowed.some((root) => {
+        const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+        return abs === root || abs.startsWith(prefix);
+    });
+}