universal-mcp 0.1.7rc1__py3-none-any.whl → 0.1.8__py3-none-any.whl

universal_mcp/applications/firecrawl/app.py

@@ -15,34 +15,11 @@ class FirecrawlApp(APIApplication):
 
     def __init__(self, integration: Integration | None = None) -> None:
         super().__init__(name="firecrawl", integration=integration)
-        self.api_key: str | None = None
 
-    def _set_api_key(self):
-        """
-        Ensures the API key is loaded from the integration.
-        Raises ValueError if the integration or key is missing/misconfigured.
-        """
-        if self.api_key:
-            return
-
-        if not self.integration:
-            raise ValueError(
-                "Integration is None. Cannot retrieve Firecrawl API Key."
-            )
-
-        credentials = self.integration.get_credentials()
-        if not credentials:
-            raise ValueError(
-                f"Failed to retrieve Firecrawl API Key using integration '{self.integration.name}'. "
-                f"Check store configuration (e.g., ensure the correct source like environment variable is set)."
-            )
-
-        self.api_key = credentials
-        
     def _get_client(self) -> FirecrawlApiClient:
         """Initializes and returns the Firecrawl client after ensuring API key is set."""
-        self._set_api_key()
-        return FirecrawlApiClient(api_key=self.api_key)
+        api_key = self.integration.get_credentials().get("api_key")
+        return FirecrawlApiClient(api_key=api_key)
 
     def scrape_url(
         self, url: str, params: dict[str, Any] | None = None
@@ -57,6 +34,9 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the scraped data on success,
             or a string containing an error message on failure.
+
+        Tags:
+            scrape, important
         """
         try:
             client = self._get_client()
@@ -79,6 +59,9 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the search results on success,
             or a string containing an error message on failure.
+
+        Tags:
+            search, important
         """
         try:
             client = self._get_client()
@@ -104,6 +87,9 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the job initiation response on success,
             or a string containing an error message on failure.
+
+        Tags:
+            crawl, async_job, start
         """
         try:
             client = self._get_client()
@@ -125,12 +111,15 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the job status details on success,
             or a string containing an error message on failure.
+
+        Tags:
+            crawl, async_job, status
         """
         try:
             client = self._get_client()
-            status = client.check_crawl_status(id=job_id)    
+            status = client.check_crawl_status(id=job_id)
             return status
-        
+
         except Exception as e:
             return f"Error checking crawl status for job ID {job_id}: {type(e).__name__} - {e}"
 
@@ -144,17 +133,19 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary confirming the cancellation status on success,
             or a string containing an error message on failure.
+
+        Tags:
+            crawl, async_job, management, cancel
         """
         try:
             client = self._get_client()
             response = client.cancel_crawl(id=job_id)
-            
+
             return response
 
-        except Exception as e:            
+        except Exception as e:
             return f"Error cancelling crawl job ID {job_id}: {type(e).__name__} - {e}"
 
-
     def start_batch_scrape(
         self,
         urls: list[str],
@@ -172,6 +163,9 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the job initiation response on success,
             or a string containing an error message on failure.
+
+        Tags:
+            scrape, batch, async_job, start
         """
         try:
             client = self._get_client()
@@ -193,12 +187,15 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the job status details on success,
             or a string containing an error message on failure.
+
+        Tags:
+            scrape, batch, async_job, status
         """
         try:
             client = self._get_client()
-            status = client.check_batch_scrape_status(id=job_id)            
+            status = client.check_batch_scrape_status(id=job_id)
             return status
-        
+
         except Exception as e:
             return f"Error checking batch scrape status for job ID {job_id}: {type(e).__name__} - {e}"
 
@@ -219,8 +216,11 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the job initiation response on success,
             or a string containing an error message on failure.
+
+        Tags:
+            extract, ai, async_job, start
         """
-        
+
         try:
             client = self._get_client()
             response = client.async_extract(
@@ -241,12 +241,15 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the job status details on success,
             or a string containing an error message on failure.
+
+        Tags:
+            extract, ai, async_job, status
         """
         try:
             client = self._get_client()
             status = client.get_extract_status(job_id=job_id)
             return status
-        
+
         except Exception as e:
             return f"Error checking extraction status for job ID {job_id}: {type(e).__name__} - {e}"
 
@@ -262,4 +265,4 @@ class FirecrawlApp(APIApplication):
             self.check_batch_scrape_status,
             self.start_extract,
             self.check_extract_status,
-        ]
+        ]

universal_mcp/applications/github/app.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, ClassVar
 
 from loguru import logger
 
@@ -7,6 +7,8 @@ from universal_mcp.integrations import Integration
 
 
 class GithubApp(APIApplication):
+    APP_TAGS: ClassVar[list[str]] = ["developers-tools"]
+
     def __init__(self, integration: Integration) -> None:
         super().__init__(name="github", integration=integration)
         self.base_api_url = "https://api.github.com/repos"
@@ -23,18 +25,24 @@ class GithubApp(APIApplication):
         }
 
     def star_repository(self, repo_full_name: str) -> str:
-        """Star a GitHub repository
+        """
+        Stars a GitHub repository using the GitHub API and returns a status message.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
+            repo_full_name: The full name of the repository in 'owner/repo' format (e.g., 'octocat/Hello-World')
 
         Returns:
+            A string message indicating whether the starring operation was successful, the repository was not found, or an error occurred
 
-            A confirmation message
+        Raises:
+            RequestException: If there are network connectivity issues or API request failures
+            ValueError: If the repository name format is invalid
+
+        Tags:
+            star, github, api, action, social, repository, important
         """
         url = f"https://api.github.com/user/starred/{repo_full_name}"
         response = self._put(url, data={})
-
         if response.status_code == 204:
             return f"Successfully starred repository {repo_full_name}"
         elif response.status_code == 404:
@@ -44,23 +52,29 @@ class GithubApp(APIApplication):
             return f"Error starring repository: {response.text}"
 
     def list_commits(self, repo_full_name: str) -> str:
-        """List recent commits for a GitHub repository
+        """
+        Retrieves and formats a list of recent commits from a GitHub repository
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
+            repo_full_name: The full name of the repository in 'owner/repo' format
 
         Returns:
-            A formatted list of recent commits
+            A formatted string containing the most recent 12 commits, including commit hash, message, and author
+
+        Raises:
+            requests.exceptions.HTTPError: When the GitHub API request fails (e.g., repository not found, rate limit exceeded)
+            requests.exceptions.RequestException: When network issues or other request-related problems occur
+
+        Tags:
+            list, read, commits, github, history, api, important
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/commits"
         response = self._get(url)
         response.raise_for_status()
-
         commits = response.json()
         if not commits:
             return f"No commits found for repository {repo_full_name}"
-
         result = f"Recent commits for {repo_full_name}:\n\n"
         for commit in commits[:12]:  # Limit to 12 commits
             sha = commit.get("sha", "")[:7]
@@ -68,54 +82,63 @@ class GithubApp(APIApplication):
             author = commit.get("commit", {}).get("author", {}).get("name", "Unknown")
 
             result += f"- {sha}: {message} (by {author})\n"
-
         return result
 
     def list_branches(self, repo_full_name: str) -> str:
-        """List branches for a GitHub repository
+        """
+        Lists all branches for a specified GitHub repository and returns them in a formatted string representation.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
+            repo_full_name: The full name of the repository in 'owner/repo' format (e.g., 'octocat/Hello-World')
 
         Returns:
-            A formatted list of branches
+            A formatted string containing the list of branches, or a message indicating no branches were found
+
+        Raises:
+            HTTPError: When the GitHub API request fails (e.g., repository not found, authentication error)
+            RequestException: When there are network connectivity issues or API communication problems
+
+        Tags:
+            list, branches, github, read, api, repository, important
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/branches"
         response = self._get(url)
         response.raise_for_status()
-
         branches = response.json()
         if not branches:
             return f"No branches found for repository {repo_full_name}"
-
         result = f"Branches for {repo_full_name}:\n\n"
         for branch in branches:
             branch_name = branch.get("name", "Unknown")
             result += f"- {branch_name}\n"
-
         return result
 
     def list_pull_requests(self, repo_full_name: str, state: str = "open") -> str:
-        """List pull requests for a GitHub repository
+        """
+        Retrieves and formats a list of pull requests for a specified GitHub repository.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
-            state: The state of the pull requests to filter by (open, closed, or all)
+            repo_full_name: The full name of the repository in the format 'owner/repo' (e.g., 'tensorflow/tensorflow')
+            state: Filter for pull request state. Can be 'open', 'closed', or 'all'. Defaults to 'open'
 
         Returns:
-            A formatted list of pull requests
+            A formatted string containing the list of pull requests, including PR number, title, author, and status. Returns a message if no pull requests are found.
+
+        Raises:
+            HTTPError: Raised when the GitHub API request fails (e.g., invalid repository name, rate limiting, or authentication issues)
+
+        Tags:
+            list, pull-request, github, api, read, important, fetch, query
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/pulls"
         params = {"state": state}
         response = self._get(url, params=params)
         response.raise_for_status()
-
         pull_requests = response.json()
         if not pull_requests:
             return f"No pull requests found for repository {repo_full_name} with state '{state}'"
-
         result = f"Pull requests for {repo_full_name} (State: {state}):\n\n"
         for pr in pull_requests:
             pr_title = pr.get("title", "No Title")
@@ -126,7 +149,6 @@ class GithubApp(APIApplication):
             result += (
                 f"- PR #{pr_number}: {pr_title} (by {pr_user}, Status: {pr_state})\n"
             )
-
         return result
 
     def list_issues(
@@ -138,62 +160,72 @@ class GithubApp(APIApplication):
         per_page: int = 30,
         page: int = 1,
     ) -> list[dict[str, Any]]:
-        """List issues for a GitHub repository
+        """
+        Retrieves a list of issues from a specified GitHub repository with optional filtering parameters.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
-            state: State of issues to return (open, closed, all). Default: open
-            assignee: Filter by assignee. Use 'none' for no assignee, '*' for any assignee
-            labels: Comma-separated list of label names (e.g. "bug,ui,@high")
-            per_page: The number of results per page (max 100)
-            page: The page number of the results to fetch
+            repo_full_name: The full name of the repository in 'owner/repo' format
+            state: Filter issues by state ('open', 'closed', 'all'). Defaults to 'open'
+            assignee: Filter by assignee username. Use 'none' for unassigned issues, '*' for assigned issues
+            labels: Comma-separated string of label names to filter by (e.g., 'bug,ui,@high')
+            per_page: Number of results per page (max 100). Defaults to 30
+            page: Page number for pagination. Defaults to 1
 
         Returns:
-             The complete GitHub API response
+            List of dictionaries containing issue data from the GitHub API response
+
+        Raises:
+            HTTPError: When the GitHub API request fails (e.g., invalid repository name, authentication failure)
+            RequestException: When there are network connectivity issues or other request-related problems
+
+        Tags:
+            list, issues, github, api, read, filter, pagination, important, project-management
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/issues"
-
         params = {"state": state, "per_page": per_page, "page": page}
-
         if assignee:
             params["assignee"] = assignee
         if labels:
             params["labels"] = labels
-
         response = self._get(url, params=params)
         response.raise_for_status()
         return response.json()
 
     def get_pull_request(self, repo_full_name: str, pull_number: int) -> str:
-        """Get a specific pull request for a GitHub repository
+        """
+        Retrieves and formats detailed information about a specific GitHub pull request from a repository
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
-            pull_number: The number of the pull request to retrieve
+            repo_full_name: The full repository name in 'owner/repo' format (e.g., 'octocat/Hello-World')
+            pull_number: The numeric identifier of the pull request to retrieve
 
         Returns:
-            A formatted string with pull request details
+            A formatted string containing pull request details including title, creator, status, and description
+
+        Raises:
+            HTTPError: Raised when the GitHub API request fails (e.g., invalid repository name, non-existent PR number, or authentication issues)
+            RequestException: Raised when there are network connectivity issues or other request-related problems
+
+        Tags:
+            get, read, github, pull-request, api, fetch, format, important
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/pulls/{pull_number}"
         response = self._get(url)
         response.raise_for_status()
-
         pr = response.json()
         pr_title = pr.get("title", "No Title")
         pr_number = pr.get("number", "Unknown")
         pr_state = pr.get("state", "Unknown")
         pr_user = pr.get("user", {}).get("login", "Unknown")
         pr_body = pr.get("body", "No description provided.")
-
         result = (
             f"Pull Request #{pr_number}: {pr_title}\n"
             f"Created by: {pr_user}\n"
             f"Status: {pr_state}\n"
             f"Description: {pr_body}\n"
         )
-
         return result
 
     def create_pull_request(
@@ -207,7 +239,8 @@ class GithubApp(APIApplication):
         maintainer_can_modify: bool = True,
         draft: bool = False,
     ) -> dict[str, Any]:
-        """Create a new pull request for a GitHub repository
+        """
+        Creates a new pull request in a GitHub repository, optionally converting an existing issue into a pull request.
 
         Args:
             repo_full_name: The full name of the repository (e.g. 'owner/repo')
@@ -215,24 +248,28 @@ class GithubApp(APIApplication):
             base: The name of the branch you want the changes pulled into
             title: The title of the new pull request (required if issue is not specified)
             body: The contents of the pull request
-            issue: An issue number to convert to a pull request. If specified, the issue's
-                   title, body, and comments will be used for the pull request
+            issue: An issue number to convert to a pull request. If specified, the issue's title, body, and comments will be used
             maintainer_can_modify: Indicates whether maintainers can modify the pull request
             draft: Indicates whether the pull request is a draft
 
         Returns:
-            The complete GitHub API response
+            A dictionary containing the complete GitHub API response
+
+        Raises:
+            ValueError: Raised when neither 'title' nor 'issue' parameter is specified
+            HTTPError: Raised when the GitHub API request fails
+
+        Tags:
+            create, pull-request, github, api, write, important
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/pulls"
-
         pull_request_data = {
             "head": head,
             "base": base,
             "maintainer_can_modify": maintainer_can_modify,
             "draft": draft,
         }
-
         if issue is not None:
             pull_request_data["issue"] = issue
         else:
@@ -241,7 +278,6 @@ class GithubApp(APIApplication):
             pull_request_data["title"] = title
             if body is not None:
                 pull_request_data["body"] = body
-
         response = self._post(url, pull_request_data)
         response.raise_for_status()
         return response.json()
@@ -249,25 +285,27 @@ class GithubApp(APIApplication):
     def create_issue(
         self, repo_full_name: str, title: str, body: str = "", labels=None
     ) -> str:
-        """Create a new issue in a GitHub repository
+        """
+        Creates a new issue in a specified GitHub repository with a title, body content, and optional labels.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
+            repo_full_name: The full name of the repository in 'owner/repo' format
             title: The title of the issue
-            body: The contents of the issue
-            labels: Labels to associate with this issue. Enter as a comma-separated string
-                   (e.g. "bug,enhancement,documentation").
-                   NOTE: Only users with push access can set labels for new issues.
-                   Labels are silently dropped otherwise.
+            body: The contents/description of the issue (defaults to empty string)
+            labels: Labels to associate with the issue, as a comma-separated string or list. Only users with push access can set labels
 
         Returns:
-            A confirmation message with the new issue details
+            A string containing a confirmation message with the issue number, title, and URL
+
+        Raises:
+            HTTPError: When the GitHub API request fails (e.g., invalid repository name, authentication issues, or insufficient permissions)
+
+        Tags:
+            create, issues, github, api, project-management, write, important
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/issues"
-
         issue_data = {"title": title, "body": body}
-
         if labels:
             if isinstance(labels, str):
                 labels_list = [
@@ -276,14 +314,11 @@ class GithubApp(APIApplication):
                 issue_data["labels"] = labels_list
             else:
                 issue_data["labels"] = labels
-
         response = self._post(url, issue_data)
         response.raise_for_status()
-
         issue = response.json()
         issue_number = issue.get("number", "Unknown")
         issue_url = issue.get("html_url", "")
-
         return (
             f"Successfully created issue #{issue_number}:\n"
             f"Title: {title}\n"
@@ -293,31 +328,33 @@ class GithubApp(APIApplication):
     def list_repo_activities(
         self, repo_full_name: str, direction: str = "desc", per_page: int = 30
     ) -> str:
-        """List activities for a GitHub repository
+        """
+        Retrieves and formats a list of activities for a specified GitHub repository.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
-            direction: The direction to sort the results by (asc or desc). Default: desc
-            per_page: The number of results per page (max 100). Default: 30
+            repo_full_name: The full name of the repository in 'owner/repo' format
+            direction: The sort direction for results ('asc' or 'desc'). Defaults to 'desc'
+            per_page: Number of activities to return per page (1-100). Defaults to 30
 
         Returns:
-            A formatted list of repository activities
+            A formatted string containing a list of repository activities, including timestamps and actor names. Returns a 'No activities' message if no activities are found.
+
+        Raises:
+            HTTPError: Raised when the GitHub API request fails
+            ValueError: May be raised if repo_full_name is invalid or empty after stripping
+
+        Tags:
+            list, activity, github, read, events, api, query, format
         """
         repo_full_name = repo_full_name.strip()
         url = f"{self.base_api_url}/{repo_full_name}/activity"
-
-        # Build query parameters
         params = {"direction": direction, "per_page": per_page}
-
         response = self._get(url, params=params)
         response.raise_for_status()
-
         activities = response.json()
         if not activities:
             return f"No activities found for repository {repo_full_name}"
-
         result = f"Repository activities for {repo_full_name}:\n\n"
-
         for activity in activities:
             # Extract common fields
             timestamp = activity.get("timestamp", "Unknown time")
@@ -327,7 +364,6 @@ class GithubApp(APIApplication):
 
             # Create a simple description of the activity
             result += f"- {actor_name} performed an activity at {timestamp}\n"
-
         return result
 
     def update_issue(
@@ -340,22 +376,29 @@ class GithubApp(APIApplication):
         state: str = None,
         state_reason: str = None,
     ) -> dict[str, Any]:
-        """Update an issue in a GitHub repository
+        """
+        Updates an existing GitHub issue with specified parameters including title, body, assignee, state, and state reason.
 
         Args:
-            repo_full_name: The full name of the repository (e.g. 'owner/repo')
-            issue_number: The number that identifies the issue
-            title: The title of the issue
-            body: The contents of the issue
-            assignee: Username to assign to this issue
-            state: State of the issue (open or closed)
-            state_reason: Reason for state change (completed, not_planned, reopened, null)
+            repo_full_name: The full name of the repository in 'owner/repo' format
+            issue_number: The unique identifier number of the issue to update
+            title: The new title of the issue (optional)
+            body: The new content/description of the issue (optional)
+            assignee: GitHub username to assign to the issue (optional)
+            state: The desired state of the issue ('open' or 'closed') (optional)
+            state_reason: The reason for state change ('completed', 'not_planned', 'reopened', or null) (optional)
 
         Returns:
-             The complete GitHub API response
+            A dictionary containing the complete GitHub API response with updated issue details
+
+        Raises:
+            HTTPError: Raised when the GitHub API request fails (e.g., invalid repository, non-existent issue, insufficient permissions)
+            RequestException: Raised when there's a network error or API connectivity issue
+
+        Tags:
+            github, issues, update, api, project-management, write, important
         """
         url = f"{self.base_api_url}/{repo_full_name}/issues/{issue_number}"
-
         update_data = {}
         if title is not None:
             update_data["title"] = title
@@ -367,7 +410,6 @@ class GithubApp(APIApplication):
             update_data["state"] = state
         if state_reason is not None:
             update_data["state_reason"] = state_reason
-
         response = self._patch(url, update_data)
         response.raise_for_status()
         return response.json()