Apktool MCP Server

Instructions

Implementation Reference

• apktool_mcp_server.py:797-931 (handler)

  The handler function implementing the list_resources tool. Lists resources from an APKTool decoded project directory, either all resource types with counts or files in a specific resource type directory. Supports pagination via offset and count parameters. Includes input validation and detailed error handling.
  async def list_resources( project_dir: str, resource_type: Optional[str] = None, offset: int = 0, count: int = 0 ) -> Dict: """ List resources with pagination support and enhanced metadata. Args: project_dir: Path to the APKTool project directory resource_type: Optional resource type to filter by (e.g., "layout", "drawable") offset: Starting offset for pagination count: Number of items to return (0 means use default) Returns: Paginated dictionary with list of resources and metadata """ # Input validation path_validation = ValidationUtils.validate_path(project_dir, must_exist=True) if not path_validation["valid"]: return {"success": False, "error": path_validation["error"]} res_path = os.path.join(project_dir, "res") if not os.path.exists(res_path): return { "success": False, "error": f"Resources directory not found: {res_path}" } try: if resource_type: # List resources of specific type type_path = os.path.join(res_path, resource_type) if not os.path.exists(type_path): # Get available resource types resource_types = [ d for d in os.listdir(res_path) if os.path.isdir(os.path.join(res_path, d)) ] return { "success": False, "error": f"Resource type directory not found: {resource_type}", "available_types": resource_types } resources = [] for item in os.listdir(type_path): item_path = os.path.join(type_path, item) if os.path.isfile(item_path): resources.append({ "name": item, "path": item_path, "size": os.path.getsize(item_path), "type": resource_type, "extension": os.path.splitext(item)[1], "modified_time": os.path.getmtime(item_path) }) # Sort by name resources.sort(key=lambda x: x["name"]) # Apply pagination paginated_result = PaginationUtils.handle_pagination( items=resources, offset=offset, count=count, data_type="resources", items_key="resources" ) paginated_result["success"] = True paginated_result["resource_type"] = resource_type paginated_result["resource_path"] = type_path return paginated_result else: # List all resource types with counts resource_types = [] for item in os.listdir(res_path): type_path = os.path.join(res_path, item) if os.path.isdir(type_path): try: files = [f for f in os.listdir(type_path) if os.path.isfile(os.path.join(type_path, f))] resource_count = len(files) # Calculate total size total_size = 0 for f in files: try: total_size += os.path.getsize(os.path.join(type_path, f)) except: pass resource_types.append({ "type": item, "path": type_path, "count": resource_count, "total_size": total_size }) except Exception as e: logger.warning(f"Error processing resource type {item}: {e}") resource_types.append({ "type": item, "path": type_path, "count": 0, "total_size": 0, "error": str(e) }) # Sort by type name resource_types.sort(key=lambda x: x["type"]) # Apply pagination paginated_result = PaginationUtils.handle_pagination( items=resource_types, offset=offset, count=count, data_type="resource-types", items_key="resource_types" ) paginated_result["success"] = True return paginated_result except Exception as e: logger.error(f"Error listing resources: {str(e)}") return { "success": False, "error": f"Failed to list resources: {str(e)}" }
• apktool_mcp_server.py:797-797 (registration)

  The @mcp.tool() decorator registers the list_resources function as an MCP tool.
  async def list_resources(
• apktool_mcp_server.py:50-142 (helper)

  PaginationUtils class providing handle_pagination method used by list_resources for paginated responses.
  class PaginationUtils: """Utility class for handling pagination across different MCP tools""" # Configuration constants DEFAULT_PAGE_SIZE = 100 MAX_PAGE_SIZE = 10000 MAX_OFFSET = 1000000 @staticmethod def validate_pagination_params(offset: int, count: int) -> tuple[int, int]: """Validate and normalize pagination parameters""" offset = max(0, min(offset, PaginationUtils.MAX_OFFSET)) count = max(0, min(count, PaginationUtils.MAX_PAGE_SIZE)) return offset, count @staticmethod def handle_pagination( items: List[Any], offset: int = 0, count: int = 0, data_type: str = "paginated-list", items_key: str = "items", item_transformer: Optional[Callable[[Any], Any]] = None ) -> Dict[str, Any]: """ Generic pagination handler for list data Args: items: List of items to paginate offset: Starting offset count: Number of items to return (0 means use default) data_type: Type identifier for the response items_key: Key name for items in response item_transformer: Optional function to transform items Returns: Paginated response dictionary """ if items is None: items = [] total_items = len(items) # Validate parameters offset, count = PaginationUtils.validate_pagination_params(offset, count) # Determine effective limit if count == 0: effective_limit = min(PaginationUtils.DEFAULT_PAGE_SIZE, max(0, total_items - offset)) else: effective_limit = min(count, max(0, total_items - offset)) # Calculate bounds start_index = min(offset, total_items) end_index = min(start_index + effective_limit, total_items) has_more = end_index < total_items # Extract and transform paginated subset paginated_items = items[start_index:end_index] if item_transformer: paginated_items = [item_transformer(item) for item in paginated_items] # Build response result = { "type": data_type, items_key: paginated_items, "pagination": { "total": total_items, "offset": offset, "limit": effective_limit, "count": len(paginated_items), "has_more": has_more } } # Add navigation helpers if has_more: result["pagination"]["next_offset"] = end_index if offset > 0: prev_offset = max(0, offset - effective_limit) result["pagination"]["prev_offset"] = prev_offset # Page calculations if effective_limit > 0: current_page = (offset // effective_limit) + 1 total_pages = (total_items + effective_limit - 1) // effective_limit result["pagination"]["current_page"] = current_page result["pagination"]["total_pages"] = total_pages result["pagination"]["page_size"] = effective_limit return result
• apktool_mcp_server.py:143-178 (helper)

  ValidationUtils class providing validate_path used at the start of list_resources for input validation.
  class ValidationUtils: """Utility class for input validation""" @staticmethod def validate_path(path: str, must_exist: bool = True) -> Dict[str, Union[bool, str]]: """Validate file/directory path""" if not path or not isinstance(path, str): return {"valid": False, "error": "Path cannot be empty"} if must_exist and not os.path.exists(path): return {"valid": False, "error": f"Path does not exist: {path}"} return {"valid": True} @staticmethod def validate_class_name(class_name: str) -> Dict[str, Union[bool, str]]: """Validate Java class name format""" if not class_name or not isinstance(class_name, str): return {"valid": False, "error": "Class name cannot be empty"} if not class_name.replace('.', '').replace('_', '').replace('$', '').replace('/', '').isalnum(): return {"valid": False, "error": "Invalid class name format"} return {"valid": True} @staticmethod def validate_search_pattern(pattern: str) -> Dict[str, Union[bool, str]]: """Validate search pattern""" if not pattern or not isinstance(pattern, str): return {"valid": False, "error": "Search pattern cannot be empty"} if len(pattern) > 1000: return {"valid": False, "error": "Search pattern too long (max 1000 characters)"} return {"valid": True}