filesystem-mcp

Instructions

Implementation Reference

• src/handlers/search-files.ts:221-270 (handler)

  Main handler function that validates args, compiles regex, finds files with glob, searches content in parallel, collects matches with context lines and errors, returns JSON-structured response.

  export const handleSearchFilesFunc = async (
    deps: SearchFilesDependencies,
    args: unknown,
  ): Promise<LocalMcpResponse> => {
    // Updated response type
    const {
      path: relativePath,
      regex: regexString,
      file_pattern: filePattern,
    } = parseAndValidateArgs(args);
  
    const searchRegex = compileSearchRegex(regexString);
    const allResults: SearchResultItem[] = [];
  
    try {
      const filesToSearch = await findFilesToSearch(deps, relativePath, filePattern);
  
      const searchPromises = filesToSearch.map((absoluteFilePath) =>
        searchFileContent({ deps, absoluteFilePath, searchRegex }),
      );
  
      const resultsPerFile = await Promise.all(searchPromises);
      // Flatten results (which now include potential errors)
      for (const fileResults of resultsPerFile) allResults.push(...fileResults);
    } catch (error: unknown) {
      // Errors from findFilesToSearch or Promise.all rejections (should be less likely now)
      if (error instanceof McpError) throw error;
  
      const errorMessage =
        error instanceof Error ? error.message : 'An unknown error occurred during file search.';
      // Error logged via McpError
      // Include a general error if the whole process fails unexpectedly
      allResults.push({ type: 'error', file: 'general', error: errorMessage });
      // Don't throw, return the collected results including the general error
      // throw new McpError(ErrorCode.InternalError, errorMessage);
    }
  
    // Return the structured data including matches and errors
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({ results: allResults }, undefined, 2),
        },
      ],
      data: {
        results: allResults,
      },
    };
  };

• src/handlers/search-files.ts:30-47 (schema)

  Zod input schema defining parameters: path (directory), regex (pattern), file_pattern (glob filter).

  export const SearchFilesArgsSchema = z
    .object({
      path: z
        .string()
        .optional()
        .default('.')
        .describe('Relative path of the directory to search in.'),
      regex: z
        .string()
        .min(1, { message: 'Regex pattern cannot be empty' })
        .describe('The regex pattern to search for.'),
      file_pattern: z
        .string()
        .optional()
        .default('*')
        .describe("Glob pattern to filter files (e.g., '*.ts'). Defaults to all files ('*')."),
    })
    .strict();

• src/handlers/search-files.ts:273-306 (registration)

  Tool definition object registering 'search_files' with name, description, input/output schemas, and handler wrapper that provides dependencies.

  export const searchFilesToolDefinition = {
    name: 'search_files',
    description:
      'Search for a regex pattern within files in a specified directory (read-only). Returns matches and any errors encountered.',
    inputSchema: SearchFilesArgsSchema,
    // Define output schema
    outputSchema: z.object({
      results: z.array(
        z.object({
          type: z.enum(['match', 'error']),
          file: z.string(),
          line: z.number().int().optional(),
          match: z.string().optional(),
          context: z.array(z.string()).optional(),
          error: z.string().optional(),
        }),
      ),
    }),
    // Use the imported local McpResponse type
    handler: (args: unknown): Promise<LocalMcpResponse> => {
      const deps: SearchFilesDependencies = {
        readFile: async (_path, _options) => {
          const encoding = typeof _options === 'string' ? _options : (_options?.encoding ?? 'utf8');
          return fsPromises.readFile(_path, { encoding });
        },
        glob: globFn,
        resolvePath: resolvePathUtil,
        PROJECT_ROOT: projectRootUtil,
        pathRelative: path.relative.bind(path),
        pathJoin: path.join.bind(path),
      };
      return handleSearchFilesFunc(deps, args);
    },
  };

• src/handlers/index.ts:48-91 (registration)

  Central registry aggregating all tool definitions, including searchFilesToolDefinition (line 59 in original file).

  export const allToolDefinitions: HandlerToolDefinition[] = [
    listFilesToolDefinition,
    statItemsToolDefinition,
    readContentToolDefinition,
    writeContentToolDefinition,
    deleteItemsToolDefinition,
    createDirectoriesToolDefinition,
    chmodItemsToolDefinition,
    chownItemsToolDefinition,
    moveItemsToolDefinition,
    copyItemsToolDefinition,
    searchFilesToolDefinition,
    replaceContentToolDefinition,
    {
      name: 'apply_diff',
      description: 'Apply diffs to files',
      inputSchema: applyDiffInputSchema,
      handler: async (args: unknown): Promise<McpToolResponse> => {
        const validatedArgs = applyDiffInputSchema.parse(args);
        const result: ApplyDiffOutput = await handleApplyDiff(validatedArgs.changes, {
          readFile: async (path: string) => fs.promises.readFile(path, 'utf8'),
          writeFile: async (path: string, content: string) =>
            fs.promises.writeFile(path, content, 'utf8'),
          path,
          projectRoot: process.cwd(),
        });
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  success: result.success,
                  results: result.results,
                },
                undefined,
                2,
              ),
            },
          ],
        };
      },
    },
  ];

• src/handlers/index.ts:11-11 (registration)

  Import of the search_files tool definition for inclusion in the central registry.

  import { searchFilesToolDefinition } from './search-files.js';