@j0hanz/filesystem-mcp 1.2.4 → 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/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/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.js

@@ -1,8 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as http from 'node:http';
-import * as path from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { InMemoryTaskMessageQueue, InMemoryTaskStore, } from '@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -13,7 +11,8 @@ import { formatUnknownErrorMessage } from '../lib/errors.js';
 import { createInMemoryResourceStore } from '../lib/resource-store.js';
 import { pkgInfo } from '../pkg-info.js';
 import { registerGetHelpPrompt } from '../prompts.js';
-import { registerInstructionResource, registerResultResources, } from '../resources.js';
+import { registerInstructionResource, registerMetricsResource, registerResultResources, } from '../resources.js';
+import { buildServerInstructions } from '../resources/generated-instructions.js';
 import { registerAllTools } from '../tools.js';
 import { withDefaultIcons } from '../tools/shared.js';
 import { buildServerCapabilities, supportsTaskToolRequests, } from './capabilities.js';
@@ -28,19 +27,8 @@ function getRootsManager(server) {
     }
     return manager;
 }
-async function loadServerInstructions() {
-    const defaultInstructions = `
-Filesystem MCP Instructions
-(Detailed instructions failed to load - check logs)
-`;
-    try {
-        const currentDir = path.dirname(fileURLToPath(import.meta.url));
-        return await fs.readFile(path.join(currentDir, '../instructions.md'), 'utf-8');
-    }
-    catch (error) {
-        console.error('[WARNING] Failed to load instructions.md:', formatUnknownErrorMessage(error));
-        return defaultInstructions;
-    }
+function loadServerInstructions() {
+    return buildServerInstructions();
 }
 async function getLocalIconInfo() {
     const name = 'logo.svg';
@@ -63,7 +51,7 @@ async function getLocalIconInfo() {
 }
 export async function createServer(options = {}) {
     const resourceStore = createInMemoryResourceStore();
-    const serverInstructions = await loadServerInstructions();
+    const serverInstructions = loadServerInstructions();
     const localIcon = await getLocalIconInfo();
     const taskToolSupport = supportsTaskToolRequests();
     const serverConfig = {
@@ -77,7 +65,10 @@ export async function createServer(options = {}) {
         serverConfig.taskMessageQueue = new InMemoryTaskMessageQueue();
     }
     if (serverInstructions) {
-        serverConfig.instructions = serverInstructions;
+        serverConfig.instructions =
+            'filesystem-mcp: Secure local filesystem MCP server. ' +
+                'Essential sequence: roots → ls/tree/find → read/grep. ' +
+                'Full reference: read the internal://instructions resource or invoke the get-help prompt.';
     }
     const server = new McpServer(withDefaultIcons({
         name: 'filesystem-mcp',
@@ -96,7 +87,8 @@ export async function createServer(options = {}) {
     registerInstructionResource(server, serverInstructions, localIcon);
     registerGetHelpPrompt(server, serverInstructions, localIcon);
     registerResultResources(server, resourceStore, localIcon);
-    registerCompletions(server);
+    registerMetricsResource(server, localIcon);
+    registerCompletions(server, serverInstructions);
     registerAllTools(server, {
         resourceStore,
         isInitialized: () => rootsManager.isInitialized(),
@@ -173,6 +165,31 @@ export async function startHttpServer(port, options) {
     async function handleMcpRequest(req, res) {
         const { method } = req;
         const sessionId = req.headers['mcp-session-id'];
+        const apiKey = process.env['FILESYSTEM_MCP_API_KEY'];
+        if (apiKey) {
+            const authHeader = req.headers['authorization'];
+            const bearerPrefix = 'Bearer ';
+            let authorized = false;
+            if (typeof authHeader === 'string' &&
+                authHeader.startsWith(bearerPrefix)) {
+                const userKey = authHeader.slice(bearerPrefix.length);
+                const expectedHash = createHash('sha256').update(apiKey).digest();
+                const actualHash = createHash('sha256').update(userKey).digest();
+                authorized = timingSafeEqual(expectedHash, actualHash);
+            }
+            if (!authorized) {
+                res.writeHead(401, {
+                    'Content-Type': 'application/json',
+                    'WWW-Authenticate': 'Bearer',
+                });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32000, message: 'Unauthorized' },
+                    id: null,
+                }));
+                return;
+            }
+        }
         try {
             if (method === 'POST') {
                 const body = await readRequestBody(req);
@@ -230,7 +247,10 @@ export async function startHttpServer(port, options) {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({
                         jsonrpc: '2.0',
-                        error: { code: -32000, message: 'Bad Request: Session not found' },
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Session not found',
+                        },
                         id: null,
                     }));
                 }
@@ -256,7 +276,10 @@ export async function startHttpServer(port, options) {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({
                         jsonrpc: '2.0',
-                        error: { code: -32000, message: 'Bad Request: Session not found' },
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Session not found',
+                        },
                         id: null,
                     }));
                 }