@j0hanz/filesystem-mcp 1.19.1 → 2.0.0

package/dist/cli-help.d.ts

@@ -0,0 +1,3 @@
+export declare function printHelpAndExit(): never;
+export declare function printVersionAndExit(): never;
+//# sourceMappingURL=cli-help.d.ts.map

package/dist/cli-help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-help.d.ts","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"AAgJA,wBAAgB,gBAAgB,IAAI,KAAK,CAkCxC;AAED,wBAAgB,mBAAmB,IAAI,KAAK,CAG3C"}

package/dist/cli-help.js

@@ -0,0 +1,169 @@
+import packageJson from '../package.json' with { type: 'json' };
+import { cliFmt, padEndVisible } from './core/fmt.js';
+import { MUTATING_TOOL_NAMES } from './tools/index.js';
+// Help text and its rendering. Split out of cli.ts so that module holds only
+// argument parsing and directory validation: this file is static copy plus a
+// formatter, and shares no state with the parser.
+const { version: SERVER_VERSION } = packageJson;
+const OPTIONS_HELP = [
+    { flags: '-h, --help', desc: 'Show this help message' },
+    { flags: '-v, --version', desc: 'Show the server version' },
+    { flags: '--allow-cwd', desc: 'Add the current working directory as an allowed root' },
+    {
+        flags: '--port <number>',
+        desc: 'Start HTTP transport on this port (env: FS_PORT)',
+    },
+    {
+        flags: '--read-only',
+        desc: `Disable write tools: ${[...MUTATING_TOOL_NAMES].sort().join(', ')}`,
+    },
+    { flags: '--safe', desc: 'Alias for --read-only' },
+    {
+        flags: '--print-config',
+        desc: 'Print the active configuration and exit (use with --json for machine output)',
+    },
+    { flags: '--json', desc: 'Output --print-config as JSON' },
+    {
+        flags: '--log-level <level>',
+        desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency (env: FS_LOG_LEVEL)',
+    },
+    { flags: '--http-host <host>', desc: 'HTTP server bind address (env: FS_HTTP_HOST)' },
+    {
+        flags: '--api-key <key>',
+        desc: 'Require this API key on HTTP requests; prefer FS_API_KEY (argv is world-readable)',
+    },
+    {
+        flags: '--allow-sensitive',
+        desc: 'Allow access to sensitive system paths (env: FS_ALLOW_SENSITIVE)',
+    },
+    {
+        flags: '--root-boundary <path>',
+        desc: 'Require all allowed roots to fall under this path (env: FS_ROOT_BOUNDARY)',
+    },
+    {
+        flags: '--max-file-size <bytes>',
+        desc: 'Maximum file size for reads in bytes (env: FS_MAX_FILE_SIZE)',
+    },
+    { flags: '--walk-cwd', desc: 'Walk up from CWD to find a project root; implies --allow-cwd' },
+    { flags: '--deny <pattern>', desc: 'Block paths matching this pattern; repeatable' },
+    {
+        flags: '--allow-missing-roots',
+        desc: 'Start even if configured allowed directories do not exist',
+    },
+];
+const ENV_HELP = [
+    {
+        flags: 'FS_LOG_LEVEL',
+        desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency',
+    },
+    { flags: 'FS_PORT', desc: 'Start HTTP transport on this port (unset = stdio)' },
+    { flags: 'FS_HTTP_HOST', desc: 'HTTP bind address' },
+    { flags: 'FS_API_KEY', desc: 'HTTP API key' },
+    {
+        flags: 'FS_TRUST_PROXY',
+        desc: 'Express trust-proxy setting: hop count or expression (unset = do not trust X-Forwarded-*)',
+    },
+    {
+        flags: 'FS_ALLOW_SENSITIVE',
+        desc: 'Allow sensitive system paths ("true" or "1" enables this)',
+    },
+    { flags: 'FS_ROOT_BOUNDARY', desc: 'Path prefix all allowed roots must fall under' },
+    { flags: 'FS_MAX_FILE_SIZE', desc: 'Maximum file size for reads in bytes' },
+    {
+        flags: 'FS_ALLOWED_DIRS',
+        desc: 'Allowed dirs: colon-separated (Unix), semicolon-separated (Windows)',
+    },
+    {
+        flags: 'FS_ALLOW_CWD_WALK',
+        desc: 'Walk up from CWD to find a project root ("true" or "1" enables this)',
+    },
+    { flags: 'FS_DENYLIST', desc: 'Paths/patterns to block, comma-separated' },
+    {
+        flags: 'FS_ALLOW_MISSING_ROOTS',
+        desc: 'Start even if configured allowed directories do not exist ("true" or "1" enables this)',
+    },
+    {
+        flags: 'FS_ALLOWED_HOSTS',
+        desc: 'Comma-separated Host header values to accept (HTTP transport)',
+    },
+    { flags: 'FS_ALLOWED_ORIGINS', desc: 'Comma-separated origin hostnames for CORS' },
+    {
+        flags: 'FS_ALLOW_UNRESTRICTED_HOSTS',
+        desc: 'Bind a wildcard host with no Host validation, accepts the risk ("true" or "1" enables this)',
+    },
+    { flags: 'FS_PUBLIC_URL', desc: 'Resource identifier URL for RFC 9728 discovery' },
+    {
+        flags: 'FS_RATE_LIMIT_RPM',
+        desc: 'Per-client-IP requests/min (default 120 authenticated, 6000 keyless loopback; 1–100000)',
+    },
+    {
+        flags: 'FS_MAX_REQUEST_BYTES',
+        desc: 'Max HTTP request body bytes (default 4194304, 1024–268435456)',
+    },
+    {
+        flags: 'FS_KEEPALIVE_TIMEOUT_MS',
+        desc: 'HTTP keep-alive timeout; set above any fronting proxy idle timeout (default 5000, 1000–600000)',
+    },
+    {
+        flags: 'FS_MAX_WATCHERS',
+        desc: 'Max concurrent file watchers (default 256, 1–4096)',
+    },
+    {
+        flags: 'FS_MAX_INLINE_MATCHES',
+        desc: 'Max inline content matches per search (default 50, 1–10000)',
+    },
+    {
+        flags: 'FS_MAX_READ_MANY_BYTES',
+        desc: 'Max total bytes across one batch read (default 524288, 10240–104857600)',
+    },
+    { flags: 'FS_SEARCH_TIMEOUT_MS', desc: 'Search timeout in ms (default 5000, 100–60000)' },
+    { flags: 'NO_COLOR', desc: 'Any value disables ANSI color output' },
+    {
+        flags: 'FS_REQUEST_STATE_KEY',
+        desc: 'HMAC key for input_required state; optional outside fleet mode, shared and >=32 bytes in fleet mode',
+    },
+];
+const EXAMPLES_HELP = [
+    '$ filesystem-mcp /path/to/allowed/dir',
+    '$ filesystem-mcp --allow-cwd',
+    '$ filesystem-mcp /project/src /project/tests --allow-cwd',
+    '$ filesystem-mcp --port 3000 /path/to/allowed/dir',
+    '$ filesystem-mcp --read-only /data/readonly',
+    '$ filesystem-mcp --print-config --json /project',
+];
+export function printHelpAndExit() {
+    const { bold, dim, section, flag, placeholder, cyan } = cliFmt;
+    const COL = 27;
+    const optRow = (flags, desc) => {
+        const colored = flags
+            .replace(/<[^>]+>/g, (m) => placeholder(m))
+            .replace(/-{1,2}[\w-]+/g, (m) => flag(m));
+        return `  ${padEndVisible(colored, COL)}${desc}`;
+    };
+    const envRow = (name, desc) => {
+        return `  ${padEndVisible(cyan(name), COL - 1)} ${desc}`;
+    };
+    const lines = [
+        '',
+        `${bold('Filesystem MCP')} ${dim(`v${SERVER_VERSION}`)}`,
+        '',
+        dim('Pass one or more directories to set the allowed access roots.'),
+        '',
+        section('Options:'),
+        ...OPTIONS_HELP.map(({ flags, desc }) => optRow(flags, desc)),
+        '',
+        `${section('Environment variables:')} ${dim('(flags take precedence when both are set)')}`,
+        ...ENV_HELP.map(({ flags, desc }) => envRow(flags, desc)),
+        '',
+        section('Examples:'),
+        ...EXAMPLES_HELP.map((ex) => `  ${dim(ex)}`),
+        '',
+    ];
+    process.stdout.write(lines.join('\n'));
+    process.exit(0);
+}
+export function printVersionAndExit() {
+    process.stdout.write(`${cliFmt.cyan(SERVER_VERSION)}\n`);
+    process.exit(0);
+}
+//# sourceMappingURL=cli-help.js.map

package/dist/cli-help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-help.js","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"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","sourcesContent":["import packageJson from '../package.json' with { type: 'json' };\nimport { cliFmt, padEndVisible } from './core/fmt.js';\nimport { MUTATING_TOOL_NAMES } from './tools/index.js';\n\n// Help text and its rendering. Split out of cli.ts so that module holds only\n// argument parsing and directory validation: this file is static copy plus a\n// formatter, and shares no state with the parser.\n\nconst { version: SERVER_VERSION } = packageJson;\n\ninterface HelpRow {\n  flags: string;\n  desc: string;\n}\n\nconst OPTIONS_HELP: HelpRow[] = [\n  { flags: '-h, --help', desc: 'Show this help message' },\n  { flags: '-v, --version', desc: 'Show the server version' },\n  { flags: '--allow-cwd', desc: 'Add the current working directory as an allowed root' },\n  {\n    flags: '--port <number>',\n    desc: 'Start HTTP transport on this port (env: FS_PORT)',\n  },\n  {\n    flags: '--read-only',\n    desc: `Disable write tools: ${[...MUTATING_TOOL_NAMES].sort().join(', ')}`,\n  },\n  { flags: '--safe', desc: 'Alias for --read-only' },\n  {\n    flags: '--print-config',\n    desc: 'Print the active configuration and exit (use with --json for machine output)',\n  },\n  { flags: '--json', desc: 'Output --print-config as JSON' },\n  {\n    flags: '--log-level <level>',\n    desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency (env: FS_LOG_LEVEL)',\n  },\n  { flags: '--http-host <host>', desc: 'HTTP server bind address (env: FS_HTTP_HOST)' },\n  {\n    flags: '--api-key <key>',\n    desc: 'Require this API key on HTTP requests; prefer FS_API_KEY (argv is world-readable)',\n  },\n  {\n    flags: '--allow-sensitive',\n    desc: 'Allow access to sensitive system paths (env: FS_ALLOW_SENSITIVE)',\n  },\n  {\n    flags: '--root-boundary <path>',\n    desc: 'Require all allowed roots to fall under this path (env: FS_ROOT_BOUNDARY)',\n  },\n  {\n    flags: '--max-file-size <bytes>',\n    desc: 'Maximum file size for reads in bytes (env: FS_MAX_FILE_SIZE)',\n  },\n  { flags: '--walk-cwd', desc: 'Walk up from CWD to find a project root; implies --allow-cwd' },\n  { flags: '--deny <pattern>', desc: 'Block paths matching this pattern; repeatable' },\n  {\n    flags: '--allow-missing-roots',\n    desc: 'Start even if configured allowed directories do not exist',\n  },\n];\n\nconst ENV_HELP: HelpRow[] = [\n  {\n    flags: 'FS_LOG_LEVEL',\n    desc: 'Log level, RFC 5424: debug|info|notice|warn|error|critical|alert|emergency',\n  },\n  { flags: 'FS_PORT', desc: 'Start HTTP transport on this port (unset = stdio)' },\n  { flags: 'FS_HTTP_HOST', desc: 'HTTP bind address' },\n  { flags: 'FS_API_KEY', desc: 'HTTP API key' },\n  {\n    flags: 'FS_TRUST_PROXY',\n    desc: 'Express trust-proxy setting: hop count or expression (unset = do not trust X-Forwarded-*)',\n  },\n  {\n    flags: 'FS_ALLOW_SENSITIVE',\n    desc: 'Allow sensitive system paths (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_ROOT_BOUNDARY', desc: 'Path prefix all allowed roots must fall under' },\n  { flags: 'FS_MAX_FILE_SIZE', desc: 'Maximum file size for reads in bytes' },\n  {\n    flags: 'FS_ALLOWED_DIRS',\n    desc: 'Allowed dirs: colon-separated (Unix), semicolon-separated (Windows)',\n  },\n  {\n    flags: 'FS_ALLOW_CWD_WALK',\n    desc: 'Walk up from CWD to find a project root (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_DENYLIST', desc: 'Paths/patterns to block, comma-separated' },\n  {\n    flags: 'FS_ALLOW_MISSING_ROOTS',\n    desc: 'Start even if configured allowed directories do not exist (\"true\" or \"1\" enables this)',\n  },\n  {\n    flags: 'FS_ALLOWED_HOSTS',\n    desc: 'Comma-separated Host header values to accept (HTTP transport)',\n  },\n  { flags: 'FS_ALLOWED_ORIGINS', desc: 'Comma-separated origin hostnames for CORS' },\n  {\n    flags: 'FS_ALLOW_UNRESTRICTED_HOSTS',\n    desc: 'Bind a wildcard host with no Host validation, accepts the risk (\"true\" or \"1\" enables this)',\n  },\n  { flags: 'FS_PUBLIC_URL', desc: 'Resource identifier URL for RFC 9728 discovery' },\n  {\n    flags: 'FS_RATE_LIMIT_RPM',\n    desc: 'Per-client-IP requests/min (default 120 authenticated, 6000 keyless loopback; 1–100000)',\n  },\n  {\n    flags: 'FS_MAX_REQUEST_BYTES',\n    desc: 'Max HTTP request body bytes (default 4194304, 1024–268435456)',\n  },\n  {\n    flags: 'FS_KEEPALIVE_TIMEOUT_MS',\n    desc: 'HTTP keep-alive timeout; set above any fronting proxy idle timeout (default 5000, 1000–600000)',\n  },\n  {\n    flags: 'FS_MAX_WATCHERS',\n    desc: 'Max concurrent file watchers (default 256, 1–4096)',\n  },\n  {\n    flags: 'FS_MAX_INLINE_MATCHES',\n    desc: 'Max inline content matches per search (default 50, 1–10000)',\n  },\n  {\n    flags: 'FS_MAX_READ_MANY_BYTES',\n    desc: 'Max total bytes across one batch read (default 524288, 10240–104857600)',\n  },\n  { flags: 'FS_SEARCH_TIMEOUT_MS', desc: 'Search timeout in ms (default 5000, 100–60000)' },\n  { flags: 'NO_COLOR', desc: 'Any value disables ANSI color output' },\n  {\n    flags: 'FS_REQUEST_STATE_KEY',\n    desc: 'HMAC key for input_required state; optional outside fleet mode, shared and >=32 bytes in fleet mode',\n  },\n];\n\nconst EXAMPLES_HELP = [\n  '$ filesystem-mcp /path/to/allowed/dir',\n  '$ filesystem-mcp --allow-cwd',\n  '$ filesystem-mcp /project/src /project/tests --allow-cwd',\n  '$ filesystem-mcp --port 3000 /path/to/allowed/dir',\n  '$ filesystem-mcp --read-only /data/readonly',\n  '$ filesystem-mcp --print-config --json /project',\n];\n\nexport function printHelpAndExit(): never {\n  const { bold, dim, section, flag, placeholder, cyan } = cliFmt;\n  const COL = 27;\n\n  const optRow = (flags: string, desc: string): string => {\n    const colored = flags\n      .replace(/<[^>]+>/g, (m) => placeholder(m))\n      .replace(/-{1,2}[\\w-]+/g, (m) => flag(m));\n    return `  ${padEndVisible(colored, COL)}${desc}`;\n  };\n\n  const envRow = (name: string, desc: string): string => {\n    return `  ${padEndVisible(cyan(name), COL - 1)} ${desc}`;\n  };\n\n  const lines = [\n    '',\n    `${bold('Filesystem MCP')} ${dim(`v${SERVER_VERSION}`)}`,\n    '',\n    dim('Pass one or more directories to set the allowed access roots.'),\n    '',\n    section('Options:'),\n    ...OPTIONS_HELP.map(({ flags, desc }) => optRow(flags, desc)),\n    '',\n    `${section('Environment variables:')} ${dim('(flags take precedence when both are set)')}`,\n    ...ENV_HELP.map(({ flags, desc }) => envRow(flags, desc)),\n    '',\n    section('Examples:'),\n    ...EXAMPLES_HELP.map((ex) => `  ${dim(ex)}`),\n    '',\n  ];\n\n  process.stdout.write(lines.join('\\n'));\n  process.exit(0);\n}\n\nexport function printVersionAndExit(): never {\n  process.stdout.write(`${cliFmt.cyan(SERVER_VERSION)}\\n`);\n  process.exit(0);\n}\n"]}

package/dist/cli.d.ts

@@ -6,4 +6,32 @@ export declare function parseArgs(): Promise<{
     allowedDirs: string[];
     allowCwd: boolean;
     port: number | undefined;
+    readOnly: boolean;
+    printConfig: boolean;
+    json: boolean;
+    httpHost: string | undefined;
+    apiKey: string | undefined;
 }>;
+export interface EffectiveConfig {
+    transport: string;
+    readOnly: boolean;
+    allowedRoots: string[];
+    tools: string[];
+    apiKey: string | null;
+    limits: {
+        maxFileSizeBytes: number;
+    };
+}
+export interface PrintConfigOptions {
+    allowedDirs: string[];
+    allowCwd: boolean;
+    readOnly: boolean;
+    json: boolean;
+    /** Resolved `--port`. Present means the launch this reports on is an HTTP bind. */
+    port?: number;
+    httpHost?: string;
+    apiKey?: string;
+    stdout?: (chunk: string) => void;
+}
+export declare function runPrintConfig(options: PrintConfigOptions): Promise<EffectiveConfig>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAyBA,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAK9C;AAkJD,wBAAsB,SAAS,IAAI,OAAO,CAAC;IACzC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC,CAgFD;AAMD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAuC1F"}

package/dist/cli.js

@@ -1,13 +1,19 @@
 import { stat } from 'node:fs/promises';
-import { getSystemErrorMessage, getSystemErrorName } from 'node:util';
-import { Command, CommanderError, InvalidArgumentError } from 'commander';
-import { processInParallel } from './lib/fs-helpers.js';
-import { getReservedDeviceNameForPath, isWindowsDriveRelativePath, normalizePath, } from './lib/paths.js';
-import { isRecord } from './lib/utils.js';
-import { pkgInfo } from './pkg-info.js';
-const { version: SERVER_VERSION } = pkgInfo;
-const IS_WINDOWS = process.platform === 'win32';
+import { getSystemErrorMessage, getSystemErrorName, parseArgs as utilParseArgs } from 'node:util';
+import { printHelpAndExit, printVersionAndExit } from './cli-help.js';
+import { processInParallel } from './core/concurrency.js';
+import { cli } from './core/config.js';
+import { formatUnknownErrorMessage } from './core/errors.js';
+import { cliFmt, padEndVisible } from './core/fmt.js';
+import { getReservedDeviceNameForPath, isWindowsDriveRelativePath, normalizePath, } from './core/path-utils.js';
+import { PathGuard } from './core/path.js';
+import { IS_WINDOWS, isRecord, parseTrueEnvFlag } from './core/primitives.js';
+import { getMaxTextFileSize } from './core/util.js';
+import { registeredTools } from './tools/index.js';
 const CLI_VALIDATE_CONCURRENCY = 8;
+// ════════════════════════════════════════════════════════════
+// Path & Config Utilities — pure functions and error types
+// ════════════════════════════════════════════════════════════
 export class CliExitError extends Error {
     exitCode;
     constructor(message, exitCode) {
@@ -18,45 +24,25 @@ export class CliExitError extends Error {
 }
 function validateCliPath(inputPath) {
     if (inputPath.includes('\0')) {
-        throw new InvalidArgumentError('Path contains null bytes.');
+        throw new CliExitError('Path contains null bytes.', 1);
     }
     if (isWindowsDriveRelativePath(inputPath)) {
-        throw new InvalidArgumentError('Windows drive-relative paths are not allowed. Use C:\\path or C:/path instead of C:path.');
+        throw new CliExitError('Windows drive-relative paths are not allowed. Use C:\\path or C:/path instead of C:path.', 1);
     }
     const reserved = getReservedDeviceNameForPath(inputPath);
     if (reserved) {
-        throw new InvalidArgumentError(`Windows reserved device name not allowed: ${reserved}.`);
+        throw new CliExitError(`Windows reserved device name not allowed: ${reserved}.`, 1);
     }
 }
-function getNodeErrorProperty(error, key) {
+function getSystemErrorDetails(error) {
     if (!isRecord(error))
-        return undefined;
-    const value = error[key];
-    if (typeof value === 'string' || typeof value === 'number') {
-        return value;
-    }
-    return undefined;
-}
-function collectStringValues(values) {
-    const result = [];
-    for (const value of values) {
-        if (typeof value === 'string') {
-            result.push(value);
-        }
-    }
-    return result;
-}
-function getNodeErrorCode(error) {
-    const code = getNodeErrorProperty(error, 'code');
-    return typeof code === 'string' ? code : undefined;
-}
-function getNodeErrorErrno(error) {
-    const errno = getNodeErrorProperty(error, 'errno');
-    return typeof errno === 'number' ? errno : undefined;
+        return { code: undefined, errno: undefined };
+    const code = typeof error['code'] === 'string' ? error['code'] : undefined;
+    const errno = typeof error['errno'] === 'number' ? error['errno'] : undefined;
+    return { code, errno };
 }
 function normalizeDirectoryError(error, inputPath) {
-    const code = getNodeErrorCode(error);
-    const errno = getNodeErrorErrno(error);
+    const { code, errno } = getSystemErrorDetails(error);
     if (error instanceof Error && code === undefined && errno === undefined) {
         return error;
     }
@@ -67,8 +53,9 @@ function normalizeDirectoryError(error, inputPath) {
             return new Error(`Cannot access directory ${inputPath} (${name}: ${message})`);
         }
         catch {
-            // Fall through to best-effort formatting.
+            // Fall through, but preserve raw errno value
         }
+        return new Error(`Cannot access directory ${inputPath} (errno ${errno})`);
     }
     if (code) {
         return new Error(`Cannot access directory ${inputPath} (${code})`);
@@ -80,7 +67,7 @@ function assertDirectory(stats, inputPath) {
         return;
     throw new Error(`${inputPath} is not a directory`);
 }
-async function validateDirectoryPath(inputPath) {
+async function validateDirectoryPath(inputPath, allowMissing = false) {
     const normalized = normalizePath(inputPath);
     try {
         const stats = await stat(normalized);
@@ -88,77 +75,25 @@ async function validateDirectoryPath(inputPath) {
         return normalized;
     }
     catch (error) {
+        if (allowMissing) {
+            if (error instanceof Error && error.message.includes('is not a directory')) {
+                throw error;
+            }
+            return normalized;
+        }
         throw normalizeDirectoryError(error, inputPath);
     }
 }
-async function normalizeCliDirectories(args) {
-    const { results, errors } = await processInParallel([...args], validateDirectoryPath, CLI_VALIDATE_CONCURRENCY);
+async function normalizeAndValidateDirs(paths, allowMissing = false) {
+    const { results, errors } = await processInParallel([...paths], (p) => validateDirectoryPath(p, allowMissing), CLI_VALIDATE_CONCURRENCY);
     if (errors.length === 0) {
-        return results;
-    }
-    let first = errors[0];
-    for (const failure of errors) {
-        if (first && failure.index < first.index) {
-            first = failure;
-        }
+        return deduplicateAllowedDirectories(results.map((r) => r.value));
     }
-    throw first?.error ?? new Error('Failed to validate directories');
-}
-function parseAllowedDirArgument(value, previous) {
-    validateCliPath(value);
-    const values = Array.isArray(previous) ? collectStringValues(previous) : [];
-    return [...values, value];
-}
-function getParsedAllowedDirs(cli) {
-    const [allowedDirs] = cli.processedArgs;
-    if (!Array.isArray(allowedDirs))
-        return [];
-    return collectStringValues(allowedDirs);
-}
-function createCliProgram(output) {
-    const cli = new Command();
-    cli
-        .name('filesystem-mcp')
-        .usage('[options] [allowedDirs...]')
-        .description('MCP filesystem server. Positional directories define allowed access roots.')
-        .argument('[allowedDirs...]', 'Directories the MCP server can access on disk', parseAllowedDirArgument)
-        .option('--allow_cwd, --allow-cwd', 'Allow the current working directory as an additional root')
-        .option('--port <number>', 'Enable HTTP transport on the given port (Node Streamable HTTP)')
-        .helpOption('-h, --help', 'Display command help')
-        .version(SERVER_VERSION, '-v, --version', 'Display server version')
-        .addHelpText('after', `
-Examples:
-  $ filesystem-mcp /path/to/allowed/dir
-  $ filesystem-mcp --allow-cwd
-  $ filesystem-mcp /project/src /project/tests --allow-cwd
-  $ filesystem-mcp --port 3000 /path/to/allowed/dir
-`);
-    cli.allowUnknownOption(false);
-    cli.allowExcessArguments(false);
-    cli.showHelpAfterError('(run with --help for usage)');
-    cli.showSuggestionAfterError(true);
-    cli.exitOverride();
-    cli.configureOutput({
-        writeOut(text) {
-            output.push(text);
-        },
-        writeErr(text) {
-            output.push(text);
-        },
-        outputError(text, write) {
-            write(text);
-        },
-    });
-    return cli;
-}
-function formatCliOutput(output, fallback) {
-    const joined = output.join('').trimEnd();
-    if (joined.length > 0)
-        return joined;
-    return fallback.trimEnd();
+    const first = errors.reduce((prev, curr) => (curr.index < prev.index ? curr : prev));
+    throw first.error;
 }
 function normalizeCliExitMessage(error) {
-    const rawMessage = error instanceof Error ? error.message : String(error);
+    const rawMessage = formatUnknownErrorMessage(error);
     return rawMessage.startsWith('Error:') ? rawMessage : `Error: ${rawMessage}`;
 }
 function deduplicateAllowedDirectories(dirs) {
@@ -174,38 +109,148 @@ function deduplicateAllowedDirectories(dirs) {
     return deduplicated;
 }
 function parsePortOption(raw) {
-    if (raw === undefined)
+    // '' reads as unset: FS_PORT set-but-empty (compose templating) means stdio.
+    if (raw === undefined || raw === '')
         return undefined;
     const n = Number(raw);
     if (!Number.isInteger(n) || n < 1 || n > 65535) {
-        throw new CliExitError(`Error: --port must be an integer between 1 and 65535`, 1);
+        throw new CliExitError(`Error: --port / FS_PORT must be an integer between 1 and 65535`, 1);
     }
     return n;
 }
+const CLI_PARSER_CONFIG = {
+    options: {
+        'allow-cwd': { type: 'boolean', default: false },
+        'read-only': { type: 'boolean', default: false },
+        safe: { type: 'boolean', default: false },
+        'print-config': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        port: { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+        'log-level': { type: 'string' },
+        'http-host': { type: 'string' },
+        'api-key': { type: 'string' },
+        'allow-sensitive': { type: 'boolean', default: false },
+        'root-boundary': { type: 'string' },
+        'max-file-size': { type: 'string' },
+        'walk-cwd': { type: 'boolean', default: false },
+        deny: { type: 'string', multiple: true },
+        'allow-missing-roots': { type: 'boolean', default: false },
+    },
+    strict: true,
+    allowPositionals: true,
+};
 export async function parseArgs() {
-    const output = [];
-    const cli = createCliProgram(output);
     try {
-        cli.parse(process.argv, { from: 'node' });
+        const parsed = utilParseArgs(CLI_PARSER_CONFIG);
+        if (parsed.values.help) {
+            printHelpAndExit();
+        }
+        if (parsed.values.version) {
+            printVersionAndExit();
+        }
+        for (const positional of parsed.positionals) {
+            validateCliPath(positional);
+        }
+        const vals = parsed.values;
+        // `--http-host` and `--api-key` are returned to the caller and handed to
+        // the server as config. Every other flag lands in the CLI-override store
+        // (core/config.ts) — the one owner of the flag-beats-env rule — which deep
+        // core readers (path, sensitive, observability, util) consult before
+        // falling back to the operator's environment. Nothing writes process.env.
+        const httpHost = typeof vals['http-host'] === 'string' ? vals['http-host'] : process.env['FS_HTTP_HOST'];
+        const apiKey = typeof vals['api-key'] === 'string' ? vals['api-key'] : process.env['FS_API_KEY'];
+        if (typeof vals['log-level'] === 'string')
+            cli.logLevel = vals['log-level'];
+        if (typeof vals['max-file-size'] === 'string')
+            cli.maxFileSize = vals['max-file-size'];
+        if (typeof vals['root-boundary'] === 'string')
+            cli.rootBoundary = vals['root-boundary'];
+        if (vals['allow-sensitive'] === true)
+            cli.allowSensitive = true;
+        if (vals['walk-cwd'] === true)
+            cli.allowCwdWalk = true;
+        if (vals['allow-missing-roots'] === true)
+            cli.allowMissingRoots = true;
+        if (Array.isArray(vals['deny'])) {
+            const denyPatterns = vals['deny']
+                .filter((entry) => typeof entry === 'string')
+                .map((entry) => entry.trim())
+                .filter(Boolean);
+            if (denyPatterns.length > 0)
+                cli.denyPatterns = [...new Set(denyPatterns)];
+        }
+        const allowCwd = vals['allow-cwd'] ||
+            vals['walk-cwd'] ||
+            parseTrueEnvFlag(process.env['FS_ALLOW_CWD_WALK'], 'FS_ALLOW_CWD_WALK');
+        const readOnly = vals['read-only'] || vals['safe'];
+        const printConfig = vals['print-config'];
+        const json = vals['json'];
+        const port = parsePortOption(parsed.values.port ?? process.env['FS_PORT']);
+        const allowMissingRoots = vals['allow-missing-roots'] ||
+            parseTrueEnvFlag(process.env['FS_ALLOW_MISSING_ROOTS'], 'FS_ALLOW_MISSING_ROOTS');
+        let allowedDirs = [];
+        try {
+            allowedDirs =
+                parsed.positionals.length > 0
+                    ? await normalizeAndValidateDirs(parsed.positionals, allowMissingRoots)
+                    : [];
+        }
+        catch (error) {
+            throw new CliExitError(normalizeCliExitMessage(error), 1);
+        }
+        return {
+            allowedDirs,
+            allowCwd,
+            port,
+            readOnly,
+            printConfig,
+            json,
+            httpHost,
+            apiKey,
+        };
     }
     catch (error) {
-        if (error instanceof CommanderError) {
-            throw new CliExitError(formatCliOutput(output, error.message), error.exitCode);
+        if (error instanceof CliExitError) {
+            throw error;
         }
-        throw error;
+        throw new CliExitError(normalizeCliExitMessage(error), 1);
     }
-    const options = cli.opts();
-    const allowCwd = Boolean(options.allowCwd);
-    const port = parsePortOption(options.port);
-    const positionals = getParsedAllowedDirs(cli);
-    let allowedDirs;
-    try {
-        allowedDirs =
-            positionals.length > 0 ? await normalizeCliDirectories(positionals) : [];
+}
+export async function runPrintConfig(options) {
+    const write = options.stdout ?? ((s) => process.stdout.write(s));
+    const pathGuard = new PathGuard({
+        allowCwd: options.allowCwd,
+        cliAllowedDirs: options.allowedDirs,
+    });
+    await pathGuard.recomputeAllowedDirectories();
+    const allowedRoots = pathGuard.getAllowedDirectories();
+    const tools = registeredTools(options.readOnly).map((t) => t.name);
+    // Derived, never assumed: `--print-config --port 3000` reports the HTTP bind
+    // that `--port` would actually have started, not the stdio default.
+    const config = {
+        transport: options.port !== undefined
+            ? `http://${options.httpHost ?? '127.0.0.1'}:${String(options.port)}`
+            : 'stdio',
+        readOnly: options.readOnly,
+        allowedRoots,
+        tools,
+        apiKey: options.apiKey ? '***' : null,
+        limits: { maxFileSizeBytes: getMaxTextFileSize() },
+    };
+    if (options.json) {
+        write(JSON.stringify(config, null, 2));
     }
-    catch (error) {
-        throw new CliExitError(normalizeCliExitMessage(error), 1);
+    else {
+        const key = (k) => padEndVisible(cliFmt.cyan(k), 14);
+        write(`${key('transport:')}${config.transport}\n`);
+        write(`${key('readOnly:')}${cliFmt.bool(config.readOnly)}\n`);
+        write(`${key('apiKey:')}${cliFmt.dim(config.apiKey ?? 'none')}\n`);
+        write(`${key('allowedRoots:')}${config.allowedRoots.join(', ') || cliFmt.dim('(none)')}\n`);
+        write(`${key('tools:')}${cliFmt.dim(config.tools.join(', '))}\n`);
+        write(`${key('maxFileSize:')}${cliFmt.yellow(String(config.limits.maxFileSizeBytes))}\n`);
     }
-    const deduplicatedDirs = deduplicateAllowedDirectories(allowedDirs);
-    return { allowedDirs: deduplicatedDirs, allowCwd, port };
+    return config;
 }
+//# sourceMappingURL=cli.js.map