MCP Build Environment Service

Instructions

Implementation Reference

• src/server.py:521-537 (handler)

  The handler function that implements the core logic of the 'ls' tool: parses input arguments, validates them, constructs the 'ls' shell command, executes it within the specified repository worktree (handling branch-specific isolation and locking), and returns the 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 (schema)

  The tool schema definition returned by list_tools(), including name, description, and JSON inputSchema specifying required 'repo' and optional 'args'/'branch' parameters.

  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:459-460 (registration)

  Tool dispatch/registration in the central execute_tool() method, which routes 'ls' calls to the handle_ls handler.

  elif name == "ls":
      return await self.handle_ls(arguments)

• src/validators.py:141-171 (helper)

  Helper function validate_ls_args() that checks 'ls' arguments for dangerous patterns (path traversal, shell injection), validates flags, and sanitizes paths to prevent escapes.

  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)