MCP Build Environment Service

Instructions

Implementation Reference

• src/server.py:552-627 (handler)

  The core handler function `handle_read_file` that implements the read_file tool logic: extracts arguments, gets repo worktree path with locking, validates file path using helper, reads file content with optional start_line/end_line range, formats output with line numbers, total lines, and file metadata.
  async def handle_read_file(self, args: Dict[str, Any]) -> List[TextContent]: """Handle read_file command""" repo = args.get("repo") branch = args.get("branch") file_path = args.get("path") start_line = args.get("start_line") end_line = args.get("end_line") if not file_path: raise ValueError("File path is required") # Get working path with locking lock_key = self._get_lock_key(repo, branch) async with self.worktree_locks[lock_key]: repo_path = await self.get_working_path(repo, branch) # Validate and resolve the file path validated_path = validate_file_path(file_path, repo_path) # Read the file try: with open(validated_path, 'r', encoding='utf-8', errors='replace') as f: if start_line is not None or end_line is not None: # Read specific line range lines = f.readlines() total_lines = len(lines) # Validate line numbers if start_line is not None and start_line < 1: raise ValueError(f"start_line must be >= 1, got {start_line}") if end_line is not None and end_line < 1: raise ValueError(f"end_line must be >= 1, got {end_line}") if start_line is not None and end_line is not None and start_line > end_line: raise ValueError(f"start_line ({start_line}) must be <= end_line ({end_line})") # Default values start_idx = (start_line - 1) if start_line is not None else 0 end_idx = end_line if end_line is not None else total_lines # Clamp to valid range start_idx = max(0, min(start_idx, total_lines)) end_idx = max(0, min(end_idx, total_lines)) # Extract the requested lines selected_lines = lines[start_idx:end_idx] # Format output with line numbers output = f"File: {validated_path}\n" output += f"Lines {start_idx + 1}-{end_idx} of {total_lines}\n" output += "=" * 80 + "\n" for i, line in enumerate(selected_lines, start=start_idx + 1): output += f"{i:6d}: {line.rstrip()}\n" return [TextContent(type="text", text=output)] else: # Read entire file content = f.read() lines_count = content.count('\n') + (1 if content and not content.endswith('\n') else 0) output = f"File: {validated_path}\n" output += f"Total lines: {lines_count}\n" output += "=" * 80 + "\n" # Add line numbers to entire file for i, line in enumerate(content.splitlines(), start=1): output += f"{i:6d}: {line}\n" return [TextContent(type="text", text=output)] except FileNotFoundError: raise FileNotFoundError(f"File not found: {validated_path}") except PermissionError: raise PermissionError(f"Permission denied reading file: {validated_path}") except Exception as e: raise Exception(f"Error reading file {validated_path}: {str(e)}")
• src/server.py:396-447 (schema)

  The JSON inputSchema and Tool metadata definition for the read_file tool, returned by the list_tools() MCP method to register the tool's schema and description.
  Tool( name="env", description="Show environment information including environment variables " "and versions of key build tools (gcc, g++, python, make, cmake, etc.). " "If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.", inputSchema={ "type": "object", "properties": { "repo": { "type": "string", "description": "Repository name (required)" }, "branch": { "type": "string", "description": "Git branch name (optional). If provided, uses isolated worktree." } }, "required": ["repo"] } ), Tool( name="read_file", description="Read the contents of a file in a repository. " "Supports reading specific line ranges for large files. " "If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.", inputSchema={ "type": "object", "properties": { "repo": { "type": "string", "description": "Repository name (required)" }, "path": { "type": "string", "description": "Absolute path to the file to read (required)" }, "start_line": { "type": "integer", "description": "Starting line number (1-indexed, optional). If provided, only lines from start_line to end_line will be returned." }, "end_line": { "type": "integer", "description": "Ending line number (1-indexed, optional). If provided, only lines from start_line to end_line will be returned." }, "branch": { "type": "string", "description": "Git branch name (optional). If provided, uses isolated worktree." } }, "required": ["repo", "path"] } )
• src/server.py:463-466 (registration)

  Dispatch/registration logic in the call_tool() MCP handler that routes calls to the 'read_file' tool to its specific handler function.
  elif name == "read_file": return await self.handle_read_file(arguments) else: raise ValueError(f"Unknown tool: {name}")
• src/validators.py:172-242 (helper)

  Supporting helper `validate_file_path` that ensures the requested file path resolves within the repository root, blocks command injection patterns and path traversal attempts (used at line 569 in handler).
  def validate_file_path(file_path: str, repo_path: Path) -> Path: """ Validate a file path for reading and ensure it's within the repository. This validator accepts both absolute and relative paths but ensures that the final resolved path is within the repository directory. Args: file_path: The file path to validate (can be absolute or relative) repo_path: The repository root path Returns: Path: The validated absolute path to the file Raises: ValueError: If path contains dangerous patterns or escapes the repository """ if not file_path: raise ValueError("File path cannot be empty") # Check for dangerous command injection patterns # We're less strict than validate_path since we're only reading files dangerous_for_file_read = [ r";", # Command chaining r"\|", # Pipes r"&", # Background/chaining r"`", # Command substitution r"\$\(", # Command substitution ] for pattern in dangerous_for_file_read: if re.search(pattern, file_path): raise ValueError(f"File path contains dangerous pattern: {file_path}") # Convert to Path object path_obj = Path(file_path) # Resolve the path to absolute if path_obj.is_absolute(): # Absolute path - resolve it resolved_path = path_obj.resolve() else: # Relative path - resolve relative to repo resolved_path = (repo_path / path_obj).resolve() # Ensure the resolved path is within the repository repo_path_resolved = repo_path.resolve() try: # This will raise ValueError if resolved_path is not relative to repo_path resolved_path.relative_to(repo_path_resolved) except ValueError: raise ValueError( f"Access denied: Path '{file_path}' resolves to '{resolved_path}' " f"which is outside repository '{repo_path_resolved}'" ) # Additional check: ensure no parent directory traversal in original path # This catches things like "foo/../../etc/passwd" even if they resolve safely if ".." in path_obj.parts: # But we need to verify it doesn't escape try: if path_obj.is_absolute(): check_path = path_obj.resolve() else: check_path = (repo_path / path_obj).resolve() check_path.relative_to(repo_path_resolved) except ValueError: raise ValueError(f"Path traversal not allowed: {file_path}") return resolved_path