Filesystem MCP Server

Instructions

Implementation Reference

• src/index.ts:372-409 (handler)

  Handler for 'search_files' tool: extracts arguments, validates path, performs recursive directory traversal using fs.readdir and fs.stat, matches entry names against case-insensitive RegExp pattern, collects full paths of matches, returns as newline-separated text content.

  case 'search_files': {
    const { path: dirPath, pattern } = request.params.arguments as { 
      path: string; 
      pattern: string 
    };
    validatePath(dirPath);
    
    const results: string[] = [];
    const patternRegex = new RegExp(pattern, 'i');
    
    async function searchDirectory(currentPath: string) {
      const entries = await fs.readdir(currentPath);
      
      for (const entry of entries) {
        const entryPath = path.join(currentPath, entry);
        const stats = await fs.stat(entryPath);
        
        if (patternRegex.test(entry)) {
          results.push(entryPath);
        }
        
        if (stats.isDirectory()) {
          await searchDirectory(entryPath);
        }
      }
    }
    
    await searchDirectory(dirPath);
    
    return {
      content: [
        {
          type: 'text',
          text: results.join('\n'),
        },
      ],
    };
  }

• src/index.ts:190-207 (schema)

  Schema definition in ListTools response for 'search_files' tool, defining input schema with required 'path' (starting directory) and 'pattern' (case-insensitive search pattern).

  {
    name: 'search_files',
    description: 'Recursively search for files/directories',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'Starting directory for search',
        },
        pattern: {
          type: 'string',
          description: 'Search pattern (case-insensitive)',
        },
      },
      required: ['path', 'pattern'],
    },
  },

• src/index.ts:93-232 (registration)

  The tool is registered by including its details in the tools array returned by the ListToolsRequest handler.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'read_file',
        description: 'Read complete contents of a file',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Path to the file to read',
            },
          },
          required: ['path'],
        },
      },
      {
        name: 'read_multiple_files',
        description: 'Read multiple files simultaneously',
        inputSchema: {
          type: 'object',
          properties: {
            paths: {
              type: 'array',
              items: {
                type: 'string',
              },
              description: 'Array of file paths to read',
            },
          },
          required: ['paths'],
        },
      },
      {
        name: 'write_file',
        description: 'Create new file or overwrite existing',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Path to the file to write',
            },
            content: {
              type: 'string',
              description: 'Content to write to the file',
            },
          },
          required: ['path', 'content'],
        },
      },
      {
        name: 'create_directory',
        description: 'Create new directory or ensure it exists',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Path to the directory to create',
            },
          },
          required: ['path'],
        },
      },
      {
        name: 'list_directory',
        description: 'List directory contents with [FILE] or [DIR] prefixes',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Path to the directory to list',
            },
          },
          required: ['path'],
        },
      },
      {
        name: 'move_file',
        description: 'Move or rename files and directories',
        inputSchema: {
          type: 'object',
          properties: {
            source: {
              type: 'string',
              description: 'Source path',
            },
            destination: {
              type: 'string',
              description: 'Destination path',
            },
          },
          required: ['source', 'destination'],
        },
      },
      {
        name: 'search_files',
        description: 'Recursively search for files/directories',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Starting directory for search',
            },
            pattern: {
              type: 'string',
              description: 'Search pattern (case-insensitive)',
            },
          },
          required: ['path', 'pattern'],
        },
      },
      {
        name: 'get_file_info',
        description: 'Get detailed file/directory metadata',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Path to the file or directory',
            },
          },
          required: ['path'],
        },
      },
      {
        name: 'list_allowed_directories',
        description: 'List all directories the server is allowed to access',
        inputSchema: {
          type: 'object',
          properties: {},
          required: [],
        },
      },
    ],
  }));