github-mcp 1.1.0__py3-none-any.whl

github_mcp/tools/search.py

@@ -0,0 +1,524 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from github_mcp.app import mcp
+from mcp.types import ToolAnnotations
+from github_mcp.client import github_request, handle_github_error
+from github_mcp.formatting import (
+    ResponseFormat,
+    fmt_json,
+    fmt_list_markdown,
+    fmt_timestamp,
+)
+
+# MARK: Shared pagination helper for search endpoints
+
+_SEARCH_BASE = "/search"
+
+
+async def _search(
+    endpoint: str,
+    q: str,
+    *,
+    sort: str | None = None,
+    order: str | None = None,
+    limit: int = 20,
+    page: int = 1,
+) -> dict:
+    """Run a GitHub search query and return the raw result dict."""
+    params: dict = {"q": q, "per_page": limit, "page": page}
+    if sort:
+        params["sort"] = sort
+    if order:
+        params["order"] = order
+    resp = await github_request("GET", f"{_SEARCH_BASE}/{endpoint}", params=params)
+    return resp.json()
+
+
+# MARK: Input models
+
+
+class SearchRepositoriesInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    q: str = Field(
+        ...,
+        description=(
+            "GitHub repository search query. Supports qualifiers like "
+            "'language:python stars:>100 topic:mcp'. See "
+            "https://docs.github.com/en/search-github/searching-on-github/searching-for-repositories"
+        ),
+        min_length=1,
+    )
+    sort: Optional[str] = Field(
+        default=None,
+        description="Sort field: 'stars', 'forks', 'help-wanted-issues', 'updated'. Default: best match.",
+    )
+    order: Optional[str] = Field(
+        default="desc", description="Sort order: 'desc' (default) or 'asc'."
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Max results to return (1–100, default 20).",
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class SearchCodeInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    q: str = Field(
+        ...,
+        description=(
+            "Code search query. Supports qualifiers like 'repo:owner/repo language:python "
+            "filename:test_*.py'. See https://docs.github.com/en/search-github/searching-on-github/searching-code"
+        ),
+        min_length=1,
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Max results to return (1–100, default 20).",
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class SearchIssuesInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    q: str = Field(
+        ...,
+        description=(
+            "Issue/PR search query. Supports qualifiers like 'is:issue is:open label:bug repo:owner/repo'. "
+            "See https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests"
+        ),
+        min_length=1,
+    )
+    sort: Optional[str] = Field(
+        default=None,
+        description=(
+            "Sort by: 'comments', 'reactions', 'reactions-+1', 'reactions--1', "
+            "'reactions-smile', 'reactions-thinking_face', 'reactions-heart', "
+            "'reactions-tada', 'interactions', 'created', 'updated'. Default: best match."
+        ),
+    )
+    order: Optional[str] = Field(
+        default="desc", description="Sort order: 'desc' (default) or 'asc'."
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Max results to return (1–100, default 20).",
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class SearchUsersInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    q: str = Field(
+        ...,
+        description=(
+            "User/org search query. Supports qualifiers like 'type:user location:Berlin language:python'. "
+            "See https://docs.github.com/en/search-github/searching-on-github/searching-users"
+        ),
+        min_length=1,
+    )
+    sort: Optional[str] = Field(
+        default=None,
+        description="Sort by: 'followers', 'repositories', 'joined'. Default: best match.",
+    )
+    order: Optional[str] = Field(
+        default="desc", description="Sort order: 'desc' (default) or 'asc'."
+    )
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Max results (1–100, default 20)."
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class SearchCommitsInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    q: str = Field(
+        ...,
+        description=(
+            "Commit search query. Supports qualifiers like 'repo:owner/repo author:login "
+            "committer-date:>2024-01-01'. "
+            "See https://docs.github.com/en/search-github/searching-on-github/searching-commits"
+        ),
+        min_length=1,
+    )
+    sort: Optional[str] = Field(
+        default=None,
+        description="Sort by: 'author-date', 'committer-date'. Default: best match.",
+    )
+    order: Optional[str] = Field(
+        default="desc", description="Sort order: 'desc' (default) or 'asc'."
+    )
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Max results (1–100, default 20)."
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(
+    name="github_search_repositories",
+    annotations=ToolAnnotations(
+        title="Search GitHub Repositories",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_search_repositories(params: SearchRepositoriesInput) -> str:
+    """Search GitHub repositories using GitHub's search syntax.
+
+    Supports qualifiers such as language, stars, topics, owner, etc.
+
+    Args:
+        params (SearchRepositoriesInput): Validated input containing:
+            - q (str): Search query string.
+            - sort (Optional[str]): Sort field.
+            - order (Optional[str]): 'asc' or 'desc'.
+            - limit (int): Max results (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted results. Markdown shows repo name, description, stars,
+            language, and URL. JSON includes full_name, description, stars,
+            forks, language, topics, html_url, and total_count.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        data = await _search(
+            "repositories",
+            params.q,
+            sort=params.sort,
+            order=params.order,
+            limit=params.limit,
+            page=params.page,
+        )
+        repos = data.get("items", [])
+        total = data.get("total_count", 0)
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json({"total_count": total, "items": repos})
+
+        lines = [
+            f"## Repository Search: `{params.q}`",
+            f"*{total:,} total matches — showing {len(repos)}*",
+            "",
+        ]
+        lines.append(
+            fmt_list_markdown(
+                repos,
+                fields=[
+                    "description",
+                    "language",
+                    "stargazers_count",
+                    "forks_count",
+                    "updated_at",
+                ],
+                name_field="full_name",
+            )
+        )
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_search_code",
+    annotations=ToolAnnotations(
+        title="Search GitHub Code",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_search_code(params: SearchCodeInput) -> str:
+    """Search for code across GitHub repositories using GitHub's code search syntax.
+
+    Note: Code search requires authentication. Results are limited to the first
+    1 000 matches by GitHub's API.
+
+    Args:
+        params (SearchCodeInput): Validated input containing:
+            - q (str): Code search query (e.g. 'FastMCP repo:user/repo language:python').
+            - limit (int): Max results (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted results. Markdown shows file path, repository, and URL.
+            JSON includes name, path, repository, sha, and html_url.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        # Code search doesn't support sort parameter in a stable way
+        data = await _search("code", params.q, limit=params.limit, page=params.page)
+        items = data.get("items", [])
+        total = data.get("total_count", 0)
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json({"total_count": total, "items": items})
+
+        lines = [
+            f"## Code Search: `{params.q}`",
+            f"*{total:,} total matches — showing {len(items)}*",
+            "",
+        ]
+        if not items:
+            lines.append("*No code matches found.*")
+        else:
+            for item in items:
+                path = item.get("path", "")
+                repo_name = item.get("repository", {}).get("full_name", "")
+                url = item.get("html_url", "")
+                lines.append(f"- [`{path}`]({url}) in **{repo_name}**")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_search_issues",
+    annotations=ToolAnnotations(
+        title="Search GitHub Issues and Pull Requests",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_search_issues(params: SearchIssuesInput) -> str:
+    """Search issues and pull requests across GitHub using search qualifiers.
+
+    Use ``is:issue`` or ``is:pr`` to restrict to one type.
+
+    Args:
+        params (SearchIssuesInput): Validated input containing:
+            - q (str): Search query (e.g. 'is:open is:issue label:bug repo:owner/repo').
+            - sort (Optional[str]): Sort field.
+            - order (Optional[str]): 'asc' or 'desc'.
+            - limit (int): Max results (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted issue/PR list. Markdown shows number, title, state,
+            type (issue/PR), labels, and URL. JSON includes number, title, state,
+            labels, user, created_at, html_url, and total_count.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        data = await _search(
+            "issues",
+            params.q,
+            sort=params.sort,
+            order=params.order,
+            limit=params.limit,
+            page=params.page,
+        )
+        items = data.get("items", [])
+        total = data.get("total_count", 0)
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json({"total_count": total, "items": items})
+
+        lines = [
+            f"## Issues/PR Search: `{params.q}`",
+            f"*{total:,} total matches — showing {len(items)}*",
+            "",
+        ]
+        if not items:
+            lines.append("*No matches found.*")
+        else:
+            for item in items:
+                num = item.get("number", "?")
+                title = item.get("title", "")
+                url = item.get("html_url", "")
+                state = item.get("state", "")
+                kind = "PR" if "pull_request" in item else "Issue"
+                labels = ", ".join(lbl["name"] for lbl in item.get("labels", []))
+                label_str = f" [{labels}]" if labels else ""
+                repo_url = item.get("repository_url", "")
+                repo_name = repo_url.split("repos/")[-1] if "repos/" in repo_url else ""
+                lines.append(
+                    f"- **#{num}** ({kind}) [{title}]({url}){label_str} — {state}"
+                )
+                if repo_name:
+                    lines.append(f"  - Repo: {repo_name}")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_search_users",
+    annotations=ToolAnnotations(
+        title="Search GitHub Users and Organisations",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_search_users(params: SearchUsersInput) -> str:
+    """Search GitHub users and organisations.
+
+    Supports qualifiers such as location, language, followers, type, etc.
+
+    Args:
+        params (SearchUsersInput): Validated input containing:
+            - q (str): User search query.
+            - sort (Optional[str]): Sort field.
+            - order (Optional[str]): 'asc' or 'desc'.
+            - limit (int): Max results (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted user list. Markdown shows login, type (user/org),
+            and profile URL. JSON includes login, type, avatar_url, html_url.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        data = await _search(
+            "users",
+            params.q,
+            sort=params.sort,
+            order=params.order,
+            limit=params.limit,
+            page=params.page,
+        )
+        users = data.get("items", [])
+        total = data.get("total_count", 0)
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json({"total_count": total, "items": users})
+
+        lines = [
+            f"## User Search: `{params.q}`",
+            f"*{total:,} total matches — showing {len(users)}*",
+            "",
+        ]
+        if not users:
+            lines.append("*No users found.*")
+        else:
+            for user in users:
+                login = user.get("login", "?")
+                url = user.get("html_url", "")
+                user_type = user.get("type", "User")
+                lines.append(f"- **[{login}]({url})** ({user_type})")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_search_commits",
+    annotations=ToolAnnotations(
+        title="Search GitHub Commits",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_search_commits(params: SearchCommitsInput) -> str:
+    """Search commits across GitHub repositories.
+
+    Supports qualifiers like repo, author, committer, committer-date, merge, etc.
+
+    Args:
+        params (SearchCommitsInput): Validated input containing:
+            - q (str): Commit search query.
+            - sort (Optional[str]): 'author-date' or 'committer-date'.
+            - order (Optional[str]): 'asc' or 'desc'.
+            - limit (int): Max results (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted commit list. Markdown shows SHA (short), commit message,
+            author, date, and URL. JSON is raw API items with total_count.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        resp = await github_request(
+            "GET",
+            f"{_SEARCH_BASE}/commits",
+            params={
+                "q": params.q,
+                "per_page": params.limit,
+                "page": params.page,
+                **({"sort": params.sort} if params.sort else {}),
+                **({"order": params.order} if params.order else {}),
+            },
+            accept="application/vnd.github+json",
+        )
+        data = resp.json()
+        items = data.get("items", [])
+        total = data.get("total_count", 0)
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json({"total_count": total, "items": items})
+
+        lines = [
+            f"## Commit Search: `{params.q}`",
+            f"*{total:,} total matches — showing {len(items)}*",
+            "",
+        ]
+        if not items:
+            lines.append("*No commits found.*")
+        else:
+            for item in items:
+                sha = item.get("sha", "")[:7]
+                commit_data = item.get("commit", {})
+                msg = commit_data.get("message", "").split("\n")[0][:80]
+                author = commit_data.get("author", {}).get("name", "unknown")
+                date = fmt_timestamp(commit_data.get("author", {}).get("date"))
+                repo_name = item.get("repository", {}).get("full_name", "")
+                url = item.get("html_url", "")
+                lines.append(f"- [`{sha}`]({url}) {msg}")
+                lines.append(f"  - Author: {author} — {date} in **{repo_name}**")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)