ls
List files and directories within a repository to inspect project structure and contents. Supports branch isolation for secure file browsing in build environments.
Instructions
List files and directories in a repository. Limited to paths within the repository to prevent path traversal. If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments to pass to ls (e.g., '-la', '-lh build/') | |
| repo | Yes | Repository name (required) | |
| branch | No | Git branch name (optional). If provided, uses isolated worktree. |
Implementation Reference
- src/server.py:521-537 (handler)The handler function for the 'ls' MCP tool. Extracts arguments, validates them using validate_ls_args, constructs the 'ls' command by splitting args with shlex, executes it via execute_in_worktree in the repository's worktree (creating if needed for branch), and returns the formatted output.async def handle_ls(self, args: Dict[str, Any]) -> List[TextContent]: """Handle ls command""" repo = args.get("repo") branch = args.get("branch") ls_args = args.get("args", "") # Validate arguments validate_ls_args(ls_args) # Build command cmd = ["ls"] if ls_args: cmd.extend(shlex.split(ls_args)) # Execute in appropriate worktree with locking result = await self.execute_in_worktree(repo, branch, cmd) return [TextContent(type="text", text=result)]
- src/server.py:372-395 (registration)Registers the 'ls' tool in the MCP list_tools response, providing name, description, and input schema requiring 'repo' (optional 'args' and 'branch'). This defines the tool's interface.Tool( name="ls", description="List files and directories in a repository. " "Limited to paths within the repository to prevent path traversal. " "If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.", inputSchema={ "type": "object", "properties": { "args": { "type": "string", "description": "Arguments to pass to ls (e.g., '-la', '-lh build/')" }, "repo": { "type": "string", "description": "Repository name (required)" }, "branch": { "type": "string", "description": "Git branch name (optional). If provided, uses isolated worktree." } }, "required": ["repo"] } ),
- src/server.py:377-393 (schema)JSON schema defining the input parameters for the 'ls' tool: 'repo' (required string), 'args' (optional string for ls flags/paths), 'branch' (optional string).inputSchema={ "type": "object", "properties": { "args": { "type": "string", "description": "Arguments to pass to ls (e.g., '-la', '-lh build/')" }, "repo": { "type": "string", "description": "Repository name (required)" }, "branch": { "type": "string", "description": "Git branch name (optional). If provided, uses isolated worktree." } }, "required": ["repo"]
- src/validators.py:141-170 (helper)Validates 'ls' arguments: checks for dangerous patterns, parses parts, validates non-flag parts as paths using validate_path, and checks ls flags match ^-[a-zA-Z]+$. Called before executing the command.def validate_ls_args(args: str) -> None: """ Validate ls command arguments Args: args: Ls command arguments Raises: ValueError: If arguments contain dangerous patterns """ if not args: return # Empty args is fine (will list current directory) # Check for dangerous patterns if contains_dangerous_pattern(args): raise ValueError(f"Ls arguments contain dangerous patterns: {args}") # Parse arguments to validate paths parts = args.split() for part in parts: # Skip flags (starting with -) if part.startswith('-'): # Validate flag is reasonable if not re.match(r'^-[a-zA-Z]+$', part): raise ValueError(f"Invalid ls flag: {part}") continue # Validate paths validate_path(part)