feat(github): enhance user activity query documentation for authenticated user access

Author: saidsef

src/mcp_github/github_integration.py

@@ -668,12 +668,96 @@ def create_release(self, repo_owner: str, repo_name: str, tag_name: str, release
 
     def user_activity_query(self, variables: dict[str, Any], query: str) -> Dict[str, Any]:
         """
-        Performs a user activity query using GitHub's GraphQL API across all repositories and organisations.
+        Performs a user activity query using GitHub's GraphQL API for the authenticated user (token owner).
+
+        **Important**: To query private organization activities, the query MUST use the `viewer` field 
+        instead of `user(login:)`. The `viewer` field returns data for the authenticated user (token owner) 
+        and includes all private contributions and organization activities.
+
+        **Query Requirements**:
+        - Use `viewer { ... }` to query the authenticated user's activity
+        - Do NOT use `user(login: "username") { ... }` as it only shows public contributions
+        - The `viewer` query automatically includes private repositories and organizations
+
+        **Example Query Structure**:
+        ```graphql
+        query($from: DateTime!, $to: DateTime!) {
+          viewer {
+            login
+            contributionsCollection(from: $from, to: $to) {
+              commitContributionsByRepository(maxRepositories: 100) {
+            repository {
+              name
+              isPrivate
+              owner {
+                login
+                ... on Organization {
+                  login
+                }
+              }
+            }
+            contributions {
+              totalCount
+            }
+              }
+              pullRequestContributionsByRepository(maxRepositories: 100) {
+            repository {
+              name
+              isPrivate
+              owner {
+                login
+              }
+            }
+            contributions {
+              totalCount
+            }
+              }
+              issueContributionsByRepository(maxRepositories: 100) {
+            repository {
+              name
+              isPrivate
+              owner {
+                login
+              }
+            }
+            contributions {
+              totalCount
+            }
+              }
+              pullRequestReviewContributionsByRepository(maxRepositories: 100) {
+            repository {
+              name
+              isPrivate
+              owner {
+                login
+              }
+            }
+            contributions {
+              totalCount
+            }
+              }
+            }
+            organizations(first: 100) {
+              nodes {
+            login
+            viewerCanAdminister
+              }
+            }
+          }
+        }
+        ```
+
         Args:
-            variables (dict[str, Any]): The variables to include in the query i.e. {"login": "username", "from": "2023-01-01", "to": "2023-12-31"}.
-            query (str): The search query string. GitHub GraphQL query summary collection that includes all activity across all orgs, public and private.
+            variables (dict[str, Any]): Query variables. For authenticated user queries, only include:
+            - "from": Start date in ISO 8601 format (e.g., "2024-10-01T00:00:00Z")
+            - "to": End date in ISO 8601 format (e.g., "2024-10-31T23:59:59Z")
+            Do NOT include "login" variable when using `viewer`.
+            query (str): GraphQL query string. Must use `viewer` field to access authenticated user's 
+            private activities across all organizations.
+
         Returns:
-            Dict[str, Any]: The JSON response from the GitHub API containing search results if successful.
+            Dict[str, Any]: The JSON response from GitHub's GraphQL API containing the authenticated 
+            user's activity data, including private repositories and organizations.
         """
         logging.info("Performing user query on GitHub")