@j0hanz/filesystem-mcp 1.2.3 → 1.3.0

package/README.md

@@ -479,6 +479,8 @@ Replace text in all files matching a glob. Replaces **all** occurrences per file
 | `internal://instructions`      | Usage guidance for models          | `text/markdown` |
 | `filesystem-mcp://result/{id}` | Ephemeral cached large tool output | varies          |
 
+When a tool response includes a `resource_link`/`resourceUri`, treat it as authoritative for full payload retrieval and call `resources/read` with that URI.
+
 ### Prompts
 
 | Prompt     | Description                               |
@@ -493,6 +495,12 @@ 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`.
 
+Recommended task follow-up loop:
+
+1. Start with `tools/call` + `task` (optional `_meta.progressToken`).
+2. Poll `tasks/get` until terminal status (`completed`, `failed`, `cancelled`).
+3. Fetch final payload with `tasks/result`.
+
 Task status notifications (`notifications/tasks/status`) are best-effort and emitted only when the transport/runtime provides a notification sender.
 
 Cancellation semantics:

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

@@ -123,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', `
@@ -130,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);
@@ -171,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);
@@ -185,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 {
@@ -195,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.d.ts

@@ -9,5 +9,5 @@ interface CompletionOptions {
     contextArguments?: Record<string, string>;
 }
 export declare function getPathCompletions(currentValue: string, options?: CompletionOptions): Promise<CompletionResult>;
-export declare function registerCompletions(server: McpServer): void;
+export declare function registerCompletions(server: McpServer, instructions?: string): void;
 export {};

package/dist/completions.js

@@ -5,6 +5,19 @@ import { toPosixPath } from './lib/path-format.js';
 import { getAllowedDirectories, isPathWithinDirectories, normalizePath, } from './lib/path-validation.js';
 import { isRecord } from './lib/type-guards.js';
 const MAX_COMPLETION_ITEMS = 100;
+const COMPLETION_RATE_LIMIT_MS = 100;
+const completionLastCallMs = new Map();
+function extractTopicCompletions(instructions) {
+    const headers = [];
+    for (const line of instructions.split('\n')) {
+        if (line.startsWith('## ')) {
+            const header = line.slice(3).trim().toLowerCase();
+            if (header)
+                headers.push(header);
+        }
+    }
+    return headers;
+}
 const PATH_ARGUMENTS = new Set([
     'path',
     'source',
@@ -352,16 +365,38 @@ export async function getPathCompletions(currentValue, options = {}) {
         return { values: [] };
     }
 }
-export function registerCompletions(server) {
+export function registerCompletions(server, instructions = '') {
+    const topicValues = extractTopicCompletions(instructions);
     server.server.setRequestHandler(CompleteRequestSchema, async (request) => {
         const { params } = request;
         const { argument, ref } = params;
         const argName = argument.name.toLowerCase();
+        // Handle prompt topic completions
+        if (isRecord(ref) && ref['type'] === 'ref/prompt' && argName === 'topic') {
+            const currentValue = argument.value.toLowerCase();
+            const filtered = currentValue
+                ? topicValues.filter((v) => v.startsWith(currentValue))
+                : topicValues;
+            const sliced = filtered.slice(0, MAX_COMPLETION_ITEMS);
+            return {
+                completion: {
+                    values: sliced,
+                    total: filtered.length,
+                    hasMore: filtered.length > MAX_COMPLETION_ITEMS,
+                },
+            };
+        }
         const isPathArg = isPathLikeArgumentName(argName) ||
             isPathArgumentFromReference(argName, ref);
         if (!isPathArg) {
             return { completion: { values: [], total: 0, hasMore: false } };
         }
+        const now = Date.now();
+        const lastCallMs = completionLastCallMs.get(argName) ?? 0;
+        if (now - lastCallMs < COMPLETION_RATE_LIMIT_MS) {
+            return { completion: { values: [], total: 0, hasMore: false } };
+        }
+        completionLastCallMs.set(argName, now);
         const contextArguments = extractContextArguments(params.context);
         const { value } = argument;
         const completions = await getPathCompletions(value, {

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/observability.d.ts

@@ -5,6 +5,12 @@ interface OpsTraceContext {
     path?: string | undefined;
     [key: string]: unknown;
 }
+export interface ToolMetrics {
+    calls: number;
+    errors: number;
+    totalDurationMs: number;
+}
+export declare const globalMetrics: Map<string, ToolMetrics>;
 export declare function shouldPublishOpsTrace(): boolean;
 export declare function publishOpsTraceStart(context: OpsTraceContext): void;
 export declare function publishOpsTraceEnd(context: OpsTraceContext): void;

package/dist/lib/observability.js

@@ -24,7 +24,7 @@ function parseDetail(val) {
         return 1;
     return 0;
 }
-const globalMetrics = new Map();
+export const globalMetrics = new Map();
 function updateMetrics(tool, ok, durationMs) {
     const current = globalMetrics.get(tool) ?? {
         calls: 0,

package/dist/lib/resource-store.js

@@ -1,10 +1,17 @@
 import { hash, randomUUID } from 'node:crypto';
+import { channel } from 'node:diagnostics_channel';
 import { ErrorCode, McpError } from './errors.js';
 const DEFAULT_RESOURCE_STORE_OPTIONS = {
     maxEntries: 64,
     maxTotalBytes: 25 * 1024 * 1024,
     maxEntryBytes: 10 * 1024 * 1024,
 };
+const RESOURCE_STORE_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:resource-store');
+function publishResourceStoreDiagnostics(event) {
+    if (!RESOURCE_STORE_DIAGNOSTICS_CHANNEL.hasSubscribers)
+        return;
+    RESOURCE_STORE_DIAGNOSTICS_CHANNEL.publish(event);
+}
 function estimateBytes(text) {
     return Buffer.byteLength(text, 'utf8');
 }
@@ -41,6 +48,12 @@ export function createInMemoryResourceStore(options = {}) {
         totalBytes -= existing.size;
         byUri.delete(uri);
         byHashIndex.delete(existing.hash);
+        publishResourceStoreDiagnostics({
+            phase: 'cache_evict',
+            uri,
+            name: existing.name,
+            bytes: existing.size,
+        });
     }
     function enforceLimits() {
         while (byUri.size > resolved.maxEntries)
@@ -55,6 +68,11 @@ export function createInMemoryResourceStore(options = {}) {
         const mimeType = params.mimeType ?? 'text/plain';
         const entryBytes = estimateBytes(params.text);
         if (entryBytes > resolved.maxEntryBytes) {
+            publishResourceStoreDiagnostics({
+                phase: 'cache_reject',
+                bytes: entryBytes,
+                reason: 'entry_too_large',
+            });
             throw new McpError(ErrorCode.E_TOO_LARGE, `Resource too large to cache (${entryBytes} bytes)`);
         }
         const contentHash = computeSha256(params.text);
@@ -62,6 +80,12 @@ export function createInMemoryResourceStore(options = {}) {
         if (existingUri !== undefined) {
             const cached = byUri.get(existingUri);
             if (cached !== undefined) {
+                publishResourceStoreDiagnostics({
+                    phase: 'cache_hit',
+                    uri: cached.uri,
+                    name: cached.name,
+                    bytes: cached.size,
+                });
                 return cached;
             }
         }
@@ -76,8 +100,21 @@ export function createInMemoryResourceStore(options = {}) {
         byUri.set(uri, entry);
         byHashIndex.set(contentHash, uri);
         totalBytes += entryBytes;
+        publishResourceStoreDiagnostics({
+            phase: 'cache_store',
+            uri: entry.uri,
+            name: entry.name,
+            bytes: entry.size,
+        });
         enforceLimits();
         if (!byUri.has(uri)) {
+            publishResourceStoreDiagnostics({
+                phase: 'cache_reject',
+                uri,
+                name: entry.name,
+                bytes: entry.size,
+                reason: 'evicted_immediately',
+            });
             throw new McpError(ErrorCode.E_TOO_LARGE, 'Resource cache full: entry evicted immediately');
         }
         return entry;
@@ -85,14 +122,30 @@ export function createInMemoryResourceStore(options = {}) {
     function getText(uri) {
         const existing = byUri.get(uri);
         if (!existing) {
+            publishResourceStoreDiagnostics({
+                phase: 'cache_miss',
+                uri,
+                reason: 'not_found',
+            });
             throw new McpError(ErrorCode.E_NOT_FOUND, `Resource not found: ${uri}. The cached result may have been evicted. Re-run the originating tool to regenerate.`);
         }
+        publishResourceStoreDiagnostics({
+            phase: 'cache_hit',
+            uri: existing.uri,
+            name: existing.name,
+            bytes: existing.size,
+        });
         return existing;
     }
     function clear() {
+        const bytesBeforeClear = totalBytes;
         byUri.clear();
         byHashIndex.clear();
         totalBytes = 0;
+        publishResourceStoreDiagnostics({
+            phase: 'cache_clear',
+            bytes: bytesBeforeClear,
+        });
     }
     return { putText, getText, clear };
 }

package/dist/prompts.js

@@ -1,21 +1,41 @@
+import { z } from 'zod';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
 const HELP_PROMPT_DESCRIPTION = 'Return the filesystem-mcp usage instructions.';
+function filterInstructionsByTopic(instructions, topic) {
+    const normalized = topic.trim().toLowerCase();
+    if (!normalized)
+        return instructions;
+    const sections = instructions.split(/\n(?=## )/u);
+    const match = sections.find((sec) => sec.toLowerCase().startsWith(`## ${normalized}`));
+    return match ?? instructions;
+}
 export function registerGetHelpPrompt(server, instructions, iconInfo) {
-    server.registerPrompt(HELP_PROMPT_NAME, withDefaultIcons({
-        title: HELP_PROMPT_TITLE,
-        description: HELP_PROMPT_DESCRIPTION,
-    }, iconInfo), () => ({
-        description: HELP_PROMPT_DESCRIPTION,
-        messages: [
-            {
-                role: 'user',
-                content: {
-                    type: 'text',
-                    text: instructions,
+    const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);
+    server.registerPrompt(HELP_PROMPT_NAME, {
+        ...baseConfig,
+        argsSchema: {
+            topic: z
+                .string()
+                .optional()
+                .describe('Section heading prefix to filter (e.g. "error handling strategy"). Omit for full instructions.'),
+        },
+    }, ({ topic }) => {
+        const text = topic
+            ? filterInstructionsByTopic(instructions, topic)
+            : instructions;
+        return {
+            description: HELP_PROMPT_DESCRIPTION,
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text,
+                    },
                 },
-            },
-        ],
-    }));
+            ],
+        };
+    });
 }

package/dist/resources/generated-instructions.d.ts

@@ -0,0 +1 @@
+export declare function buildServerInstructions(): string;

package/dist/resources/generated-instructions.js

@@ -0,0 +1,100 @@
+import { ALL_TOOLS } from '../tools.js';
+const INSTRUCTIONS_HEADER = `# FILESYSTEM-MCP INSTRUCTIONS
+
+> Resource: \`internal://instructions\` | Prompt: \`get-help\`
+
+## CORE CAPABILITY
+
+- **Domain:** Safe local filesystem operations (read/write/diff/patch) within allowed roots.
+- **Tools:**
+  - READ: \`roots\`, \`ls\`, \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat\`, \`stat_many\`, \`grep\`, \`calculate_hash\`, \`diff_files\`.
+  - WRITE: \`mkdir\`, \`write\`, \`edit\`, \`mv\`, \`rm\`, \`apply_patch\`, \`search_and_replace\`.
+
+## RESOURCES
+
+- \`filesystem-mcp://result/{id}\`: Ephemeral cached output.
+- \`filesystem-mcp://metrics\`: Live tool stats.
+- **Tip:** If response has \`resourceUri\`, call \`resources/read\` to fetch full content.
+
+## PROGRESS & TASKS
+
+- Support \`_meta.progressToken\` for updates.
+- Task tools: \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat_many\`, \`grep\`, \`mkdir\`, \`write\`, \`mv\`, \`rm\`, \`calculate_hash\`, \`apply_patch\`, \`search_and_replace\`.
+- Flow: \`tools/call\` (task) → \`tasks/get\` → \`tasks/result\`.
+
+## GOLDEN PATH WORKFLOWS
+
+### A: EXPLORE
+1. \`roots\` (List allowed paths).
+2. \`ls\` (files) | \`tree\` (structure).
+3. \`stat\` | \`stat_many\` (size/type check).
+4. \`read\` | \`read_many\` (content).
+   > **Strict:** Never guess paths. Resolve first.
+
+### B: SEARCH
+1. \`find\` (glob candidates).
+2. \`grep\` (content search).
+3. \`read\` (verify context).
+   > **Tip:** Content search requires \`grep\`, not \`find\`.
+
+### C: EDIT
+1. \`edit\` (precise string match).
+2. \`search_and_replace\` (bulk regex/glob).
+3. \`mv\` | \`rm\` (file layout).
+4. \`mkdir\` (create dirs).
+   > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
+
+### D: PATCH
+1. \`diff_files\` (generate).
+2. \`apply_patch\` (dryRun: true).
+3. \`apply_patch\` (dryRun: false).
+   > **Tip:** Use \`diff_files\` output directly.
+`;
+const INSTRUCTIONS_FOOTER = `
+## CONSTRAINTS
+
+- **Scope:** Allowed roots only (negotiated via CLI).
+- **Security:** Sensitive files denylisted by default.
+- **Limits:** Max file size & search results enforced.
+- **Cache:** Externalized results are ephemeral (in-memory).
+
+## ERROR HANDLING
+
+- \`E_ACCESS_DENIED\` → Call \`roots\`; use allowed path.
+- \`E_NOT_FOUND\`     → Call \`ls\`/\`find\`; verify spelling.
+- \`E_TOO_LARGE\`     → Use range/head or \`read_many\`.
+- \`E_TIMEOUT\`       → Reduce scope or result limits.
+`;
+function formatToolSection(tool) {
+    const parts = [`${tool.name}: ${tool.description}`];
+    if (tool.annotations) {
+        const attrs = [];
+        if (tool.annotations.destructiveHint)
+            attrs.push('[Destructive]');
+        if (tool.annotations.idempotentHint)
+            attrs.push('[Idempotent]');
+        if (tool.annotations.readOnlyHint)
+            attrs.push('[Read-Only]');
+        if (attrs.length > 0)
+            parts.push(attrs.join(' '));
+    }
+    if (tool.nuances && tool.nuances.length > 0) {
+        parts.push(...tool.nuances.map((n) => `! ${n}`));
+    }
+    if (tool.gotchas && tool.gotchas.length > 0) {
+        parts.push(...tool.gotchas.map((g) => `! ${g}`));
+    }
+    return parts.join('\n');
+}
+export function buildServerInstructions() {
+    const toolSections = ALL_TOOLS.map(formatToolSection).join('\n\n');
+    return [
+        INSTRUCTIONS_HEADER,
+        '## TOOL REFERENCE',
+        '',
+        toolSections,
+        '',
+        '---',
+        INSTRUCTIONS_FOOTER,
+    ].join('\n');
+}

package/dist/resources.d.ts

@@ -3,3 +3,4 @@ import type { ResourceStore } from './lib/resource-store.js';
 import { type IconInfo } from './tools/shared.js';
 export declare function registerInstructionResource(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
 export declare function registerResultResources(server: McpServer, store: ResourceStore, iconInfo?: IconInfo): void;
+export declare function registerMetricsResource(server: McpServer, iconInfo?: IconInfo): void;

package/dist/resources.js

@@ -1,5 +1,6 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from './lib/errors.js';
+import { globalMetrics } from './lib/observability.js';
 import { withDefaultIcons } from './tools/shared.js';
 const RESULT_TEMPLATE = new ResourceTemplate('filesystem-mcp://result/{id}', {
     list: undefined,
@@ -9,6 +10,9 @@ const INSTRUCTIONS_RESOURCE_URI = 'internal://instructions';
 const INSTRUCTIONS_RESOURCE_DESCRIPTION = 'Guidance for using the filesystem-mcp MCP tools effectively.';
 const RESULT_RESOURCE_NAME = 'filesystem-mcp-result';
 const RESULT_RESOURCE_DESCRIPTION = 'Ephemeral cached tool output exposed as an MCP resource. Not guaranteed to be listed via resources/list.';
+const METRICS_RESOURCE_NAME = 'filesystem-mcp-metrics';
+const METRICS_RESOURCE_URI = 'filesystem-mcp://metrics';
+const METRICS_RESOURCE_DESCRIPTION = 'Live per-tool call/error/avgDurationMs metrics snapshot.';
 export function registerInstructionResource(server, instructions, iconInfo) {
     server.registerResource(INSTRUCTIONS_RESOURCE_NAME, INSTRUCTIONS_RESOURCE_URI, withDefaultIcons({
         title: 'Server Instructions',
@@ -40,7 +44,7 @@ export function registerResultResources(server, store, iconInfo) {
     }, iconInfo), (uri, variables) => {
         const { id } = variables;
         if (typeof id !== 'string' || id.length === 0) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Missing resource id');
+            throw new McpError(ErrorCode.E_NOT_FOUND, 'Cached result has expired — re-run the tool to regenerate.');
         }
         const entry = store.getText(uri.toString());
         return {
@@ -54,3 +58,34 @@ export function registerResultResources(server, store, iconInfo) {
         };
     });
 }
+export function registerMetricsResource(server, iconInfo) {
+    server.registerResource(METRICS_RESOURCE_NAME, METRICS_RESOURCE_URI, withDefaultIcons({
+        title: 'Tool Metrics',
+        description: METRICS_RESOURCE_DESCRIPTION,
+        mimeType: 'application/json',
+        annotations: {
+            audience: ['assistant'],
+            priority: 0.5,
+        },
+    }, iconInfo), (uri) => {
+        const snapshot = {};
+        for (const [tool, m] of globalMetrics) {
+            snapshot[tool] = {
+                calls: m.calls,
+                errors: m.errors,
+                avgDurationMs: m.calls > 0
+                    ? parseFloat((m.totalDurationMs / m.calls).toFixed(2))
+                    : 0,
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify({ ok: true, metrics: snapshot }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/schemas.d.ts

@@ -47,6 +47,7 @@ export declare const ListDirectoryInputSchema: z.ZodObject<{
     }>>>;
     pattern: z.ZodOptional<z.ZodString>;
     includeSymlinkTargets: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const ListAllowedDirectoriesInputSchema: z.ZodObject<{}, z.core.$strict>;
 export declare const SearchFilesInputSchema: z.ZodObject<{
@@ -62,6 +63,7 @@ export declare const SearchFilesInputSchema: z.ZodObject<{
         modified: "modified";
     }>>>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const TreeInputSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
@@ -153,6 +155,7 @@ export declare const ListDirectoryOutputSchema: z.ZodObject<{
     }>>;
     skippedInaccessible: z.ZodOptional<z.ZodNumber>;
     symlinksNotFollowed: z.ZodOptional<z.ZodNumber>;
+    nextCursor: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{
             readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
@@ -211,6 +214,7 @@ export declare const SearchFilesOutputSchema: z.ZodObject<{
         maxFiles: "maxFiles";
         timeout: "timeout";
     }>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const SearchContentOutputSchema: z.ZodObject<{
     totalMatches: z.ZodOptional<z.ZodNumber>;
@@ -711,6 +715,8 @@ export declare const SearchAndReplaceInputSchema: z.ZodObject<{
     replacement: z.ZodString;
     isRegex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    includeHidden: z.ZodOptional<z.ZodBoolean>;
+    includeIgnored: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const SearchAndReplaceOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;

package/dist/schemas.js

@@ -135,6 +135,10 @@ export const ListDirectoryInputSchema = z.strictObject({
         .optional()
         .default(false)
         .describe('Resolve and include symlink targets in results'),
+    cursor: z
+        .string()
+        .optional()
+        .describe('Pagination cursor from a previous response'),
 });
 export const ListAllowedDirectoriesInputSchema = z
     .strictObject({})
@@ -177,6 +181,10 @@ export const SearchFilesInputSchema = z.strictObject({
         .max(100, 'Max: 100')
         .optional()
         .describe('Maximum directory depth to scan'),
+    cursor: z
+        .string()
+        .optional()
+        .describe('Pagination cursor from a previous response'),
 });
 export const TreeInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
@@ -325,6 +333,10 @@ export const ListDirectoryOutputSchema = z.strictObject({
     stoppedReason: ListDirectoryStopReasonSchema.optional(),
     skippedInaccessible: z.number().optional(),
     symlinksNotFollowed: z.number().optional(),
+    nextCursor: z
+        .string()
+        .optional()
+        .describe('Cursor for the next page; absent on the final page'),
     error: ErrorSchema.optional(),
 });
 const SearchSummarySchema = z.strictObject({
@@ -347,6 +359,10 @@ export const SearchFilesOutputSchema = SearchSummarySchema.extend({
     filesScanned: z.number().optional().describe('Files scanned'),
     skippedInaccessible: z.number().optional().describe('Inaccessible files'),
     stoppedReason: SearchStopReasonSchema.optional().describe('Why search stopped'),
+    nextCursor: z
+        .string()
+        .optional()
+        .describe('Cursor for the next page; absent on the final page'),
 });
 export const SearchContentOutputSchema = SearchSummarySchema.extend({
     ok: z.boolean(),
@@ -613,6 +629,14 @@ export const SearchAndReplaceInputSchema = z.strictObject({
         .optional()
         .default(false)
         .describe('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
+    includeHidden: z
+        .boolean()
+        .optional()
+        .describe('Include hidden files and directories (starting with .) in the search scope. Default: false.'),
+    includeIgnored: z
+        .boolean()
+        .optional()
+        .describe('Include files and directories ignored by .gitignore rules (e.g. node_modules, dist). Default: false.'),
 });
 export const SearchAndReplaceOutputSchema = z.strictObject({
     ok: z.boolean(),

package/dist/server/bootstrap.d.ts

@@ -1,4 +1,6 @@
+import * as http from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ServerOptions } from './types.js';
 export declare function createServer(options?: ServerOptions): Promise<McpServer>;
 export declare function startServer(server: McpServer): Promise<void>;
+export declare function startHttpServer(port: number, options: ServerOptions): Promise<http.Server>;