Windows System MCP

Instructions

Implementation Reference

• src/tools/filesystem.ts:46-80 (handler)

  The main execution handler for the 'filesystem' tool. It processes the input arguments, dispatches to specific sub-methods based on the 'action' parameter, and handles errors.

  async run(args: {
    action: string;
    path?: string;
    pattern?: string;
    recursive?: boolean;
    max_depth?: number;
    size_threshold?: number;
  }) {
    try {
      switch (args.action) {
        case "list_directory":
          return await this.listDirectory(args.path || "C:\\", args.recursive, args.max_depth);
        case "read_file":
          return await this.readFile(args.path!);
        case "search_files":
          return await this.searchFiles(args.pattern!, args.path, args.recursive);
        case "get_file_info":
          return await this.getFileInfo(args.path!);
        case "find_large_files":
          return await this.findLargeFiles(args.path || "C:\\", args.size_threshold!);
        case "get_disk_usage":
          return await this.getDiskUsage();
        default:
          throw new Error(`Unknown action: ${args.action}`);
      }
    } catch (error: any) {
      return {
        content: [{
          type: "text",
          text: `❌ File system operation failed: ${error.message}`
        }],
        isError: true
      };
    }
  },

• src/tools/filesystem.ts:11-44 (schema)

  The input schema defining the parameters accepted by the 'filesystem' tool, including action types and optional parameters.

  parameters: {
    type: "object",
    properties: {
      action: {
        type: "string",
        enum: ["list_directory", "read_file", "search_files", "get_file_info", "find_large_files", "get_disk_usage"],
        description: "The file system action to perform"
      },
      path: {
        type: "string",
        description: "File or directory path (required for most actions)"
      },
      pattern: {
        type: "string",
        description: "Search pattern for file searching (supports wildcards)"
      },
      recursive: {
        type: "boolean",
        description: "Whether to search recursively (default: false)",
        default: false
      },
      max_depth: {
        type: "number",
        description: "Maximum depth for recursive operations (default: 3)",
        default: 3
      },
      size_threshold: {
        type: "number",
        description: "Size threshold in MB for finding large files (default: 100)",
        default: 100
      }
    },
    required: ["action"]
  },

• src/index.ts:27-31 (registration)

  Registration of the 'filesystem' tool in the MCP server's list of available tools.

  {
    name: fileSystemTool.name,
    description: fileSystemTool.description,
    inputSchema: fileSystemTool.parameters
  },

• src/index.ts:71-72 (registration)

  Dispatch handler in the MCP server that routes calls to the 'filesystem' tool to its run method.

  case "filesystem":
    return await fileSystemTool.run(args as any);

• src/tools/filesystem.ts:82-135 (helper)

  Helper method for listing directory contents, used by the 'list_directory' action.

  async listDirectory(dirPath: string, recursive = false, maxDepth = 3) {
    try {
      const items = await fs.readdir(dirPath, { withFileTypes: true });
      let result = `# Directory Listing: ${dirPath}\n\n`;
      
      const directories: string[] = [];
      const files: string[] = [];
      
      for (const item of items) {
        const fullPath = path.join(dirPath, item.name);
        try {
          const stats = await fs.stat(fullPath);
          const size = item.isFile() ? this.formatFileSize(stats.size) : "";
          const modified = stats.mtime.toISOString().split('T')[0];
          
          if (item.isDirectory()) {
            directories.push(`📁 ${item.name}/ (${modified})`);
          } else {
            files.push(`📄 ${item.name} (${size}, ${modified})`);
          }
        } catch {
          if (item.isDirectory()) {
            directories.push(`📁 ${item.name}/ (access denied)`);
          } else {
            files.push(`📄 ${item.name} (access denied)`);
          }
        }
      }
      
      result += "## Directories:\n" + directories.join("\n") + "\n\n";
      result += "## Files:\n" + files.join("\n");
      
      if (recursive && maxDepth > 0) {
        result += "\n\n## Subdirectories (recursive):\n";
        for (const item of items) {
          if (item.isDirectory()) {
            try {
              const subPath = path.join(dirPath, item.name);
              const subResult = await this.listDirectory(subPath, true, maxDepth - 1);
              result += `\n### ${item.name}/\n${subResult.content[0].text}\n`;
            } catch {
              result += `\n### ${item.name}/ (access denied)\n`;
            }
          }
        }
      }
      
      return {
        content: [{ type: "text", text: result }]
      };
    } catch (error: any) {
      throw new Error(`Cannot list directory ${dirPath}: ${error.message}`);
    }
  },