universal-mcp-applications 0.1.1__py3-none-any.whl

universal_mcp/applications/twitter/api_segments/lists_api.py

@@ -0,0 +1,395 @@
+from typing import Any
+
+from .api_segment_base import APISegmentBase
+
+
+class ListsApi(APISegmentBase):
+    def __init__(self, main_app_client: Any):
+        super().__init__(main_app_client)
+
+    def list_id_create(
+        self, description=None, name=None, private=None
+    ) -> dict[str, Any]:
+        """
+
+        Creates a new Twitter list using the X API v2 and returns the newly created list's details.
+
+        Args:
+            description (string): description
+            name (string): name
+            private (boolean): private
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Lists
+        """
+        request_body_data = None
+        request_body_data = {
+            "description": description,
+            "name": name,
+            "private": private,
+        }
+        request_body_data = {
+            k: v for k, v in request_body_data.items() if v is not None
+        }
+        url = f"{self.main_app_client.base_url}/2/lists"
+        query_params = {}
+        response = self._post(
+            url,
+            data=request_body_data,
+            params=query_params,
+            content_type="application/json",
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def list_id_delete(self, id) -> dict[str, Any]:
+        """
+
+        Deletes a list specified by its ID using the DELETE method.
+
+        Args:
+            id (string): id
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Lists
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        url = f"{self.main_app_client.base_url}/2/lists/{id}"
+        query_params = {}
+        response = self._delete(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def list_id_get(
+        self, id, list_fields=None, expansions=None, user_fields=None
+    ) -> dict[str, Any]:
+        """
+
+        Retrieves detailed information about a specific Twitter List by its unique identifier, including optional expansions and fields for lists and users.
+
+        Args:
+            id (string): id
+            list_fields (array): A comma separated list of List fields to display. Example: "['created_at', 'description', 'follower_count', 'id', 'member_count', 'name', 'owner_id', 'private']".
+            expansions (array): A comma separated list of fields to expand. Example: "['owner_id']".
+            user_fields (array): A comma separated list of User fields to display. Example: "['affiliation', 'connection_status', 'created_at', 'description', 'entities', 'id', 'location', 'most_recent_tweet_id', 'name', 'pinned_tweet_id', 'profile_banner_url', 'profile_image_url', 'protected', 'public_metrics', 'receives_your_dm', 'subscription_type', 'url', 'username', 'verified', 'verified_type', 'withheld']".
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Lists
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        url = f"{self.main_app_client.base_url}/2/lists/{id}"
+        query_params = {
+            k: v
+            for k, v in [
+                ("list.fields", list_fields),
+                ("expansions", expansions),
+                ("user.fields", user_fields),
+            ]
+            if v is not None
+        }
+        response = self._get(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def list_id_update(
+        self, id, description=None, name=None, private=None
+    ) -> dict[str, Any]:
+        """
+
+        Updates a list specified by the ID using the provided JSON payload, authenticating with OAuth2 or user tokens.
+
+        Args:
+            id (string): id
+            description (string): description
+            name (string): name
+            private (boolean): private
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Lists
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        request_body_data = None
+        request_body_data = {
+            "description": description,
+            "name": name,
+            "private": private,
+        }
+        request_body_data = {
+            k: v for k, v in request_body_data.items() if v is not None
+        }
+        url = f"{self.main_app_client.base_url}/2/lists/{id}"
+        query_params = {}
+        response = self._put(
+            url,
+            data=request_body_data,
+            params=query_params,
+            content_type="application/json",
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def list_get_followers(
+        self,
+        id,
+        max_results=None,
+        pagination_token=None,
+        user_fields=None,
+        expansions=None,
+        tweet_fields=None,
+    ) -> dict[str, Any]:
+        """
+
+        Retrieves a list of users who follow a specified Twitter list using the list ID, with optional parameters for pagination and user data customization.
+
+        Args:
+            id (string): id
+            max_results (integer): Specifies the maximum number of follower results to return, with a default value of 100.
+            pagination_token (string): The pagination_token query parameter is an optional cursor used to retrieve the next page of results when paginating through the followers of a list.
+            user_fields (array): A comma separated list of User fields to display. Example: "['affiliation', 'connection_status', 'created_at', 'description', 'entities', 'id', 'location', 'most_recent_tweet_id', 'name', 'pinned_tweet_id', 'profile_banner_url', 'profile_image_url', 'protected', 'public_metrics', 'receives_your_dm', 'subscription_type', 'url', 'username', 'verified', 'verified_type', 'withheld']".
+            expansions (array): A comma separated list of fields to expand. Example: "['affiliation.user_id', 'most_recent_tweet_id', 'pinned_tweet_id']".
+            tweet_fields (array): A comma separated list of Tweet fields to display. Example: "['article', 'attachments', 'author_id', 'card_uri', 'context_annotations', 'conversation_id', 'created_at', 'edit_controls', 'edit_history_tweet_ids', 'entities', 'geo', 'id', 'in_reply_to_user_id', 'lang', 'non_public_metrics', 'note_tweet', 'organic_metrics', 'possibly_sensitive', 'promoted_metrics', 'public_metrics', 'referenced_tweets', 'reply_settings', 'scopes', 'source', 'text', 'username', 'withheld']".
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Users
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        url = f"{self.main_app_client.base_url}/2/lists/{id}/followers"
+        query_params = {
+            k: v
+            for k, v in [
+                ("max_results", max_results),
+                ("pagination_token", pagination_token),
+                ("user.fields", user_fields),
+                ("expansions", expansions),
+                ("tweet.fields", tweet_fields),
+            ]
+            if v is not None
+        }
+        response = self._get(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def list_get_members(
+        self,
+        id,
+        max_results=None,
+        pagination_token=None,
+        user_fields=None,
+        expansions=None,
+        tweet_fields=None,
+    ) -> dict[str, Any]:
+        """
+
+        Retrieves a list of User objects that are members of a specified Twitter List by the provided List ID.
+
+        Args:
+            id (string): id
+            max_results (integer): The maximum number of list members to return per page, defaulting to 100.
+            pagination_token (string): Optional token used for cursor-based pagination, allowing retrieval of the next subset of members in the list.
+            user_fields (array): A comma separated list of User fields to display. Example: "['affiliation', 'connection_status', 'created_at', 'description', 'entities', 'id', 'location', 'most_recent_tweet_id', 'name', 'pinned_tweet_id', 'profile_banner_url', 'profile_image_url', 'protected', 'public_metrics', 'receives_your_dm', 'subscription_type', 'url', 'username', 'verified', 'verified_type', 'withheld']".
+            expansions (array): A comma separated list of fields to expand. Example: "['affiliation.user_id', 'most_recent_tweet_id', 'pinned_tweet_id']".
+            tweet_fields (array): A comma separated list of Tweet fields to display. Example: "['article', 'attachments', 'author_id', 'card_uri', 'context_annotations', 'conversation_id', 'created_at', 'edit_controls', 'edit_history_tweet_ids', 'entities', 'geo', 'id', 'in_reply_to_user_id', 'lang', 'non_public_metrics', 'note_tweet', 'organic_metrics', 'possibly_sensitive', 'promoted_metrics', 'public_metrics', 'referenced_tweets', 'reply_settings', 'scopes', 'source', 'text', 'username', 'withheld']".
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Users
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        url = f"{self.main_app_client.base_url}/2/lists/{id}/members"
+        query_params = {
+            k: v
+            for k, v in [
+                ("max_results", max_results),
+                ("pagination_token", pagination_token),
+                ("user.fields", user_fields),
+                ("expansions", expansions),
+                ("tweet.fields", tweet_fields),
+            ]
+            if v is not None
+        }
+        response = self._get(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def list_add_member(self, id, user_id=None) -> dict[str, Any]:
+        """
+
+        Adds one or more members to a specified list by list ID using the POST method.
+
+        Args:
+            id (string): id
+            user_id (string): Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. Example: '2244994945'.
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Lists
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        request_body_data = None
+        request_body_data = {"user_id": user_id}
+        request_body_data = {
+            k: v for k, v in request_body_data.items() if v is not None
+        }
+        url = f"{self.main_app_client.base_url}/2/lists/{id}/members"
+        query_params = {}
+        response = self._post(
+            url,
+            data=request_body_data,
+            params=query_params,
+            content_type="application/json",
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def list_remove_member(self, id, user_id) -> dict[str, Any]:
+        """
+
+        Removes a member from a list using the provided list ID and user ID, requiring appropriate permissions for the operation.
+
+        Args:
+            id (string): id
+            user_id (string): user_id
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Lists
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        if user_id is None:
+            raise ValueError("Missing required parameter 'user_id'.")
+        url = f"{self.main_app_client.base_url}/2/lists/{id}/members/{user_id}"
+        query_params = {}
+        response = self._delete(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def lists_id_tweets(
+        self,
+        id,
+        max_results=None,
+        pagination_token=None,
+        tweet_fields=None,
+        expansions=None,
+        media_fields=None,
+        poll_fields=None,
+        user_fields=None,
+        place_fields=None,
+    ) -> dict[str, Any]:
+        """
+
+        Retrieves a list of tweets for a specified list by ID using the "GET" method, allowing optional parameters for pagination and field customization.
+
+        Args:
+            id (string): id
+            max_results (integer): The maximum number of tweets to return per request, with a default value of 100.
+            pagination_token (string): Optional query parameter used to request the next page of results by passing the `next_token` value from the previous response.
+            tweet_fields (array): A comma separated list of Tweet fields to display. Example: "['article', 'attachments', 'author_id', 'card_uri', 'context_annotations', 'conversation_id', 'created_at', 'edit_controls', 'edit_history_tweet_ids', 'entities', 'geo', 'id', 'in_reply_to_user_id', 'lang', 'non_public_metrics', 'note_tweet', 'organic_metrics', 'possibly_sensitive', 'promoted_metrics', 'public_metrics', 'referenced_tweets', 'reply_settings', 'scopes', 'source', 'text', 'username', 'withheld']".
+            expansions (array): A comma separated list of fields to expand. Example: "['article.cover_media', 'article.media_entities', 'attachments.media_keys', 'attachments.media_source_tweet', 'attachments.poll_ids', 'author_id', 'edit_history_tweet_ids', 'entities.mentions.username', 'geo.place_id', 'in_reply_to_user_id', 'entities.note.mentions.username', 'referenced_tweets.id', 'referenced_tweets.id.author_id', 'author_screen_name']".
+            media_fields (array): A comma separated list of Media fields to display. Example: "['alt_text', 'duration_ms', 'height', 'media_key', 'non_public_metrics', 'organic_metrics', 'preview_image_url', 'promoted_metrics', 'public_metrics', 'type', 'url', 'variants', 'width']".
+            poll_fields (array): A comma separated list of Poll fields to display. Example: "['duration_minutes', 'end_datetime', 'id', 'options', 'voting_status']".
+            user_fields (array): A comma separated list of User fields to display. Example: "['affiliation', 'connection_status', 'created_at', 'description', 'entities', 'id', 'location', 'most_recent_tweet_id', 'name', 'pinned_tweet_id', 'profile_banner_url', 'profile_image_url', 'protected', 'public_metrics', 'receives_your_dm', 'subscription_type', 'url', 'username', 'verified', 'verified_type', 'withheld']".
+            place_fields (array): A comma separated list of Place fields to display. Example: "['contained_within', 'country', 'country_code', 'full_name', 'geo', 'id', 'name', 'place_type']".
+
+        Returns:
+            dict[str, Any]: The request has succeeded.
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            Tweets
+        """
+        if id is None:
+            raise ValueError("Missing required parameter 'id'.")
+        url = f"{self.main_app_client.base_url}/2/lists/{id}/tweets"
+        query_params = {
+            k: v
+            for k, v in [
+                ("max_results", max_results),
+                ("pagination_token", pagination_token),
+                ("tweet.fields", tweet_fields),
+                ("expansions", expansions),
+                ("media.fields", media_fields),
+                ("poll.fields", poll_fields),
+                ("user.fields", user_fields),
+                ("place.fields", place_fields),
+            ]
+            if v is not None
+        }
+        response = self._get(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def list_tools(self):
+        return [
+            self.list_id_create,
+            self.list_id_delete,
+            self.list_id_get,
+            self.list_id_update,
+            self.list_get_followers,
+            self.list_get_members,
+            self.list_add_member,
+            self.list_remove_member,
+            self.lists_id_tweets,
+        ]

universal_mcp/applications/twitter/api_segments/openapi_json_api.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from .api_segment_base import APISegmentBase
+
+
+class OpenapiJsonApi(APISegmentBase):
+    def __init__(self, main_app_client: Any):
+        super().__init__(main_app_client)
+
+    def get_open_api_spec(self) -> dict[str, Any]:
+        """
+        Args:
+            None
+
+        Retrieves the OpenAPI JSON file at the specified path "/2/openapi.json" using the GET method.
+
+        Returns:
+            dict[str, Any]: The request was successful
+
+        Raises:
+            HTTPError: Raised when the API request fails (e.g., non-2XX status code).
+            JSONDecodeError: Raised if the response body cannot be parsed as JSON.
+
+        Tags:
+            General
+        """
+        url = f"{self.main_app_client.base_url}/2/openapi.json"
+        query_params = {}
+        response = self._get(url, params=query_params)
+        response.raise_for_status()
+        return response.json()
+
+    def list_tools(self):
+        return [self.get_open_api_spec]