@j0hanz/filesystem-mcp 1.4.0 → 1.5.0

package/dist/config.d.ts

@@ -112,8 +112,9 @@ export declare const ErrorCode: {
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export declare function formatBytes(bytes: number): string;
 export declare function joinLines(lines: readonly string[]): string;
-export interface OperationSummary {
+interface OperationSummary {
     truncated?: boolean;
     truncatedReason?: string;
 }
 export declare function formatOperationSummary(summary: OperationSummary): string;
+export {};

package/dist/lib/constants.d.ts

@@ -1,5 +1,3 @@
-declare const VALID_LOG_LEVELS: readonly ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"];
-export type ValidLogLevel = (typeof VALID_LOG_LEVELS)[number];
 export declare const DEFAULT_LOG_LEVEL: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
 export declare const PARALLEL_CONCURRENCY: number;
 export declare const MAX_SEARCHABLE_FILE_SIZE: number;
@@ -22,4 +20,3 @@ export declare const SENSITIVE_FILE_ALLOWLIST: string[];
 export declare const KNOWN_BINARY_EXTENSIONS: Set<string>;
 export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
 export declare function getMimeType(ext: string): string;
-export {};

package/dist/lib/observability.d.ts

@@ -5,7 +5,7 @@ interface OpsTraceContext {
     path?: string | undefined;
     [key: string]: unknown;
 }
-export interface ToolMetrics {
+interface ToolMetrics {
     calls: number;
     errors: number;
     totalDurationMs: number;

package/dist/resources/generated-instructions.js

@@ -1,4 +1,6 @@
-import { ALL_TOOLS } from '../tools.js';
+import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
+import { buildCoreContextPack, getSharedConstraints, getToolContracts, } from './tool-info.js';
+import { buildWorkflowGuide } from './workflows.js';
 const INSTRUCTIONS_HEADER = `# FILESYSTEM-MCP INSTRUCTIONS
 
 > Resource: \`internal://instructions\` | Prompt: \`get-help\`
@@ -24,39 +26,15 @@ const INSTRUCTIONS_HEADER = `# FILESYSTEM-MCP INSTRUCTIONS
 
 ## 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.
+See "Workflow Reference" below for detailed execution sequences.
 
-### 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).
+${getSharedConstraints()
+    .map((c) => `- ${c}`)
+    .join('\n')}
 
 ## ERROR HANDLING
 
@@ -87,13 +65,19 @@ function formatToolSection(tool) {
     return parts.join('\n');
 }
 export function buildServerInstructions() {
-    const toolSections = ALL_TOOLS.map(formatToolSection).join('\n\n');
+    const toolSections = getToolContracts().map(formatToolSection).join('\n\n');
     return [
         INSTRUCTIONS_HEADER,
+        buildCoreContextPack(),
+        '',
+        buildToolCatalogDetailsOnly(),
+        '',
         '## TOOL REFERENCE',
         '',
         toolSections,
         '',
+        buildWorkflowGuide(),
+        '',
         '---',
         INSTRUCTIONS_FOOTER,
     ].join('\n');

package/dist/resources/tool-catalog.d.ts

@@ -0,0 +1,2 @@
+export declare function buildToolCatalog(): string;
+export declare function buildToolCatalogDetailsOnly(): string;

package/dist/resources/tool-catalog.js

@@ -0,0 +1,29 @@
+import { buildCoreContextPack } from './tool-info.js';
+const CATALOG_GUIDE = `## Tool Catalog Details
+
+## Cross-Tool Data Flow
+
+\`\`\`
+find -> output_paths -> grep.paths
+diff_files -> output_patch -> apply_patch.patch
+\`\`\`
+
+## Search Strategy Strategy
+
+- Use \`find\` for glob-based file discovery.
+- Use \`grep\` for content-based searches.
+- Use \`search_and_replace\` ONLY for bulk replacements, not for discovery.
+
+## Patch Management
+
+- Always generate a patch with \`diff_files\` first.
+- Always use \`dryRun: true\` with \`apply_patch\` to verify changes.
+- \`apply_patch\` works on unified diff format.
+`;
+export function buildToolCatalog() {
+    // Return combined view for standalone resource usage
+    return `${buildCoreContextPack()}\n\n${CATALOG_GUIDE}`;
+}
+export function buildToolCatalogDetailsOnly() {
+    return CATALOG_GUIDE;
+}

package/dist/resources/tool-info.d.ts

@@ -0,0 +1,4 @@
+import type { ToolContract } from '../tools/contract.js';
+export declare function getToolContracts(): ToolContract[];
+export declare function buildCoreContextPack(): string;
+export declare function getSharedConstraints(): string[];

package/dist/resources/tool-info.js

@@ -0,0 +1,44 @@
+import { ALL_TOOLS } from '../tools.js';
+function toEntry(contract) {
+    const annotations = [];
+    if (contract.annotations?.destructiveHint)
+        annotations.push('[Destructive]');
+    if (contract.annotations?.idempotentHint)
+        annotations.push('[Idempotent]');
+    if (contract.annotations?.readOnlyHint)
+        annotations.push('[Read-Only]');
+    return {
+        name: contract.name,
+        description: contract.description,
+        ...(annotations.length > 0 ? { annotations } : {}),
+        ...(contract.nuances && contract.nuances.length > 0
+            ? { nuances: contract.nuances }
+            : {}),
+        ...(contract.gotchas && contract.gotchas.length > 0
+            ? { gotchas: contract.gotchas }
+            : {}),
+    };
+}
+const ENTRIES = Object.fromEntries(ALL_TOOLS.map((contract) => [contract.name, toEntry(contract)]));
+export function getToolContracts() {
+    return ALL_TOOLS;
+}
+export function buildCoreContextPack() {
+    const names = Object.keys(ENTRIES).sort((a, b) => a.localeCompare(b));
+    const rows = names.map((name) => {
+        const e = ENTRIES[name];
+        if (!e)
+            return '';
+        const annotations = e.annotations ? ` ${e.annotations.join(' ')}` : '';
+        return `| \`${e.name}\` | ${e.description}${annotations} |`;
+    });
+    return `## Core Context Pack\n\n| Tool | Purpose |\n|------|---------|\n${rows.join('\n')}`;
+}
+export function getSharedConstraints() {
+    return [
+        'Allowed roots only (negotiated via CLI).',
+        'Sensitive files denylisted by default.',
+        'Max file size & search results enforced.',
+        'Externalized results are ephemeral (in-memory).',
+    ];
+}

package/dist/resources/workflows.d.ts

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

package/dist/resources/workflows.js

@@ -0,0 +1,36 @@
+import { getSharedConstraints } from './tool-info.js';
+export function buildWorkflowGuide() {
+    return `## Workflow Reference
+
+### 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.
+
+## Shared Constraints
+${getSharedConstraints()
+        .map((c) => `- ${c}`)
+        .join('\n')}
+`;
+}

package/dist/resources.d.ts

@@ -2,5 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 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 registerToolCatalogResource(server: McpServer, iconInfo?: IconInfo): void;
+export declare function registerWorkflowGuideResource(server: McpServer, 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,6 +1,8 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from './lib/errors.js';
 import { globalMetrics } from './lib/observability.js';
+import { buildToolCatalog } from './resources/tool-catalog.js';
+import { buildWorkflowGuide } from './resources/workflows.js';
 import { withDefaultIcons } from './tools/shared.js';
 const RESULT_TEMPLATE = new ResourceTemplate('filesystem-mcp://result/{id}', {
     list: undefined,
@@ -13,6 +15,12 @@ const RESULT_RESOURCE_DESCRIPTION = 'Ephemeral cached tool output exposed as an
 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.';
+const CATALOG_RESOURCE_NAME = 'filesystem-mcp-catalog';
+const CATALOG_RESOURCE_URI = 'internal://tool-catalog';
+const CATALOG_RESOURCE_DESCRIPTION = 'Detailed catalog of tools and their inter-dependencies.';
+const WORKFLOW_RESOURCE_NAME = 'filesystem-mcp-workflows';
+const WORKFLOW_RESOURCE_URI = 'internal://workflows';
+const WORKFLOW_RESOURCE_DESCRIPTION = 'Recommended workflows for common tasks.';
 export function registerInstructionResource(server, instructions, iconInfo) {
     server.registerResource(INSTRUCTIONS_RESOURCE_NAME, INSTRUCTIONS_RESOURCE_URI, withDefaultIcons({
         title: 'Server Instructions',
@@ -32,6 +40,44 @@ export function registerInstructionResource(server, instructions, iconInfo) {
         ],
     }));
 }
+export function registerToolCatalogResource(server, iconInfo) {
+    server.registerResource(CATALOG_RESOURCE_NAME, CATALOG_RESOURCE_URI, withDefaultIcons({
+        title: 'Tool Catalog',
+        description: CATALOG_RESOURCE_DESCRIPTION,
+        mimeType: 'text/markdown',
+        annotations: {
+            audience: ['assistant'],
+            priority: 0.6,
+        },
+    }, iconInfo), (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: buildToolCatalog(),
+            },
+        ],
+    }));
+}
+export function registerWorkflowGuideResource(server, iconInfo) {
+    server.registerResource(WORKFLOW_RESOURCE_NAME, WORKFLOW_RESOURCE_URI, withDefaultIcons({
+        title: 'Workflow Guide',
+        description: WORKFLOW_RESOURCE_DESCRIPTION,
+        mimeType: 'text/markdown',
+        annotations: {
+            audience: ['assistant'],
+            priority: 0.7,
+        },
+    }, iconInfo), (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: buildWorkflowGuide(),
+            },
+        ],
+    }));
+}
 export function registerResultResources(server, store, iconInfo) {
     server.registerResource(RESULT_RESOURCE_NAME, RESULT_TEMPLATE, withDefaultIcons({
         title: 'Cached Tool Result',

package/dist/server/bootstrap.js

@@ -12,7 +12,7 @@ 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, registerMetricsResource, registerResultResources, } from '../resources.js';
+import { registerInstructionResource, registerMetricsResource, registerResultResources, registerToolCatalogResource, registerWorkflowGuideResource, } from '../resources.js';
 import { buildServerInstructions } from '../resources/generated-instructions.js';
 import { registerAllTools } from '../tools.js';
 import { withDefaultIcons } from '../tools/shared.js';
@@ -86,6 +86,8 @@ export async function createServer(options = {}) {
         return {};
     });
     registerInstructionResource(server, serverInstructions, localIcon);
+    registerToolCatalogResource(server, localIcon);
+    registerWorkflowGuideResource(server, localIcon);
     registerGetHelpPrompt(server, serverInstructions, localIcon);
     registerResultResources(server, resourceStore, localIcon);
     registerMetricsResource(server, localIcon);

package/dist/server/capabilities.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export interface CapabilityOptions {
+interface CapabilityOptions {
     enablePromptListChanged?: boolean;
     enableTaskToolRequests?: boolean;
 }

package/dist/server.d.ts

@@ -1,2 +1 @@
 export { createServer, startHttpServer, startServer, } from './server/bootstrap.js';
-export type { ServerOptions } from './server/types.js';

package/dist/tools/shared.d.ts

@@ -48,7 +48,6 @@ interface ToolErrorResponse extends Record<string, unknown> {
     isError: true;
 }
 export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;
-export declare function parseToolArgs<Schema extends z.ZodType>(schema: Schema, args: unknown): z.infer<Schema>;
 export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: unknown, extra: ToolExtra) => Promise<ToolResult<Result>>;
 type ProgressToken = string | number;
 export interface ToolExtra {

package/dist/tools/shared.js

@@ -107,7 +107,7 @@ function resolveDetailedError(error, defaultCode, path) {
 export function buildToolResponse(text, structuredContent, extraContent = []) {
     return buildContentBlock(text, structuredContent, extraContent);
 }
-export function parseToolArgs(schema, args) {
+function parseToolArgs(schema, args) {
     const candidate = args === undefined ? {} : args;
     const parsed = schema.safeParse(candidate);
     if (parsed.success) {

package/dist/tools/task-support.d.ts

@@ -9,12 +9,6 @@ type TaskToolExtra = ToolExtra & {
     taskRequestedTtl?: number | null;
 };
 type ToolArgs<Args extends ZodRawShapeCompat | AnySchema | undefined> = Args extends ZodRawShapeCompat ? ShapeOutput<Args> : Args extends AnySchema ? SchemaOutput<Args> : undefined;
-/**
- * Registers a tool preferring task-capable registration when available, and
- * returns `true`. Returns `false` so the caller can fall through to standard
- * `server.registerTool`.
- */
-export declare function tryRegisterToolTask<Args extends ZodRawShapeCompat | AnySchema | undefined>(server: McpServer, toolName: string, toolDef: object, taskHandler: ToolTaskHandler<Args>, iconInfo: IconInfo | undefined): boolean;
 export declare function registerToolTaskIfAvailable<Args extends ZodRawShapeCompat | AnySchema | undefined, Result>(server: McpServer, toolName: string, toolDef: object, run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, iconInfo: IconInfo | undefined, guard?: () => boolean): boolean;
 export declare function createToolTaskHandler<Result>(run: (args: undefined, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
     guard?: () => boolean;

package/dist/tools/task-support.js

@@ -298,7 +298,7 @@ async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName
  * returns `true`. Returns `false` so the caller can fall through to standard
  * `server.registerTool`.
  */
-export function tryRegisterToolTask(server, toolName, toolDef, taskHandler, iconInfo) {
+function tryRegisterToolTask(server, toolName, toolDef, taskHandler, iconInfo) {
     if (!hasTaskToolCapability(server))
         return false;
     const tasks = getExperimentalTaskRegistration(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",