@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/tools/stat.js

@@ -1,67 +1,207 @@
-import { basename } from 'node:path';
-import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
-import { ErrorCode } from '../lib/errors.js';
-import { getFileInfo } from '../lib/file-operations/metadata.js';
-import { formatBytes, joinLines } from '../config.js';
-import { GetFileInfoInputSchema, GetFileInfoOutputSchema } from '../schemas.js';
-import { FILE_READ_ICONS } from './icons.js';
-import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, } from './shared.js';
-import { registerStandardTool } from './task-support.js';
-export const GET_FILE_INFO_TOOL = {
-    name: 'stat',
-    title: 'Get File Info',
-    description: 'Get file/directory metadata: size, modified, permissions, mime, tokenEstimate. ' +
-        'Use `tokenEstimate` (size\u00f74) to pre-screen token cost before reading.',
-    inputSchema: GetFileInfoInputSchema,
-    outputSchema: GetFileInfoOutputSchema,
-    annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    icons: FILE_READ_ICONS,
-    taskSupport: 'forbidden',
-};
-function formatFileInfoDetails(info) {
-    const lines = [
-        `${info.name} (${info.type})`,
-        `  Path: ${info.path}`,
-        `  Size: ${formatBytes(info.size)}`,
-        `  Modified: ${info.modified.toISOString()}`,
-    ];
-    if (info.mimeType)
-        lines.push(`  Type: ${info.mimeType}`);
-    if (info.symlinkTarget)
-        lines.push(`  Target: ${info.symlinkTarget}`);
-    return joinLines(lines);
+import { parse } from 'node:path';
+import * as z from 'zod/v4';
+import { ErrorCode, rethrowIfAborted } from '../core/errors.js';
+import { formatBytes } from '../core/fmt.js';
+import { getFileType, isHidden } from '../core/fs.js';
+import { detectMimeType } from '../core/mime.js';
+import { FileInfoSchema, NonNegInt, OperationSummarySchema, PerFileErrorSchema, singleOrBatchAccessPaths, singleOrBatchPathsInput, } from '../core/schema.js';
+import { putJsonResource } from '../core/store.js';
+import { DEFAULT_SEARCH_TIMEOUT_MS } from '../core/util.js';
+import { runOverPaths } from './batch.js';
+import { defineTool } from './define.js';
+const StatInputSchema = singleOrBatchPathsInput({ extra: {} });
+const StatPerPathSchema = z.strictObject({
+    path: z.string().describe('Requested path'),
+    value: FileInfoSchema.optional().describe('File metadata; present on success'),
+    error: PerFileErrorSchema.optional().describe('Error details; present on failure'),
+});
+const StatOutputSchema = z.strictObject({
+    results: z
+        .array(StatPerPathSchema)
+        .describe('Per-path metadata results ordered to match the input paths'),
+    summary: OperationSummarySchema,
+    fileCount: NonNegInt.optional().describe('Number of regular files in the results'),
+    dirCount: NonNegInt.optional().describe('Number of directories in the results'),
+    resourceUri: z
+        .string()
+        .optional()
+        .describe('URI to aggregated stats.json in the resource store (present when resource store is available)'),
+});
+function getPermissions(mode) {
+    let out = '';
+    for (const shift of [6, 3, 0]) {
+        const bits = (mode >> shift) & 0b111;
+        out += (bits & 0b100 ? 'r' : '-') + (bits & 0b010 ? 'w' : '-') + (bits & 0b001 ? 'x' : '-');
+    }
+    return out;
 }
-async function handleGetFileInfo(args, signal) {
-    const info = await getFileInfo(args.path, {
-        includeMimeType: true,
-        ...(signal ? { signal } : {}),
-    });
-    const structured = {
-        ok: true,
-        info: buildFileInfoPayload(info),
+function buildFileInfoResult(name, requestedPath, isSymlink, stats, mimeType, symlinkTarget) {
+    const tokenEstimate = stats.isFile() ? Math.ceil(stats.size / 4) : undefined;
+    return {
+        name,
+        path: requestedPath,
+        type: isSymlink ? 'symlink' : getFileType(stats),
+        size: stats.size,
+        ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),
+        created: stats.birthtime,
+        modified: stats.mtime,
+        accessed: stats.atime,
+        permissions: getPermissions(stats.mode),
+        isHidden: isHidden(name),
+        ...(mimeType !== undefined ? { mimeType } : {}),
+        ...(symlinkTarget !== undefined ? { symlinkTarget } : {}),
     };
-    return buildToolResponse(formatFileInfoDetails(info), structured);
 }
-export function registerGetFileInfoTool(server, options = {}) {
-    const handler = (args, ctx) => executeToolWithDiagnostics({
-        toolName: 'stat',
-        ctx,
-        outputSchema: GetFileInfoOutputSchema,
-        timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
-        context: { path: args.path },
-        run: (signal) => handleGetFileInfo(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FOUND, args.path),
-    });
-    registerStandardTool(server, GET_FILE_INFO_TOOL, handler, options, {
-        progressMessage: (args) => `${GET_FILE_INFO_TOOL.title}: ${basename(args.path)}`,
-        completionMessage: (args, result) => {
-            const name = basename(args.path);
-            if (result.isError)
-                return `${GET_FILE_INFO_TOOL.title}: ${name} • ${result.errorCode}`;
-            const sc = result.structuredContent;
-            if (!sc.info)
-                return `${GET_FILE_INFO_TOOL.title}: ${name} • failed`;
-            return `${GET_FILE_INFO_TOOL.title}: ${sc.info.name} • ${formatBytes(sc.info.size)}`;
+async function getSymlinkTarget(pathToRead, fs, signal, log) {
+    signal?.throwIfAborted();
+    try {
+        const { linkString } = await fs.readlink(pathToRead);
+        return linkString;
+    }
+    catch (error) {
+        rethrowIfAborted(error);
+        log?.('warning', `stat: readlink failed for "${pathToRead}": ${String(error)}`, 'stat');
+        return undefined;
+    }
+}
+async function getFileInfo(filePath, options) {
+    const { signal, fs, log } = options;
+    signal?.throwIfAborted();
+    const { requestedPath, isSymlink, stats: followedStats, } = await fs.statDetailed(filePath, signal ? { signal } : undefined);
+    const { base: name, ext: rawExt } = parse(requestedPath);
+    const includeMimeType = options.includeMimeType !== false;
+    const mimeType = includeMimeType && rawExt.length > 0 ? detectMimeType(requestedPath).mimeType : undefined;
+    // For a symlink, fsStat follows the link and reports the target's metadata.
+    // Report the link's own metadata instead so size/permissions/timestamps
+    // describe the link the user asked about, not its target.
+    let stats = followedStats;
+    if (isSymlink) {
+        try {
+            ({ stats } = await fs.lstat(requestedPath, signal ? { signal } : undefined));
+        }
+        catch (error) {
+            // A cancelled request is not a "link metadata unavailable" fallback.
+            rethrowIfAborted(error);
+            // Guarded lstat can be refused where raw lstat succeeded (e.g. an allowed
+            // root that is itself a symlink, whose parent sits outside the roots).
+            // Falling back to the followed stats degrades the report to the target's
+            // metadata, so leave a trace instead of degrading silently.
+            log?.('warning', `stat: lstat failed for "${requestedPath}": ${String(error)}`, 'stat');
+            stats = followedStats;
+        }
+    }
+    // isSymlink above is true whenever ANY ancestor is a symlink, because it
+    // compares the requested path with its fully-resolved real path. Only the
+    // entry's own lstat says whether THIS path is a link, so a regular file under
+    // a symlinked parent is reported as a file and no readlink is attempted.
+    const isOwnSymlink = stats.isSymbolicLink();
+    const symlinkTarget = isOwnSymlink
+        ? await getSymlinkTarget(requestedPath, fs, signal, log)
+        : undefined;
+    return buildFileInfoResult(name, requestedPath, isOwnSymlink, stats, mimeType, symlinkTarget);
+}
+function classifyTypeCounts(results) {
+    let fileCount = 0;
+    let dirCount = 0;
+    for (const result of results) {
+        if ('error' in result)
+            continue;
+        if (result.value.type === 'directory')
+            dirCount += 1;
+        else
+            fileCount += 1;
+    }
+    return { fileCount, dirCount };
+}
+function toStatPerPathPayload(r) {
+    if ('error' in r) {
+        return { path: r.path, error: r.error };
+    }
+    const info = r.value;
+    return {
+        path: r.path,
+        value: {
+            name: info.name,
+            path: info.path,
+            type: info.type,
+            size: info.size,
+            ...(info.tokenEstimate !== undefined ? { tokenEstimate: info.tokenEstimate } : {}),
+            created: info.created.toISOString(),
+            modified: info.modified.toISOString(),
+            accessed: info.accessed.toISOString(),
+            permissions: info.permissions,
+            isHidden: info.isHidden,
+            ...(info.mimeType !== undefined ? { mimeType: info.mimeType } : {}),
+            ...(info.symlinkTarget !== undefined ? { symlinkTarget: info.symlinkTarget } : {}),
         },
-    });
+    };
 }
+export const GET_FILE_INFO = defineTool({
+    name: 'stat',
+    title: 'Get File Info',
+    description: 'Get metadata for one or more files or directories: size, type, permissions, MIME type, timestamps, and tokenEstimate. ' +
+        'Use tokenEstimate to pre-screen read cost before calling read. ' +
+        'Single path: pass path. Batch mode: pass paths[].',
+    input: StatInputSchema,
+    output: StatOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+    timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS,
+    defaultErrorCode: ErrorCode.NOT_FOUND,
+    progress: (args) => {
+        if (args.paths !== undefined) {
+            return { label: 'Stat', subject: `${String(args.paths.length)} paths` };
+        }
+        return { label: 'Stat', subject: args.path ?? '' };
+    },
+    accessPaths: singleOrBatchAccessPaths,
+    run: async (args, ctx) => {
+        const batchInput = args.path !== undefined ? { path: args.path } : { paths: args.paths ?? [] };
+        const batch = await runOverPaths(batchInput, ctx, async ({ path }) => getFileInfo(path, {
+            includeMimeType: true,
+            fs: ctx.fs,
+            signal: ctx.signal,
+            log: ctx.log,
+        }), { defaultErrorCode: ErrorCode.NOT_FOUND });
+        const { fileCount, dirCount } = classifyTypeCounts(batch.results);
+        const perPathPayload = batch.results.map(toStatPerPathPayload);
+        let resourceUri;
+        const resources = [];
+        if (ctx.resourceStore && batch.summary.total > 1) {
+            const { entry, link } = putJsonResource(ctx.resourceStore, `${String(batch.summary.total)} paths`, perPathPayload);
+            resourceUri = entry.uri;
+            resources.push(link);
+        }
+        const text = perPathPayload
+            .map((r) => {
+            if (r.value) {
+                const { name, type, size } = r.value;
+                // A directory's own inode size says nothing about what is inside it
+                // (0 on Windows, 4096 on ext4), and "directory, 0 B" reads as empty.
+                // Use `list` for contents; report the byte size only where it means
+                // something.
+                if (type === 'directory')
+                    return `${name}: directory`;
+                return `${name}: ${type}, ${formatBytes(size)}`;
+            }
+            return `${r.path}: ${r.error?.message ?? 'error'}`;
+        })
+            .join('\n');
+        return {
+            structured: {
+                results: perPathPayload,
+                summary: batch.summary,
+                fileCount,
+                dirCount,
+                ...(resourceUri ? { resourceUri } : {}),
+            },
+            text,
+            ...(resources.length > 0 ? { resources } : {}),
+        };
+    },
+});
+//# sourceMappingURL=stat.js.map

package/dist/tools/stat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat.js","sourceRoot":"","sources":["../../src/tools/stat.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { parse } from 'node:path';\n\nimport * as z from 'zod/v4';\n\nimport { ErrorCode, rethrowIfAborted } from '../core/errors.js';\nimport { formatBytes } from '../core/fmt.js';\nimport type { FileInfo, GuardedFileSystem, Stats } from '../core/fs.js';\nimport { getFileType, isHidden } from '../core/fs.js';\nimport { detectMimeType } from '../core/mime.js';\nimport {\n  FileInfoSchema,\n  NonNegInt,\n  OperationSummarySchema,\n  PerFileErrorSchema,\n  singleOrBatchAccessPaths,\n  singleOrBatchPathsInput,\n} from '../core/schema.js';\nimport { putJsonResource } from '../core/store.js';\nimport { DEFAULT_SEARCH_TIMEOUT_MS } from '../core/util.js';\nimport type { PerPathResult } from './batch.js';\nimport { runOverPaths } from './batch.js';\nimport type { ToolCtx } from './define.js';\nimport { defineTool } from './define.js';\n\nconst StatInputSchema = singleOrBatchPathsInput({ extra: {} });\n\nconst StatPerPathSchema = z.strictObject({\n  path: z.string().describe('Requested path'),\n  value: FileInfoSchema.optional().describe('File metadata; present on success'),\n  error: PerFileErrorSchema.optional().describe('Error details; present on failure'),\n});\n\nconst StatOutputSchema = z.strictObject({\n  results: z\n    .array(StatPerPathSchema)\n    .describe('Per-path metadata results ordered to match the input paths'),\n  summary: OperationSummarySchema,\n  fileCount: NonNegInt.optional().describe('Number of regular files in the results'),\n  dirCount: NonNegInt.optional().describe('Number of directories in the results'),\n  resourceUri: z\n    .string()\n    .optional()\n    .describe(\n      'URI to aggregated stats.json in the resource store (present when resource store is available)',\n    ),\n});\n\nfunction getPermissions(mode: number): string {\n  let out = '';\n  for (const shift of [6, 3, 0]) {\n    const bits = (mode >> shift) & 0b111;\n    out += (bits & 0b100 ? 'r' : '-') + (bits & 0b010 ? 'w' : '-') + (bits & 0b001 ? 'x' : '-');\n  }\n  return out;\n}\n\nfunction buildFileInfoResult(\n  name: string,\n  requestedPath: string,\n  isSymlink: boolean,\n  stats: Stats,\n  mimeType: string | undefined,\n  symlinkTarget: string | undefined,\n): FileInfo {\n  const tokenEstimate = stats.isFile() ? Math.ceil(stats.size / 4) : undefined;\n  return {\n    name,\n    path: requestedPath,\n    type: isSymlink ? 'symlink' : getFileType(stats),\n    size: stats.size,\n    ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),\n    created: stats.birthtime,\n    modified: stats.mtime,\n    accessed: stats.atime,\n    permissions: getPermissions(stats.mode),\n    isHidden: isHidden(name),\n    ...(mimeType !== undefined ? { mimeType } : {}),\n    ...(symlinkTarget !== undefined ? { symlinkTarget } : {}),\n  };\n}\n\nasync function getSymlinkTarget(\n  pathToRead: string,\n  fs: GuardedFileSystem,\n  signal?: AbortSignal,\n  log?: ToolCtx['log'],\n): Promise<string | undefined> {\n  signal?.throwIfAborted();\n  try {\n    const { linkString } = await fs.readlink(pathToRead);\n    return linkString;\n  } catch (error) {\n    rethrowIfAborted(error);\n    log?.('warning', `stat: readlink failed for \"${pathToRead}\": ${String(error)}`, 'stat');\n    return undefined;\n  }\n}\n\ninterface FileInfoOptions {\n  includeMimeType?: boolean | undefined;\n  signal?: AbortSignal | undefined;\n  onProgress?: (() => void) | undefined;\n  fs: GuardedFileSystem;\n  log?: ToolCtx['log'] | undefined;\n}\n\nasync function getFileInfo(filePath: string, options: FileInfoOptions): Promise<FileInfo> {\n  const { signal, fs, log } = options;\n  signal?.throwIfAborted();\n\n  const {\n    requestedPath,\n    isSymlink,\n    stats: followedStats,\n  } = await fs.statDetailed(filePath, signal ? { signal } : undefined);\n\n  const { base: name, ext: rawExt } = parse(requestedPath);\n  const includeMimeType = options.includeMimeType !== false;\n  const mimeType =\n    includeMimeType && rawExt.length > 0 ? detectMimeType(requestedPath).mimeType : undefined;\n\n  // For a symlink, fsStat follows the link and reports the target's metadata.\n  // Report the link's own metadata instead so size/permissions/timestamps\n  // describe the link the user asked about, not its target.\n  let stats = followedStats;\n  if (isSymlink) {\n    try {\n      ({ stats } = await fs.lstat(requestedPath, signal ? { signal } : undefined));\n    } catch (error) {\n      // A cancelled request is not a \"link metadata unavailable\" fallback.\n      rethrowIfAborted(error);\n      // Guarded lstat can be refused where raw lstat succeeded (e.g. an allowed\n      // root that is itself a symlink, whose parent sits outside the roots).\n      // Falling back to the followed stats degrades the report to the target's\n      // metadata, so leave a trace instead of degrading silently.\n      log?.('warning', `stat: lstat failed for \"${requestedPath}\": ${String(error)}`, 'stat');\n      stats = followedStats;\n    }\n  }\n\n  // isSymlink above is true whenever ANY ancestor is a symlink, because it\n  // compares the requested path with its fully-resolved real path. Only the\n  // entry's own lstat says whether THIS path is a link, so a regular file under\n  // a symlinked parent is reported as a file and no readlink is attempted.\n  const isOwnSymlink = stats.isSymbolicLink();\n  const symlinkTarget = isOwnSymlink\n    ? await getSymlinkTarget(requestedPath, fs, signal, log)\n    : undefined;\n\n  return buildFileInfoResult(name, requestedPath, isOwnSymlink, stats, mimeType, symlinkTarget);\n}\n\nfunction classifyTypeCounts(results: readonly PerPathResult<FileInfo>[]): {\n  fileCount: number;\n  dirCount: number;\n} {\n  let fileCount = 0;\n  let dirCount = 0;\n  for (const result of results) {\n    if ('error' in result) continue;\n    if (result.value.type === 'directory') dirCount += 1;\n    else fileCount += 1;\n  }\n  return { fileCount, dirCount };\n}\n\nfunction toStatPerPathPayload(r: PerPathResult<FileInfo>): z.infer<typeof StatPerPathSchema> {\n  if ('error' in r) {\n    return { path: r.path, error: r.error };\n  }\n  const info = r.value;\n  return {\n    path: r.path,\n    value: {\n      name: info.name,\n      path: info.path,\n      type: info.type,\n      size: info.size,\n      ...(info.tokenEstimate !== undefined ? { tokenEstimate: info.tokenEstimate } : {}),\n      created: info.created.toISOString(),\n      modified: info.modified.toISOString(),\n      accessed: info.accessed.toISOString(),\n      permissions: info.permissions,\n      isHidden: info.isHidden,\n      ...(info.mimeType !== undefined ? { mimeType: info.mimeType } : {}),\n      ...(info.symlinkTarget !== undefined ? { symlinkTarget: info.symlinkTarget } : {}),\n    },\n  };\n}\n\nexport const GET_FILE_INFO = defineTool({\n  name: 'stat',\n  title: 'Get File Info',\n  description:\n    'Get metadata for one or more files or directories: size, type, permissions, MIME type, timestamps, and tokenEstimate. ' +\n    'Use tokenEstimate to pre-screen read cost before calling read. ' +\n    'Single path: pass path. Batch mode: pass paths[].',\n  input: StatInputSchema,\n  output: StatOutputSchema,\n  annotations: {\n    readOnlyHint: true,\n    idempotentHint: true,\n    destructiveHint: false,\n    openWorldHint: false,\n  },\n  timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS,\n  defaultErrorCode: ErrorCode.NOT_FOUND,\n  progress: (args) => {\n    if (args.paths !== undefined) {\n      return { label: 'Stat', subject: `${String(args.paths.length)} paths` };\n    }\n    return { label: 'Stat', subject: args.path ?? '' };\n  },\n  accessPaths: singleOrBatchAccessPaths,\n  run: async (args, ctx) => {\n    const batchInput = args.path !== undefined ? { path: args.path } : { paths: args.paths ?? [] };\n\n    const batch = await runOverPaths<undefined, FileInfo>(\n      batchInput,\n      ctx,\n      async ({ path }) =>\n        getFileInfo(path, {\n          includeMimeType: true,\n          fs: ctx.fs,\n          signal: ctx.signal,\n          log: ctx.log,\n        }),\n      { defaultErrorCode: ErrorCode.NOT_FOUND },\n    );\n\n    const { fileCount, dirCount } = classifyTypeCounts(batch.results);\n    const perPathPayload = batch.results.map(toStatPerPathPayload);\n\n    let resourceUri: string | undefined;\n    const resources: ContentBlock[] = [];\n    if (ctx.resourceStore && batch.summary.total > 1) {\n      const { entry, link } = putJsonResource(\n        ctx.resourceStore,\n        `${String(batch.summary.total)} paths`,\n        perPathPayload,\n      );\n      resourceUri = entry.uri;\n      resources.push(link);\n    }\n\n    const text = perPathPayload\n      .map((r) => {\n        if (r.value) {\n          const { name, type, size } = r.value;\n          // A directory's own inode size says nothing about what is inside it\n          // (0 on Windows, 4096 on ext4), and \"directory, 0 B\" reads as empty.\n          // Use `list` for contents; report the byte size only where it means\n          // something.\n          if (type === 'directory') return `${name}: directory`;\n          return `${name}: ${type}, ${formatBytes(size)}`;\n        }\n        return `${r.path}: ${r.error?.message ?? 'error'}`;\n      })\n      .join('\\n');\n\n    return {\n      structured: {\n        results: perPathPayload,\n        summary: batch.summary,\n        fileCount,\n        dirCount,\n        ...(resourceUri ? { resourceUri } : {}),\n      },\n      text,\n      ...(resources.length > 0 ? { resources } : {}),\n    };\n  },\n});\n"]}

package/dist/transport/http.d.ts

@@ -0,0 +1,5 @@
+import type { Server } from 'node:http';
+import type { ServerOptions } from '../core/path.js';
+import type { RuntimeConfig } from './shared.js';
+export declare function startHttpServer(port: number, options: ServerOptions, config?: RuntimeConfig): Promise<Server>;
+//# sourceMappingURL=http.d.ts.map

package/dist/transport/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transport/http.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAUxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAuBrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyOjD,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,MAAM,GAAE,aAAkB,GACzB,OAAO,CAAC,MAAM,CAAC,CAgIjB"}

package/dist/transport/http.js

@@ -0,0 +1,276 @@
+// HTTP hosting: express app assembly, security middleware wiring, the modern
+// per-request server factory, and listen-filter watcher gating on POST /mcp.
+import { createMcpExpressApp } from '@modelcontextprotocol/express';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { createMcpHandler, DEFAULT_REQUEST_TIMEOUT_MSEC, ProtocolErrorCode, } from '@modelcontextprotocol/server';
+import { createServer as createHttpServer } from 'node:http';
+import { formatUnknownErrorMessage } from '../core/errors.js';
+import { assertFleetRequestStateKey } from '../core/input-required.js';
+import { Logger } from '../core/observability.js';
+import { PageSnapshotStore } from '../core/page-store.js';
+import { PathGuard } from '../core/path.js';
+import { parseTrueEnvFlag } from '../core/primitives.js';
+import { ResourceStore } from '../core/store.js';
+import { MIB, parseEnvInt } from '../core/util.js';
+import { createWatcherRegistry, MAX_WATCHERS, } from '../core/watcher-registry.js';
+import { assertHttpBindingPolicy, assertHttpHostPolicy, bearerAuthMiddleware, computeAllowedOriginHostnames, corsOriginMiddleware, corsPreflightHandler, createRateLimiter, protectedResourceUrl, resolveAllowedHosts, resolveTrustProxySetting, sendJsonRpcError, } from '../http-policy.js';
+import { createServer } from '../server.js';
+import { isStructurallyValidListen, jsonRpcRequestId, listenSubscriptionUris, prepareListenWatchers, } from './shared.js';
+const MAX_REQUEST_BODY_BYTES = parseEnvInt('FS_MAX_REQUEST_BYTES', 4 * MIB, 1024, 256 * MIB);
+/**
+ * The code the SDK's own non-POST rejection carries. Not a `ProtocolErrorCode`
+ * member — the enum has no `-32000` — so it is pinned here to keep the local
+ * 405 envelope identical to the one the handler would have produced.
+ */
+const SDK_METHOD_NOT_ALLOWED_CODE = -32000;
+/** Body-parser rejections and anything else that reaches the end of the chain. */
+function errorHandlerMiddleware(err, _req, res, next) {
+    if (res.headersSent) {
+        next(err);
+        return;
+    }
+    if (err.status === 413) {
+        sendJsonRpcError(res, 413, ProtocolErrorCode.InvalidRequest, 'Request body too large');
+        return;
+    }
+    if (err.status === 400) {
+        sendJsonRpcError(res, 400, ProtocolErrorCode.ParseError, 'Invalid JSON in request body');
+        return;
+    }
+    Logger.error('[HTTP] Unhandled middleware error:', formatUnknownErrorMessage(err));
+    sendJsonRpcError(res, 500, ProtocolErrorCode.InternalError, 'Internal Server Error');
+}
+function makeHttpModernFactory(options, getNotifier, sharedRegistry, sharedPathGuard, sharedStore, sharedPageStore, apiKey) {
+    return async ({ era }) => {
+        const notifier = getNotifier();
+        const c = await createServer(options, {
+            watcherRegistry: sharedRegistry,
+            notifier,
+            pathGuard: sharedPathGuard,
+            resourceStore: sharedStore,
+            pageStore: sharedPageStore,
+            era,
+            ...(apiKey !== undefined ? { apiKey } : {}),
+        });
+        const previousOnClose = c.mcp.server.onclose;
+        c.mcp.server.onclose = () => {
+            previousOnClose?.();
+            c.disposeRuntimeState();
+        };
+        return c.mcp;
+    };
+}
+function setupExpressApp(httpHost, apiKey, allowedHosts, modernNodeHandler, sharedPathGuard, sharedRegistry, notifier) {
+    const allowedOriginHostnames = computeAllowedOriginHostnames(process.env['FS_ALLOWED_ORIGINS']);
+    // Read once here and passed down, like every other env-derived policy input:
+    // http-policy holds no state and reads no env of its own.
+    const publicUrl = process.env['FS_PUBLIC_URL'];
+    const app = createMcpExpressApp({
+        host: httpHost,
+        jsonLimit: `${MAX_REQUEST_BODY_BYTES}b`,
+        ...(allowedHosts.length > 0 ? { allowedHosts: [...allowedHosts] } : {}),
+        ...(allowedOriginHostnames.length > 0 ? { allowedOrigins: [...allowedOriginHostnames] } : {}),
+    });
+    const trustProxy = resolveTrustProxySetting(process.env['FS_TRUST_PROXY']);
+    if (trustProxy !== undefined) {
+        app.set('trust proxy', trustProxy);
+    }
+    if (allowedHosts.length === 0) {
+        Logger.warn('[HTTP] FS_ALLOW_UNRESTRICTED_HOSTS is set: binding globally without Host validation.');
+    }
+    app.options('/mcp', corsPreflightHandler(allowedOriginHostnames));
+    app.use('/mcp', corsOriginMiddleware(allowedOriginHostnames));
+    // Unconditional: the spec's rate-limit MUST is not scoped to authenticated
+    // binds. A keyless bind is loopback-only, so the cap is looser, not absent.
+    const rpm = parseEnvInt('FS_RATE_LIMIT_RPM', apiKey ? 120 : 6_000, 1, 100_000);
+    app.use('/mcp', createRateLimiter(rpm));
+    if (apiKey && allowedHosts.length > 0) {
+        const metadataHandler = (req, res) => {
+            const resource = protectedResourceUrl(req, true, publicUrl);
+            if (!resource) {
+                // Unreachable for the unrestricted case (the gate above excludes it),
+                // but defend a FS_PUBLIC_URL parse failure with a bodyless
+                // 404 — a generic OAuth client cannot parse a JSON-RPC error envelope.
+                res.status(404).end();
+                return;
+            }
+            res.header('Access-Control-Allow-Origin', '*');
+            res.status(200).json({
+                resource: resource.href,
+                bearer_methods_supported: ['header'],
+                resource_name: 'filesystem-mcp',
+            });
+        };
+        app.get(['/.well-known/oauth-protected-resource', '/.well-known/oauth-protected-resource/mcp'], metadataHandler);
+    }
+    app.get('/healthz', (_req, res) => {
+        res.status(200).json({
+            status: 'ok',
+            uptime: process.uptime(),
+        });
+    });
+    app.use('/mcp', bearerAuthMiddleware(apiKey, allowedHosts.length > 0, publicUrl));
+    const resourceUpdateSink = (uri) => {
+        notifier.resourceUpdated(uri);
+    };
+    app.post('/mcp', (req, res, next) => {
+        void (async () => {
+            const parsedBody = req.body;
+            // Only a structurally valid listen gets watchers, mirroring the stdio
+            // gate. A malformed one cannot succeed downstream, so attaching handles
+            // for it only gives the response-close release something to undo — and
+            // everything that is not a listen takes no watchers either way.
+            if (!isStructurallyValidListen(parsedBody)) {
+                await modernNodeHandler(req, res, parsedBody);
+                return;
+            }
+            // Reject an over-cap listen before the ack so the client does not believe
+            // every requested URI is watched when the watcher budget is exhausted.
+            // The per-URI `capped` failure below would also reject, but only after
+            // creating and tearing down every watcher up to the cap.
+            const requestedUris = listenSubscriptionUris(parsedBody);
+            // Only URIs without a live watcher consume a slot; a re-listen to an
+            // already-watched URI just retains another lease.
+            const newUris = requestedUris.filter((uri) => !sharedRegistry.hasWatcher(uri));
+            const available = MAX_WATCHERS - sharedRegistry.size();
+            if (newUris.length > available) {
+                sendJsonRpcError(res, 400, ProtocolErrorCode.InvalidParams, `subscriptions/listen names ${newUris.length} not-yet-watched URIs but only ${available} watcher slots remain (cap ${MAX_WATCHERS}). Reduce the resourceSubscriptions list.`, jsonRpcRequestId(parsedBody));
+                return;
+            }
+            const prepared = await prepareListenWatchers(parsedBody, sharedPathGuard, sharedRegistry, resourceUpdateSink);
+            if (!prepared.ok) {
+                sendJsonRpcError(res, 400, ProtocolErrorCode.InvalidParams, prepared.message, jsonRpcRequestId(parsedBody));
+                return;
+            }
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                for (const uri of prepared.acquiredUris)
+                    sharedRegistry.release(uri);
+            };
+            if (prepared.acquiredUris.length > 0) {
+                // The attach loop awaits per-URI path validation, so the client can be
+                // gone by the time it returns. `close` fires once: a listener attached
+                // after it would never run and every lease this batch took would leak
+                // until process shutdown.
+                if (res.closed || res.destroyed || res.writableEnded)
+                    release();
+                else
+                    res.once('close', release);
+            }
+            try {
+                await modernNodeHandler(req, res, parsedBody);
+            }
+            catch (error) {
+                release();
+                throw error;
+            }
+        })().catch(next);
+    });
+    // Answer non-POST here rather than handing it to `modernNodeHandler`. The
+    // SDK's own 405 is byte-identical to this one, but it omits the `Allow`
+    // header RFC 9110 §15.5.6 requires and routes every routine GET probe through
+    // the handler's `onerror` — which this server logs at error level.
+    app.all('/mcp', (_req, res) => {
+        sendJsonRpcError(res, 405, SDK_METHOD_NOT_ALLOWED_CODE, 'Method not allowed.', null, {
+            Allow: 'POST, OPTIONS',
+        });
+    });
+    app.use(errorHandlerMiddleware);
+    return app;
+}
+export async function startHttpServer(port, options, config = {}) {
+    const httpHost = config.httpHost ?? '127.0.0.1';
+    const { apiKey, eventBus } = config;
+    const fleet = config.deploymentMode === 'fleet';
+    assertHttpBindingPolicy(httpHost, apiKey);
+    if (fleet && !apiKey) {
+        throw new Error('Fleet deployment mode requires an API key.');
+    }
+    if (fleet && !eventBus) {
+        throw new Error('Fleet deployment mode requires a shared event bus.');
+    }
+    assertFleetRequestStateKey(fleet);
+    const allowedHosts = resolveAllowedHosts(httpHost, process.env['FS_ALLOWED_HOSTS']);
+    assertHttpHostPolicy(httpHost, allowedHosts, parseTrueEnvFlag(process.env['FS_ALLOW_UNRESTRICTED_HOSTS'], 'FS_ALLOW_UNRESTRICTED_HOSTS'));
+    const sharedRegistry = createWatcherRegistry();
+    // One store for the whole endpoint, same lifetime and same one-credential
+    // trust argument as the shared guard below: a result a tool externalized in
+    // one POST must survive to the follow-up resources/read, and the modern leg
+    // builds a fresh McpServer per request so a per-request store would discard
+    // it immediately.
+    // Fires only from a tool call, which is long after `modernHandler` below is
+    // constructed, so reading it from the closure is safe (same as `getNotifier`).
+    const sharedStore = new ResourceStore(() => {
+        modernHandler.notify.resourcesChanged();
+    });
+    const sharedPageStore = new PageSnapshotStore();
+    // One guard for the whole endpoint. The modern leg builds a fresh McpServer
+    // per request, so a per-instance guard would discard every accepted access
+    // grant the moment the request ended — re-prompting on each subsequent call
+    // and leaving the listen-watcher path validating against a stale allowed set.
+    // Grant scope is therefore the endpoint, not the connection: with API_KEY set
+    // every caller presents the same key (one auth context by construction), and
+    // without it the bind is loopback-only. Split into per-auth-context guards if
+    // this ever serves more than one credential.
+    const sharedPathGuard = new PathGuard(options, true);
+    await sharedPathGuard.recomputeAllowedDirectories();
+    const modernHandler = createMcpHandler(makeHttpModernFactory(options, () => modernHandler.notify, sharedRegistry, sharedPathGuard, sharedStore, sharedPageStore, apiKey), {
+        legacy: 'reject',
+        ...(eventBus ? { bus: eventBus } : {}),
+        onerror: (error) => {
+            Logger.error('[HTTP] modern leg error:', formatUnknownErrorMessage(error));
+        },
+    });
+    const modernNodeHandler = toNodeHandler(modernHandler);
+    const app = setupExpressApp(httpHost, apiKey, allowedHosts, modernNodeHandler, sharedPathGuard, sharedRegistry, modernHandler.notify);
+    const httpServer = createHttpServer(app);
+    // Must exceed the idle timeout of any proxy in front of this server, or the
+    // proxy reuses connections the server already closed (intermittent 502s).
+    const keepAliveMs = parseEnvInt('FS_KEEPALIVE_TIMEOUT_MS', 5_000, 1_000, 600_000);
+    httpServer.keepAliveTimeout = keepAliveMs;
+    httpServer.headersTimeout = keepAliveMs + 5_000;
+    httpServer.requestTimeout = DEFAULT_REQUEST_TIMEOUT_MSEC;
+    const onHttpServerError = (error) => {
+        Logger.error('[HTTP] runtime server error', {
+            host: httpHost,
+            port,
+            error: formatUnknownErrorMessage(error),
+        });
+    };
+    httpServer.on('error', onHttpServerError);
+    const originalClose = httpServer.close.bind(httpServer);
+    httpServer.close = function (callback) {
+        sharedRegistry.destroy();
+        sharedPageStore.clear();
+        modernHandler
+            .close()
+            .then(() => {
+            originalClose(callback);
+        })
+            .catch((err) => {
+            Logger.error('[HTTP] Error closing handler during HTTP server close:', formatUnknownErrorMessage(err));
+            originalClose(callback);
+        });
+        return httpServer;
+    };
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            sharedRegistry.destroy();
+            sharedPageStore.clear();
+            modernHandler.close().catch((closeErr) => {
+                Logger.error('[HTTP] Error closing handler on startup failure:', formatUnknownErrorMessage(closeErr));
+            });
+            reject(err);
+        };
+        httpServer.once('error', onError);
+        httpServer.listen(port, httpHost, () => {
+            httpServer.removeListener('error', onError);
+            Logger.info(`[HTTP] Server listening on http://${httpHost}:${port}`);
+            resolve(httpServer);
+        });
+    });
+}
+//# sourceMappingURL=http.js.map