napistu 0.1.0__py3-none-any.whl → 0.2.4.dev3__py3-none-any.whl

napistu/mcp/constants.py

@@ -0,0 +1,72 @@
+import os
+from types import SimpleNamespace
+
+from napistu.constants import PACKAGE_DEFS
+
+MCP_COMPONENTS = SimpleNamespace(
+    CODEBASE="codebase",
+    DOCUMENTATION="documentation",
+    EXECUTION="execution",
+    TUTORIALS="tutorials",
+)
+
+DOCUMENTATION = SimpleNamespace(
+    README="readme",
+    WIKI="wiki",
+    ISSUES="issues",
+    PRS="prs",
+    PACKAGEDOWN="packagedown",
+)
+
+EXECUTION = SimpleNamespace(
+    NOTEBOOKS="notebooks",
+)
+
+TUTORIALS = SimpleNamespace(
+    TUTORIALS="tutorials",
+)
+
+TOOL_VARS = SimpleNamespace(
+    NAME="name",
+    SNIPPET="snippet",
+)
+
+READMES = {
+    "napistu": "https://raw.githubusercontent.com/napistu/napistu/main/README.md",
+    "napistu-py": "https://raw.githubusercontent.com/napistu/napistu-py/main/README.md",
+    "napistu-r": "https://raw.githubusercontent.com/napistu/napistu-r/main/README.md",
+    "napistu/tutorials": "https://raw.githubusercontent.com/napistu/napistu/main/tutorials/README.md",
+}
+
+WIKI_ROOT = "https://raw.githubusercontent.com/napistu/napistu/main/docs/wiki"
+
+NAPISTU_PY_READTHEDOCS = "https://napistu.readthedocs.io/en/latest"
+NAPISTU_PY_READTHEDOCS_API = NAPISTU_PY_READTHEDOCS + "/api.html"
+READTHEDOCS_TOC_CSS_SELECTOR = "td"
+
+DEFAULT_GITHUB_API = "https://api.github.com"
+
+REPOS_WITH_ISSUES = [
+    PACKAGE_DEFS.GITHUB_PROJECT_REPO,
+    PACKAGE_DEFS.GITHUB_NAPISTU_PY,
+    PACKAGE_DEFS.GITHUB_NAPISTU_R,
+]
+
+GITHUB_ISSUES_INDEXED = "all"
+GITHUB_PRS_INDEXED = "all"
+
+REPOS_WITH_WIKI = [PACKAGE_DEFS.GITHUB_PROJECT_REPO]
+
+# Example mapping: tutorial_id -> raw GitHub URL
+TUTORIAL_URLS = {
+    "adding_data_to_graphs": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/adding_data_to_graphs.ipynb",
+    "downloading_pathway_data": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/downloading_pathway_data.ipynb",
+    "formatting_sbml_dfs_as_cpr_graphs": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/formatting_sbml_dfs_as_cpr_graphs.ipynb",
+    "merging_models_into_a_consensus": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/merging_models_into_a_consensus.ipynb",
+    "r_based_network_visualization": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/r_based_network_visualization.ipynb",
+    "suggesting_mechanisms_with_networks": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/suggesting_mechanisms_with_networks.ipynb",
+    "understanding_sbml_dfs": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/understanding_sbml_dfs.ipynb",
+    "working_with_genome_scale_networks": "https://raw.githubusercontent.com/napistu/napistu/refs/heads/main/tutorials/working_with_genome_scale_networks.ipynb",
+}
+
+TUTORIALS_CACHE_DIR = os.path.join(PACKAGE_DEFS.CACHE_DIR, TUTORIALS.TUTORIALS)

napistu/mcp/documentation.py

@@ -0,0 +1,166 @@
+"""
+Documentation components for the Napistu MCP server.
+"""
+
+from fastmcp import FastMCP
+
+from napistu.mcp import documentation_utils
+from napistu.mcp import utils as mcp_utils
+from napistu.mcp.constants import DOCUMENTATION, READMES, REPOS_WITH_ISSUES
+
+# Global cache for documentation content
+_docs_cache = {
+    DOCUMENTATION.README: {},
+    DOCUMENTATION.WIKI: {},
+    DOCUMENTATION.ISSUES: {},
+    DOCUMENTATION.PRS: {},
+    DOCUMENTATION.PACKAGEDOWN: {},
+}
+
+
+async def initialize_components() -> bool:
+    """
+    Initialize documentation components.
+    Loads documentation content and should be called before the server starts handling requests.
+
+    Returns
+    -------
+    bool
+        True if initialization is successful.
+    """
+    global _docs_cache
+    # Load documentation from the READMES dict
+    for name, url in READMES.items():
+        _docs_cache[DOCUMENTATION.README][name] = (
+            await documentation_utils.load_readme_content(url)
+        )
+    # Load issue and PR summaries with the GitHub API
+    for repo in REPOS_WITH_ISSUES:
+        _docs_cache[DOCUMENTATION.ISSUES][repo] = await documentation_utils.list_issues(
+            repo
+        )
+        _docs_cache[DOCUMENTATION.PRS][repo] = (
+            await documentation_utils.list_pull_requests(repo)
+        )
+    return True
+
+
+def register_components(mcp: FastMCP):
+    """
+    Register documentation components with the MCP server.
+
+    Args:
+        mcp: FastMCP server instance
+    """
+
+    # Register resources
+    @mcp.resource("napistu://documentation/summary")
+    async def get_documentation_summary():
+        """
+        Get a summary of all available documentation.
+        """
+        return {
+            "readme_files": list(_docs_cache[DOCUMENTATION.README].keys()),
+            "issues": list(_docs_cache[DOCUMENTATION.ISSUES].keys()),
+            "prs": list(_docs_cache[DOCUMENTATION.PRS].keys()),
+            "wiki_pages": list(_docs_cache[DOCUMENTATION.WIKI].keys()),
+            "packagedown_sections": list(_docs_cache[DOCUMENTATION.PACKAGEDOWN].keys()),
+        }
+
+    @mcp.resource("napistu://documentation/readme/{file_name}")
+    async def get_readme_content(file_name: str):
+        """
+        Get the content of a specific README file.
+
+        Args:
+            file_name: Name of the README file
+        """
+        if file_name not in _docs_cache[DOCUMENTATION.README]:
+            return {"error": f"README file {file_name} not found"}
+
+        return {
+            "content": _docs_cache[DOCUMENTATION.README][file_name],
+            "format": "markdown",
+        }
+
+    @mcp.resource("napistu://documentation/issues/{repo}")
+    async def get_issues(repo: str):
+        """
+        Get the list of issues for a given repository.
+        """
+        return _docs_cache[DOCUMENTATION.ISSUES].get(repo, [])
+
+    @mcp.resource("napistu://documentation/prs/{repo}")
+    async def get_prs(repo: str):
+        """
+        Get the list of pull requests for a given repository.
+        """
+        return _docs_cache[DOCUMENTATION.PRS].get(repo, [])
+
+    @mcp.resource("napistu://documentation/issue/{repo}/{number}")
+    async def get_issue_resource(repo: str, number: int):
+        """
+        Get a single issue by number for a given repository.
+        """
+        # Try cache first
+        cached = next(
+            (
+                i
+                for i in _docs_cache[DOCUMENTATION.ISSUES].get(repo, [])
+                if i["number"] == number
+            ),
+            None,
+        )
+        if cached:
+            return cached
+        # Fallback to live fetch
+        return await documentation_utils.get_issue(repo, number)
+
+    @mcp.resource("napistu://documentation/pr/{repo}/{number}")
+    async def get_pr_resource(repo: str, number: int):
+        """
+        Get a single pull request by number for a given repository.
+        """
+        # Try cache first
+        cached = next(
+            (
+                pr
+                for pr in _docs_cache[DOCUMENTATION.PRS].get(repo, [])
+                if pr["number"] == number
+            ),
+            None,
+        )
+        if cached:
+            return cached
+        # Fallback to live fetch
+        return await documentation_utils.get_issue(repo, number)
+
+    # Register tools
+    @mcp.tool("search_documentation")
+    async def search_documentation(query: str):
+        """
+        Search all documentation for a specific query.
+
+        Args:
+            query: Search term
+
+        Returns:
+            Dictionary with search results organized by documentation type
+        """
+        results = {
+            DOCUMENTATION.README: [],
+            DOCUMENTATION.WIKI: [],
+            DOCUMENTATION.ISSUES: [],
+            DOCUMENTATION.PRS: [],
+            DOCUMENTATION.PACKAGEDOWN: [],
+        }
+        # Simple text search
+        for readme_name, content in _docs_cache[DOCUMENTATION.README].items():
+            if query.lower() in content.lower():
+                results[DOCUMENTATION.README].append(
+                    {
+                        "name": readme_name,
+                        "snippet": mcp_utils.get_snippet(content, query),
+                    }
+                )
+        return results

napistu/mcp/documentation_utils.py

@@ -0,0 +1,235 @@
+"""
+Utilities for loading and processing documentation.
+"""
+
+import base64
+import httpx
+import os
+from napistu.constants import PACKAGE_DEFS
+from napistu.mcp.constants import (
+    DEFAULT_GITHUB_API,
+    GITHUB_ISSUES_INDEXED,
+    GITHUB_PRS_INDEXED,
+)
+
+
+async def load_readme_content(readme_url: str) -> str:
+    if readme_url.startswith("http://") or readme_url.startswith("https://"):
+        async with httpx.AsyncClient() as client:
+            response = await client.get(readme_url)
+            response.raise_for_status()
+            return response.text
+    else:
+        raise ValueError(
+            f"Only HTTP(S) URLs are supported for documentation paths: {readme_url}"
+        )
+
+
+async def list_wiki_pages(
+    repo: str,
+    owner: str = PACKAGE_DEFS.GITHUB_OWNER,
+    github_api: str = DEFAULT_GITHUB_API,
+) -> list:
+    """
+    List all Markdown (.md) page names in a GitHub wiki using the GitHub API.
+
+    Parameters
+    ----------
+    repo : str, optional
+        The repository name.
+    owner : str, optional
+        The GitHub username or organization (default is 'napistu').
+    github_api : str, optional
+        The GitHub API base URL (default is 'https://api.github.com').
+
+    Returns
+    -------
+    list of str
+        List of page names (e.g., ['Home.md', 'Some-Page.md'])
+    """
+    wiki_repo = f"{repo}.wiki"
+    url = f"{github_api}/repos/{owner}/{wiki_repo}/contents/"
+    async with httpx.AsyncClient(headers=_get_github_headers()) as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        return [item["name"] for item in resp.json() if item["name"].endswith(".md")]
+
+
+async def fetch_wiki_page(
+    page_name: str,
+    repo: str,
+    owner: str = PACKAGE_DEFS.GITHUB_OWNER,
+    github_api: str = DEFAULT_GITHUB_API,
+) -> str:
+    """
+    Fetch the decoded Markdown content of a given wiki page from a GitHub wiki.
+
+    Parameters
+    ----------
+    page_name : str
+        The name of the page file (e.g., 'Home.md').
+    repo : str, optional
+        The repository name.
+    owner : str, optional
+        The GitHub username or organization (default is 'napistu').
+    github_api : str, optional
+        The GitHub API base URL (default is 'https://api.github.com').
+
+    Returns
+    -------
+    str
+        The Markdown content as a string.
+    """
+    wiki_repo = f"{repo}.wiki"
+    url = f"{github_api}/repos/{owner}/{wiki_repo}/contents/{page_name}"
+    async with httpx.AsyncClient(headers=_get_github_headers()) as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        data = resp.json()
+        content = base64.b64decode(data["content"]).decode("utf-8")
+        return content
+
+
+async def list_issues(
+    repo: str,
+    owner: str = PACKAGE_DEFS.GITHUB_OWNER,
+    github_api: str = DEFAULT_GITHUB_API,
+    state: str = GITHUB_ISSUES_INDEXED,
+    include_prs: bool = False,
+) -> list:
+    """
+    List issues (and optionally PRs) for a given GitHub repository using the GitHub API.
+
+    Parameters
+    ----------
+    repo : str, optional
+        The repository name.
+    owner : str, optional
+        The GitHub username or organization (default is 'napistu').
+    github_api : str, optional
+        The GitHub API base URL (default is 'https://api.github.com').
+    state : str, optional
+        The state of the issues to return. Can be 'open', 'closed', or 'all'. Default is 'open'.
+    include_prs : bool, optional
+        If True, include pull requests in the results. Default is False.
+
+    Returns
+    -------
+    list of dict
+        Each dict contains: number, title, state, url, and a truncated body (max 500 chars).
+    """
+    url = f"{github_api}/repos/{owner}/{repo}/issues?state={state}"
+    filter_func = (
+        (lambda item: True)
+        if include_prs
+        else (lambda item: "pull_request" not in item)
+    )
+    return await _fetch_github_items(url, filter_func=filter_func)
+
+
+async def list_pull_requests(
+    repo: str,
+    owner: str = PACKAGE_DEFS.GITHUB_OWNER,
+    github_api: str = DEFAULT_GITHUB_API,
+    state: str = GITHUB_PRS_INDEXED,
+) -> list:
+    """
+    List pull requests for a given GitHub repository using the GitHub API.
+
+    Parameters
+    ----------
+    repo : str, optional
+        The repository name.
+    owner : str, optional
+        The GitHub username or organization (default is 'napistu').
+    github_api : str, optional
+        The GitHub API base URL (default is 'https://api.github.com').
+    state : str, optional
+        The state of the PRs to return. Can be 'open', 'closed', or 'all'. Default is 'open'.
+
+    Returns
+    -------
+    list of dict
+        Each dict contains: number, title, state, url, and a truncated body (max 500 chars).
+    """
+    url = f"{github_api}/repos/{owner}/{repo}/pulls?state={state}"
+    return await _fetch_github_items(url)
+
+
+async def get_issue(
+    repo: str,
+    number: int,
+    owner: str = PACKAGE_DEFS.GITHUB_OWNER,
+    github_api: str = DEFAULT_GITHUB_API,
+) -> dict:
+    """
+    Get a single issue (or PR) by number from a GitHub repository.
+
+    Parameters
+    ----------
+    repo : str
+        The repository name.
+    number : int
+        The issue or PR number.
+    owner : str, optional
+        The GitHub username or organization (default is 'napistu').
+    github_api : str, optional
+        The GitHub API base URL (default is 'https://api.github.com').
+
+    Returns
+    -------
+    dict
+        The issue or PR details as a dictionary.
+    """
+    url = f"{github_api}/repos/{owner}/{repo}/issues/{number}"
+    async with httpx.AsyncClient(headers=_get_github_headers()) as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        item = resp.json()
+        return _format_github_issue(item)
+
+
+def _get_github_headers():
+    """
+    Return headers for GitHub API requests, including Authorization if GITHUB_TOKEN is set.
+    """
+    headers = {}
+
+    GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
+    if GITHUB_TOKEN:
+        print("Using token from environment variable GITHUB_TOKEN")
+        headers["Authorization"] = f"token {GITHUB_TOKEN}"
+    return headers
+
+
+def _format_github_issue(item):
+    """
+    Format a GitHub issue or PR item into a standard dict.
+    """
+    return {
+        "number": item["number"],
+        "title": item["title"],
+        "state": item["state"],
+        "url": item["html_url"],
+        "body": (
+            (item["body"][:500] + "...")
+            if item.get("body") and len(item["body"]) > 500
+            else item.get("body")
+        ),
+        "is_pr": "pull_request" in item or "merged_at" in item,
+    }
+
+
+async def _fetch_github_items(url, filter_func=None):
+    """
+    Fetch and format a list of GitHub issues or PRs from a given API endpoint.
+    """
+    async with httpx.AsyncClient(headers=_get_github_headers()) as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        items = []
+        for item in resp.json():
+            if filter_func and not filter_func(item):
+                continue
+            items.append(_format_github_issue(item))
+        return items