@j0hanz/filesystem-mcp 1.2.2 → 1.2.4

package/README.md

@@ -493,6 +493,13 @@ The server declares full task capabilities (`tasks/list`, `tasks/cancel`). The f
 
 Include `_meta.progressToken` in a `tools/call` request to receive `notifications/progress` updates. Use `tools/call` with a `task` field to invoke as a background task, then poll `tasks/get` and retrieve output via `tasks/result`.
 
+Task status notifications (`notifications/tasks/status`) are best-effort and emitted only when the transport/runtime provides a notification sender.
+
+Cancellation semantics:
+
+- `tasks/cancel` is the canonical cancellation API.
+- Clients should treat `E_CANCELLED` as cancellation even if a transport/client surfaces a terminal failure shape.
+
 ## Configuration
 
 ### CLI
@@ -535,6 +542,10 @@ Directories are resolved from three sources, merged at runtime:
 > [!TIP]
 > If no directories are configured at startup and the connected client does not supply MCP Roots, all tool calls will fail. Pass at least one directory argument or use `--allow-cwd`.
 
+### Compatibility
+
+Set `FS_CONTEXT_STRIP_STRUCTURED=1` to strip `structuredContent` from tool results and `outputSchema` from tool definitions for compatibility with clients that only consume text content.
+
 ## Security
 
 - **Path validation**: All operations use `isPathWithinDirectories` to prevent path traversal attacks.

package/dist/cli.d.ts

@@ -5,4 +5,5 @@ export declare class CliExitError extends Error {
 export declare function parseArgs(): Promise<{
     allowedDirs: string[];
     allowCwd: boolean;
+    port: number | undefined;
 }>;

package/dist/cli.js

@@ -1,13 +1,11 @@
 import * as fs from 'node:fs/promises';
 import { getSystemErrorMessage, getSystemErrorName } from 'node:util';
-import { z } from 'zod';
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
-import packageJsonRaw from '../package.json' with { type: 'json' };
 import { processInParallel } from './lib/fs-helpers.js';
 import { getReservedDeviceNameForPath, isWindowsDriveRelativePath, normalizePath, } from './lib/path-validation.js';
 import { isRecord } from './lib/type-guards.js';
-const PackageJsonSchema = z.object({ version: z.string() });
-const { version: SERVER_VERSION } = PackageJsonSchema.parse(packageJsonRaw);
+import { pkgInfo } from './pkg-info.js';
+const { version: SERVER_VERSION } = pkgInfo;
 const IS_WINDOWS = process.platform === 'win32';
 const CLI_VALIDATE_CONCURRENCY = 8;
 export class CliExitError extends Error {
@@ -125,6 +123,7 @@ function createCliProgram(output) {
         .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 (MCP Streamable HTTP with SSE)')
         .helpOption('-h, --help', 'Display command help')
         .version(SERVER_VERSION, '-v, --version', 'Display server version')
         .addHelpText('after', `
@@ -132,6 +131,7 @@ 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);
@@ -173,6 +173,15 @@ function deduplicateAllowedDirectories(dirs) {
     }
     return deduplicated;
 }
+function parsePortOption(raw) {
+    if (raw === undefined)
+        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);
+    }
+    return n;
+}
 export async function parseArgs() {
     const output = [];
     const cli = createCliProgram(output);
@@ -187,6 +196,7 @@ export async function parseArgs() {
     }
     const options = cli.opts();
     const allowCwd = options.allowCwd === true;
+    const port = parsePortOption(options.port);
     const positionals = getParsedAllowedDirs(cli);
     let allowedDirs;
     try {
@@ -197,5 +207,5 @@ export async function parseArgs() {
         throw new CliExitError(normalizeCliExitMessage(error), 1);
     }
     const deduplicatedDirs = deduplicateAllowedDirectories(allowedDirs);
-    return { allowedDirs: deduplicatedDirs, allowCwd };
+    return { allowedDirs: deduplicatedDirs, allowCwd, port };
 }

package/dist/completions.js

@@ -195,7 +195,17 @@ async function toAllowedContextDirectory(resolved, allowed) {
     return isPathWithinDirectories(parent, allowed) ? parent : undefined;
 }
 async function resolveContextBaseDirectory(argumentName, contextArguments, allowed) {
-    if (!contextArguments || Object.keys(contextArguments).length === 0) {
+    if (!contextArguments) {
+        return undefined;
+    }
+    let hasContextArgument = false;
+    for (const key in contextArguments) {
+        if (!Object.prototype.hasOwnProperty.call(contextArguments, key))
+            continue;
+        hasContextArgument = true;
+        break;
+    }
+    if (!hasContextArgument) {
         return undefined;
     }
     const keys = chooseContextKeys(argumentName);
@@ -277,10 +287,11 @@ function findRootPrefixMatches(currentValue, allowed) {
 function findMatchingRoots(searchDir, prefix, allowed) {
     const matches = [];
     const lowerPrefix = prefix.toLowerCase();
+    const normalizedSearchDir = normalizePath(searchDir);
     for (const root of allowed) {
         const rootDir = path.dirname(root);
         // Check if root is a direct child of searchDir
-        if (normalizePath(rootDir) === searchDir) {
+        if (normalizePath(rootDir) === normalizedSearchDir) {
             const rootName = path.basename(root);
             if (rootName.toLowerCase().startsWith(lowerPrefix)) {
                 matches.push(`${root}${path.sep}`);
@@ -312,10 +323,8 @@ export async function getPathCompletions(currentValue, options = {}) {
             };
         }
         const { searchDir, prefix } = context;
-        const [dirMatches, rootMatches] = await Promise.all([
-            findMatchesInDirectory(searchDir, prefix, allowed),
-            Promise.resolve(findMatchingRoots(searchDir, prefix, allowed)),
-        ]);
+        const dirMatches = await findMatchesInDirectory(searchDir, prefix, allowed);
+        const rootMatches = findMatchingRoots(searchDir, prefix, allowed);
         // Deduplicate and sort
         const unique = new Set();
         for (const match of dirMatches)

package/dist/index.js

@@ -5,9 +5,10 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from './lib/constants.js';
 import { formatUnknownErrorMessage } from './lib/errors.js';
 import { createTimedAbortSignal } from './lib/fs-helpers.js';
 import { setAllowedDirectoriesResolved } from './lib/path-validation.js';
-import { createServer, startServer } from './server.js';
+import { createServer, startHttpServer, startServer } from './server.js';
 const SHUTDOWN_TIMEOUT_MS = 5000;
 let activeServer;
+let activeHttpServer;
 let shutdownStarted = false;
 function isStdinEvent(event) {
     return event === 'end' || event === 'close';
@@ -31,6 +32,14 @@ async function shutdown(reason, exitCode = 0) {
     }, SHUTDOWN_TIMEOUT_MS);
     timer.unref();
     try {
+        if (activeHttpServer) {
+            const server = activeHttpServer;
+            await new Promise((resolve) => {
+                server.close(() => {
+                    resolve();
+                });
+            });
+        }
         if (activeServer) {
             await activeServer.close();
         }
@@ -48,9 +57,10 @@ async function shutdown(reason, exitCode = 0) {
 async function main() {
     let allowedDirs;
     let allowCwd;
+    let port;
     try {
         const parsed = await parseArgs();
-        ({ allowedDirs, allowCwd } = parsed);
+        ({ allowedDirs, allowCwd, port } = parsed);
     }
     catch (error) {
         if (error instanceof CliExitError) {
@@ -78,12 +88,20 @@ async function main() {
     else {
         console.error(`No directories specified via CLI. Will use MCP Roots${allowCwd ? ' or current working directory' : ''}.`);
     }
-    const server = await createServer({
-        allowCwd,
-        cliAllowedDirs: allowedDirs,
-    });
-    activeServer = server;
-    await startServer(server);
+    if (port !== undefined) {
+        activeHttpServer = await startHttpServer(port, {
+            allowCwd,
+            cliAllowedDirs: allowedDirs,
+        });
+    }
+    else {
+        const server = await createServer({
+            allowCwd,
+            cliAllowedDirs: allowedDirs,
+        });
+        activeServer = server;
+        await startServer(server);
+    }
 }
 registerShutdownTrigger('SIGTERM');
 registerShutdownTrigger('SIGINT');

package/dist/lib/file-operations/glob-engine.js

@@ -237,15 +237,9 @@ async function* processIterable(iterable, context) {
     const flush = async function* () {
         if (buffer.length === 0)
             return;
-        const batchSize = buffer.length;
-        const requests = new Array(batchSize);
-        for (let index = 0; index < batchSize; index += 1) {
-            const match = buffer[index];
-            if (match === undefined) {
-                requests[index] = Promise.resolve(null);
-                continue;
-            }
-            requests[index] = resolveStringMatch(match, cwd, maxDepth, seen, onlyFiles, followSymlinks, returnStats, suppressErrors);
+        const requests = [];
+        for (const match of buffer) {
+            requests.push(resolveStringMatch(match, cwd, maxDepth, seen, onlyFiles, followSymlinks, returnStats, suppressErrors));
         }
         buffer.length = 0;
         const results = await Promise.all(requests);

package/dist/lib/file-operations/read-multiple-files.js

@@ -109,16 +109,11 @@ async function validateBatch(tasks, signal) {
     }
     return infos;
 }
-async function applyBudgetForRange(options) {
-    const { batchStart, batchEnd, filePaths, totalFiles, maxTotalSize, maxSize, validated, skippedBudget, signal, totalSize: startingTotalSize, } = options;
+function applyBudgetForRange(options) {
+    const { batchStart, batchEnd, totalFiles, maxTotalSize, maxSize, validated, skippedBudget, totalSize: startingTotalSize, } = options;
     let totalSize = startingTotalSize;
     for (let index = batchStart; index < batchEnd; index += 1) {
-        const filePath = filePaths[index];
-        if (!filePath)
-            continue;
-        const cached = validated.get(index);
-        const info = cached ??
-            (await resolveValidatedInfo(filePath, index, validated, signal));
+        const info = validated.get(index);
         if (!info)
             continue;
         const { exceeded, totalSize: nextTotalSize } = applyBudget(totalSize, estimateReadSize(info.stats, maxSize), maxTotalSize, index, totalFiles, skippedBudget);
@@ -149,17 +144,15 @@ async function collectFileBudget(filePaths, maxTotalSize, maxSize, signal) {
         for (const [index, info] of batchInfos) {
             validated.set(index, info);
         }
-        const budgetResult = await applyBudgetForRange({
+        const budgetResult = applyBudgetForRange({
             batchStart,
             batchEnd,
-            filePaths,
             totalFiles,
             maxTotalSize,
             maxSize,
             validated,
             skippedBudget,
             totalSize,
-            ...(signal ? { signal } : {}),
         });
         const { exceeded, totalSize: nextTotalSize } = budgetResult;
         if (exceeded) {
@@ -169,18 +162,6 @@ async function collectFileBudget(filePaths, maxTotalSize, maxSize, signal) {
     }
     return { skippedBudget, validated };
 }
-async function resolveValidatedInfo(filePath, index, validated, signal) {
-    const existing = validated.get(index);
-    if (existing) {
-        return existing;
-    }
-    const info = await tryValidateFile(filePath, index, signal);
-    if (info) {
-        validated.set(index, info);
-        return info;
-    }
-    return undefined;
-}
 function buildOutput(filePaths) {
     const output = new Array(filePaths.length);
     for (let index = 0; index < filePaths.length; index += 1) {

package/dist/lib/file-operations/search-content.js

@@ -170,24 +170,21 @@ class ContextBuffer {
     snapshotBefore() {
         if (this.size === 0)
             return [];
-        const result = [];
+        const result = new Array(this.size);
         if (this.size < this.capacity) {
             for (let i = 0; i < this.size; i++) {
-                const item = this.buffer[i];
-                if (item !== undefined)
-                    result.push(item);
+                result[i] = this.buffer[i] ?? '';
             }
             return result;
         }
+        let outIndex = 0;
         for (let i = this.head; i < this.capacity; i++) {
-            const item = this.buffer[i];
-            if (item !== undefined)
-                result.push(item);
+            result[outIndex] = this.buffer[i] ?? '';
+            outIndex++;
         }
         for (let i = 0; i < this.head; i++) {
-            const item = this.buffer[i];
-            if (item !== undefined)
-                result.push(item);
+            result[outIndex] = this.buffer[i] ?? '';
+            outIndex++;
         }
         return result;
     }
@@ -218,17 +215,13 @@ async function readMatches(handle, requestedPath, matcher, options, maxMatches,
             if (isCancelled())
                 break;
             const matchCount = matcher(rawLine);
-            let content;
-            const getContent = () => {
-                content ??= trimContent(rawLine);
-                return content;
-            };
+            const trimmedLine = hasContext || matchCount > 0 ? trimContent(rawLine) : '';
             if (matchCount > 0) {
                 if (ctx) {
                     matches.push({
                         file: requestedPath,
                         line: lineNumber,
-                        content: getContent(),
+                        content: trimmedLine,
                         matchCount,
                         contextBefore: ctx.snapshotBefore(),
                         contextAfter: ctx.scheduleAfter(),
@@ -238,13 +231,13 @@ async function readMatches(handle, requestedPath, matcher, options, maxMatches,
                     matches.push({
                         file: requestedPath,
                         line: lineNumber,
-                        content: getContent(),
+                        content: trimmedLine,
                         matchCount,
                     });
                 }
             }
             if (ctx) {
-                ctx.add(getContent());
+                ctx.add(trimmedLine);
             }
             lineNumber++;
         }

package/dist/lib/observability.js

@@ -103,7 +103,7 @@ function extractResultError(structured) {
         ? err['message']
         : undefined;
 }
-function normalizePath(path) {
+function sanitizePathForDiagnostics(path) {
     const { detail } = readConfig();
     if (!path || detail === 0)
         return undefined;
@@ -119,7 +119,7 @@ function enrichWithToolContext(detail) {
     if (!Object.hasOwn(merged, 'tool')) {
         merged.tool = current.tool;
     }
-    const normalizedPath = normalizePath(current.path);
+    const normalizedPath = sanitizePathForDiagnostics(current.path);
     if (normalizedPath && !Object.hasOwn(merged, 'path')) {
         merged.path = normalizedPath;
     }
@@ -207,7 +207,7 @@ export function getToolContextSnapshot() {
 function normalizeContext(ctx) {
     if (!ctx.path)
         return ctx;
-    const normalized = normalizePath(ctx.path);
+    const normalized = sanitizePathForDiagnostics(ctx.path);
     if (!normalized) {
         const copy = { ...ctx };
         delete copy.path;
@@ -318,7 +318,7 @@ async function runAndObserve(tool, run, pubTool, pubPerf, logErrors, pathVal) {
 }
 export async function withToolDiagnostics(tool, run, options) {
     const config = readConfig();
-    const normalizedPath = normalizePath(options?.path);
+    const normalizedPath = sanitizePathForDiagnostics(options?.path);
     const context = {
         tool,
         ...(options?.path ? { path: options.path } : {}),

package/dist/lib/path-validation.js

@@ -433,15 +433,28 @@ async function resolveRootDirectory(root, signal) {
     }
 }
 export async function getValidRootDirectories(roots, signal) {
+    const fileRoots = roots.filter(isFileRoot);
+    if (fileRoots.length === 0)
+        return [];
+    // Phase 1: Resolve all roots in parallel (order-preserving via index).
+    const resolvedResults = await Promise.all(fileRoots.map((root) => resolveRootDirectory(root, signal)));
+    const validPaths = resolvedResults.filter((p) => p !== null);
+    if (validPaths.length === 0)
+        return [];
+    // Phase 2: Expand real paths for each valid directory in parallel.
+    const realExpansions = await Promise.all(validPaths.map(async (normalizedPath) => {
+        const extra = [];
+        await maybeAddRealPath(normalizedPath, extra, signal);
+        return extra[0] ?? null;
+    }));
+    // Build output preserving insertion order: [normalizedPath, realPath?] per root.
     const validDirs = [];
-    for (const root of roots) {
-        if (!isFileRoot(root))
-            continue;
-        const normalizedPath = await resolveRootDirectory(root, signal);
-        if (!normalizedPath)
-            continue;
-        validDirs.push(normalizedPath);
-        await maybeAddRealPath(normalizedPath, validDirs, signal);
-    }
+    validPaths.forEach((p, i) => {
+        validDirs.push(p);
+        const expanded = realExpansions[i];
+        if (expanded !== null && expanded !== undefined) {
+            validDirs.push(expanded);
+        }
+    });
     return validDirs;
 }

package/dist/pkg-info.d.ts

@@ -0,0 +1,6 @@
+export declare const pkgInfo: {
+    name: string;
+    version: string;
+    description?: string | undefined;
+    homepage?: string | undefined;
+};

package/dist/pkg-info.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import packageJsonRaw from '../package.json' with { type: 'json' };
+const PkgInfoSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+    description: z.string().optional(),
+    homepage: z.string().optional(),
+});
+export const pkgInfo = PkgInfoSchema.parse(packageJsonRaw);