universal-mcp-applications 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

universal_mcp/applications/google_docs/app.py

@@ -11,18 +11,18 @@ class GoogleDocsApp(APIApplication):
 
     def create_document(self, title: str) -> dict[str, Any]:
         """
-        Creates a new blank Google Document with the specified title and returns the API response.
-
+        Creates a new, blank Google Document with a specified title via a POST request to the Google Docs API. It returns the API response containing the new document's metadata, including its ID, which is necessary for other functions like `add_content` or `get_document` to interact with it.
+        
         Args:
             title: The title for the new Google Document to be created
-
+        
         Returns:
             A dictionary containing the Google Docs API response with document details and metadata
-
+        
         Raises:
             HTTPError: If the API request fails due to network issues, authentication errors, or invalid parameters
             RequestException: If there are connection errors or timeout issues during the API request
-
+        
         Tags:
             create, document, api, important, google-docs, http
         """
@@ -34,18 +34,18 @@ class GoogleDocsApp(APIApplication):
 
     def get_document(self, document_id: str) -> dict[str, Any]:
         """
-        Retrieves the latest version of a specified document from the Google Docs API.
-
+        Retrieves the complete content and metadata for a specific Google Document by its unique ID. This function queries the Google Docs API and returns the full JSON response, representing the document's latest version. It's the primary read operation, contrasting with `create_document` which creates new ones.
+        
         Args:
             document_id: The unique identifier of the document to retrieve
-
+        
         Returns:
             A dictionary containing the document data from the Google Docs API response
-
+        
         Raises:
             HTTPError: If the API request fails or the document is not found
             JSONDecodeError: If the API response cannot be parsed as JSON
-
+        
         Tags:
             retrieve, read, api, document, google-docs, important
         """
@@ -53,24 +53,24 @@ class GoogleDocsApp(APIApplication):
         response = self._get(url)
         return response.json()
 
-    def add_content(
+    def insert_text(
         self, document_id: str, content: str, index: int = 1
     ) -> dict[str, Any]:
         """
-        Adds text content at a specified position in an existing Google Document via the Google Docs API.
-
+        Inserts a string of text at a specified index in an existing Google Document using the `batchUpdate` API. This function specifically adds new textual content, distinguishing it from functions that insert tables or apply styling to existing text.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             content: The text content to be inserted into the document
             index: The zero-based position in the document where the text should be inserted (default: 1)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the batch update operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             update, insert, document, api, google-docs, batch, content-management, important
         """
@@ -84,7 +84,7 @@ class GoogleDocsApp(APIApplication):
         response.raise_for_status()
         return response.json()
 
-    def style_text(
+    def apply_text_style(
         self,
         document_id: str,
         start_index: int,
@@ -98,8 +98,8 @@ class GoogleDocsApp(APIApplication):
         background_color: dict[str, float] | None = None,
     ) -> dict[str, Any]:
         """
-        Simplified text styling for Google Document - handles most common cases.
-
+        Applies character-level formatting such as bold, italic, font size, color, and hyperlinks to a specified text range in a document. This function modifies text appearance, distinguishing it from `update_paragraph_style`, which handles block-level formatting like alignment and headings.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             start_index: The zero-based start index of the text range to style
@@ -111,14 +111,14 @@ class GoogleDocsApp(APIApplication):
             link_url: URL to make the text a hyperlink
             foreground_color: RGB color dict with 'red', 'green', 'blue' values (0.0 to 1.0)
             background_color: RGB color dict with 'red', 'green', 'blue' values (0.0 to 1.0)
-
+        
         Returns:
             A dictionary containing the Google Docs API response
-
+        
         Raises:
             HTTPError: When the API request fails
             RequestException: When there are network connectivity issues
-
+        
         Tags:
             style, format, text, document, api, google-docs, simple
         """
@@ -204,8 +204,8 @@ class GoogleDocsApp(APIApplication):
         tab_id: str | None = None,
     ) -> dict[str, Any]:
         """
-        Updates paragraph styling for a specified range in a Google Document.
-
+        Applies paragraph formatting, such as named styles ('TITLE', 'HEADING_1'), alignment, and text direction, to a specified range in a Google Document. It selectively updates only the provided style attributes, distinguishing it from `style_text`, which handles character-level formatting like bolding or italics.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             start_index: The zero-based start index of the paragraph range to style
@@ -216,14 +216,14 @@ class GoogleDocsApp(APIApplication):
             spacing_mode: The spacing mode ('NEVER_COLLAPSE', 'COLLAPSE_LISTS')
             segment_id: The segment ID for the range (optional)
             tab_id: The tab ID for the range (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response
-
+        
         Raises:
             HTTPError: When the API request fails
             RequestException: When there are network connectivity issues
-
+        
         Tags:
             style, format, paragraph, document, api, google-docs, batch, content-management
         """
@@ -277,7 +277,7 @@ class GoogleDocsApp(APIApplication):
         response = self._post(url, data=batch_update_data)
         return self._handle_response(response)
 
-    def delete_content(
+    def delete_content_range(
         self,
         document_id: str,
         start_index: int,
@@ -286,22 +286,22 @@ class GoogleDocsApp(APIApplication):
         tab_id: str | None = None,
     ) -> dict[str, Any]:
         """
-        Deletes content from a specified range in a Google Document.
-
+        Deletes content within a specified range in a Google Document via a `batchUpdate` API call. The function targets a range defined by start and end indexes and can operate within optional segments like headers or footers, returning the API's response after the deletion operation.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             start_index: The zero-based start index of the content range to delete
             end_index: The zero-based end index of the content range to delete (exclusive)
             segment_id: The ID of the header, footer, or footnote segment (optional)
             tab_id: The ID of the tab containing the content to delete (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the delete operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             delete, remove, content, document, api, google-docs, batch, content-management, important
         """
@@ -333,8 +333,8 @@ class GoogleDocsApp(APIApplication):
         tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Inserts a table at the specified location in a Google Document.
-
+        Inserts a table with specified row and column dimensions at a given location in a Google Document. It uses the `batchUpdate` API endpoint for precise placement within the document's body, header, or footer, returning the API response.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             location_index: The zero-based index where the table should be inserted
@@ -342,14 +342,14 @@ class GoogleDocsApp(APIApplication):
             columns: The number of columns in the table
             segment_id: The ID of the header, footer or footnote segment (optional)
             tab_id: The ID of the tab containing the location (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the insert table operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             table, insert, document, api, google-docs, batch, content-management
         """
@@ -390,22 +390,22 @@ class GoogleDocsApp(APIApplication):
         section_break_tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Creates a Footer in a Google Document.
-
+        Creates a footer of a specified type in a Google Document via the batch update API. The footer can optionally be associated with a specific section break, enabling distinct footers for different document sections, distinguishing it from `create_header`.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             footer_type: The type of footer to create (DEFAULT, HEADER_FOOTER_TYPE_UNSPECIFIED)
             section_break_location_index: The index of the SectionBreak location (optional)
             section_break_segment_id: The segment ID of the SectionBreak location (optional)
             section_break_tab_id: The tab ID of the SectionBreak location (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the create footer operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             footer, create, document, api, google-docs, batch, content-management
         """
@@ -442,8 +442,8 @@ class GoogleDocsApp(APIApplication):
         end_of_segment_tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Creates a Footnote segment and inserts a new FootnoteReference at the given location.
-
+        Creates a footnote segment and inserts a corresponding reference into a Google Document via the API's batch update. The reference can be placed at a specific index or at the end of a document segment. Unlike `create_footer`, this adds a numbered citation within the document body.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             location_index: The index where to insert the footnote reference (optional)
@@ -452,14 +452,14 @@ class GoogleDocsApp(APIApplication):
             end_of_segment_location: Whether to insert at end of segment (optional)
             end_of_segment_segment_id: The segment ID for end of segment location (optional)
             end_of_segment_tab_id: The tab ID for end of segment location (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the create footnote operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             footnote, create, document, api, google-docs, batch, content-management
         """
@@ -505,20 +505,20 @@ class GoogleDocsApp(APIApplication):
         tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Deletes a Footer from the document.
-
+        Deletes a specific footer from a Google Document using its unique ID (`footer_id`). This function constructs and sends a `deleteFooter` request to the Google Docs API's batch update endpoint, optionally targeting a footer within a specific document tab.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             footer_id: The ID of the footer to delete
             tab_id: The tab that contains the footer to delete (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the delete footer operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             footer, delete, remove, document, api, google-docs, batch, content-management
         """
@@ -545,22 +545,22 @@ class GoogleDocsApp(APIApplication):
         section_break_tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Creates a Header in a Google Document.
-
+        Creates a header in a specified Google Document via the batchUpdate API endpoint. This function allows defining the header type and can optionally associate it with a specific section break location. It complements the `delete_header` and `create_footer` functions for managing document structure.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             header_type: The type of header to create (DEFAULT, HEADER_FOOTER_TYPE_UNSPECIFIED)
             section_break_location_index: The index of the SectionBreak location (optional)
             section_break_segment_id: The segment ID of the SectionBreak location (optional)
             section_break_tab_id: The tab ID of the SectionBreak location (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the create header operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             header, create, document, api, google-docs, batch, content-management, important
         """
@@ -593,20 +593,20 @@ class GoogleDocsApp(APIApplication):
         tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Deletes a Header from the document.
-
+        Removes a specific header from a Google Document using its unique ID. This function constructs and sends a `deleteHeader` request to the Google Docs API's batch update endpoint, acting as the direct counterpart to the `create_header` function.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             header_id: The ID of the header to delete
             tab_id: The tab containing the header to delete (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the delete header operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             header, delete, remove, document, api, google-docs, batch, content-management
         """
@@ -624,7 +624,7 @@ class GoogleDocsApp(APIApplication):
         response = self._post(url, data=batch_update_data)
         return self._handle_response(response)
 
-    def create_paragraph_bullets(
+    def apply_list_style(
         self,
         document_id: str,
         start_index: int,
@@ -634,8 +634,8 @@ class GoogleDocsApp(APIApplication):
         tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Creates bullets for all of the paragraphs that overlap with the given range.
-
+        Applies a specified bulleted or numbered list format to paragraphs within a given range in a Google Document. The list style is determined by a predefined preset, covering various bullet glyphs and numbering schemes like 'BULLET_DISC_CIRCLE_SQUARE' or 'NUMBERED_DECIMAL_ALPHA_ROMAN'.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             start_index: The zero-based start index of the range to apply bullets to
@@ -659,14 +659,14 @@ class GoogleDocsApp(APIApplication):
                 - NUMBERED_ZERODECIMAL_ALPHA_ROMAN: ZERODECIMAL, ALPHA and ROMAN with periods
             segment_id: The segment ID for the range (optional)
             tab_id: The tab ID for the range (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the create bullets operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             bullets, list, paragraph, document, api, google-docs, batch, content-management
         """
@@ -704,22 +704,22 @@ class GoogleDocsApp(APIApplication):
         tab_id: str = None,
     ) -> dict[str, Any]:
         """
-        Deletes bullets from all of the paragraphs that overlap with the given range.
-
+        Removes bullet points or numbering from paragraphs within a specified range in a Google Document. This function uses the API's batch update feature to revert list formatting, acting as the direct counterpart to `create_paragraph_bullets` for removing list styles, rather than deleting text content.
+        
         Args:
             document_id: The unique identifier of the Google Document to be updated
             start_index: The zero-based start index of the range to remove bullets from
             end_index: The zero-based end index of the range to remove bullets from (exclusive)
             segment_id: The segment ID for the range (optional)
             tab_id: The tab ID for the range (optional)
-
+        
         Returns:
             A dictionary containing the Google Docs API response after performing the delete bullets operation
-
+        
         Raises:
             HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
             RequestException: When there are network connectivity issues or API endpoint problems
-
+        
         Tags:
             bullets, delete, remove, list, paragraph, document, api, google-docs, batch, content-management
         """
@@ -745,16 +745,16 @@ class GoogleDocsApp(APIApplication):
         return [
             self.create_document,
             self.get_document,
-            self.add_content,
-            self.style_text,
-            self.delete_content,
+            self.insert_text,
+            self.apply_text_style,
+            self.delete_content_range,
             self.insert_table,
             self.create_footer,
             self.create_footnote,
             self.delete_footer,
             self.create_header,
             self.delete_header,
-            self.create_paragraph_bullets,
+            self.apply_list_style,
             self.delete_paragraph_bullets,
             self.update_paragraph_style,
         ]