bugzilla-mcp 0.6.0__py3-none-any.whl

bugzilla_mcp/__init__.py

@@ -0,0 +1,65 @@
+"""MCP package for Bugzilla server"""
+
+from .tools.bugzilla import (
+    bug_info,
+    bug_comments,
+    add_comment,
+    bugs_quicksearch,
+    learn_quicksearch_syntax,
+    server_url,
+    bug_url,
+    download_attachments,
+    download_attachment,
+    bugs_info,
+    bugs_comments,
+    bugs_analysis_context,
+    classify_bugs_heuristics,
+    analyze_bugs_statistics,
+    create_bug,
+    update_bug,
+    bug_history,
+    bugs_advanced_search,
+    bug_dependencies,
+    duplicate_chain,
+    get_user,
+    search_users,
+    list_products,
+    get_product_components,
+    upload_attachment,
+    tag_comment,
+    bug_attachments,
+    get_attachment,
+    register_tools,
+)
+
+__all__ = [
+    "bug_info",
+    "bug_comments",
+    "add_comment",
+    "bugs_quicksearch",
+    "learn_quicksearch_syntax",
+    "server_url",
+    "bug_url",
+    "download_attachments",
+    "download_attachment",
+    "bugs_info",
+    "bugs_comments",
+    "bugs_analysis_context",
+    "classify_bugs_heuristics",
+    "analyze_bugs_statistics",
+    "create_bug",
+    "update_bug",
+    "bug_history",
+    "bugs_advanced_search",
+    "bug_dependencies",
+    "duplicate_chain",
+    "get_user",
+    "search_users",
+    "list_products",
+    "get_product_components",
+    "upload_attachment",
+    "tag_comment",
+    "bug_attachments",
+    "get_attachment",
+    "register_tools",
+]

bugzilla_mcp/cli.py

@@ -0,0 +1,94 @@
+"""`bugzilla-mcp` command and the server builders shared by server.py / server_local.py"""
+
+import argparse
+import os
+from importlib.metadata import PackageNotFoundError, version
+
+from dotenv import load_dotenv
+from fastmcp import FastMCP
+
+import bugzilla_mcp.utils as utils
+from bugzilla_mcp.middleware import ValidateHeaders
+from bugzilla_mcp.middleware.read_only import ReadOnlyMode, read_only_default
+from bugzilla_mcp.tools.bugzilla import WRITE_TOOL_NAMES, register_tools
+from bugzilla_mcp.utils import Bugzilla
+
+
+def build_local_server(url: str, api_key: str, read_only: bool | None = None) -> FastMCP:
+    """Single-user server: one Bugzilla client for the whole process.
+
+    It may read and write files on this machine (attachment downloads, uploads
+    from a path), because the only user is whoever started it.
+    """
+    # asyncio.run copies this context into the server's tasks, so every tool sees it
+    utils.current_bz.set(Bugzilla(url=url, api_key=api_key, allow_local_files=True))
+
+    mcp = FastMCP("Bugzilla")
+    mcp.add_middleware(ReadOnlyMode(
+        WRITE_TOOL_NAMES,
+        read_only_default() if read_only is None else read_only,
+        allow_header_override=False,
+    ))
+    register_tools(mcp, local_files=True)
+    return mcp
+
+
+def build_http_server(read_only: bool | None = None) -> FastMCP:
+    """Multi-user server: each request brings its own `api_key` / `bugzilla_url` headers.
+
+    Never touches this machine's disk, and clients may send `read_only: false`.
+    """
+    mcp = FastMCP("Bugzilla")
+    mcp.add_middleware(ValidateHeaders())
+    mcp.add_middleware(ReadOnlyMode(
+        WRITE_TOOL_NAMES,
+        read_only_default() if read_only is None else read_only,
+        allow_header_override=True,
+    ))
+    register_tools(mcp, local_files=False)
+    return mcp
+
+
+def _version() -> str:
+    try:
+        return version("bugzilla-mcp")
+    except PackageNotFoundError:  # running from a checkout that isn't installed
+        return "unknown"
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="bugzilla-mcp",
+        description=(
+            "Bugzilla MCP server. stdio (default) reads BUGZILLA_URL and BUGZILLA_API_KEY "
+            "from the environment or a .env file; http takes them from each request's headers."
+        ),
+    )
+    parser.add_argument("--transport", choices=["stdio", "http"], default="stdio")
+    parser.add_argument("--host", default="127.0.0.1", help="http only (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8000, help="http only (default: 8000)")
+    parser.add_argument(
+        "--allow-writes",
+        action="store_true",
+        help="enable tools that change Bugzilla (same as BUGZILLA_READ_ONLY=false)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    args = parser.parse_args(argv)
+
+    load_dotenv()  # optional .env in the current directory
+    read_only = False if args.allow_writes else None  # None: BUGZILLA_READ_ONLY decides
+
+    if args.transport == "stdio":
+        # The API key only comes from the environment: command-line arguments
+        # show up in process lists and shell history.
+        url = os.environ.get("BUGZILLA_URL", "")
+        api_key = os.environ.get("BUGZILLA_API_KEY", "")
+        if not url or not api_key:
+            parser.error("set BUGZILLA_URL and BUGZILLA_API_KEY (environment or .env)")
+        build_local_server(url, api_key, read_only).run(transport="stdio", show_banner=False)
+    else:
+        build_http_server(read_only).run(transport="http", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

bugzilla_mcp/middleware/__init__.py

@@ -0,0 +1,6 @@
+"""Middleware for Bugzilla MCP server"""
+
+from .validate_headers import ValidateHeaders
+
+__all__ = ["ValidateHeaders"]
+

bugzilla_mcp/middleware/read_only.py

@@ -0,0 +1,55 @@
+"""Middleware that hides and blocks write tools unless writes are enabled"""
+
+import os
+from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+READ_ONLY_ENV = "BUGZILLA_READ_ONLY"
+READ_ONLY_HEADER = "read_only"
+
+_FALSE = {"0", "false", "no", "off"}
+
+
+def read_only_default() -> bool:
+    """Read-only unless BUGZILLA_READ_ONLY is explicitly false/0/no/off"""
+    return os.environ.get(READ_ONLY_ENV, "true").strip().lower() not in _FALSE
+
+
+class ReadOnlyMode(Middleware):
+    """Hide write tools from tools/list and refuse calls to them in read-only mode.
+
+    The mode defaults to `default` (from BUGZILLA_READ_ONLY). On the HTTP server a
+    client can override it per request with a `read_only: false` header.
+    """
+
+    def __init__(self, write_tools: set[str], default: bool, allow_header_override: bool):
+        self.write_tools = write_tools
+        self.default = default
+        self.allow_header_override = allow_header_override
+
+    def _read_only(self) -> bool:
+        if self.allow_header_override:
+            value = (get_http_headers() or {}).get(READ_ONLY_HEADER)
+            if value is not None:
+                return value.strip().lower() not in _FALSE
+        return self.default
+
+    async def on_list_tools(self, context: MiddlewareContext, call_next):
+        tools = await call_next(context)
+        if not self._read_only():
+            return tools
+        return [t for t in tools if t.name not in self.write_tools]
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        if context.message.name in self.write_tools and self._read_only():
+            how = (
+                f"send the `{READ_ONLY_HEADER}: false` header"
+                if self.allow_header_override
+                else f"set {READ_ONLY_ENV}=false"
+            )
+            raise ToolError(
+                f"`{context.message.name}` changes data, and this server is in read-only mode. "
+                f"To enable write tools, {how}."
+            )
+        return await call_next(context)

bugzilla_mcp/middleware/validate_headers.py

@@ -0,0 +1,48 @@
+"""Middleware to validate required HTTP headers"""
+
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ValidationError
+from bugzilla_mcp.utils import Bugzilla
+import bugzilla_mcp.utils as utils
+
+
+class ValidateHeaders(Middleware):
+    """Validate incoming HTTP headers
+
+    Requires both `api_key` and `bugzilla_url` headers to be present.
+    Creates a Bugzilla client scoped to the current request (utils.current_bz)
+    and closes it once the request is handled.
+    """
+
+    # on_request, not on_message: since fastmcp 4, on_message also sees notifications
+    # (initialized, cancelled, progress), which never need a Bugzilla client.
+    async def on_request(self, middleware_context: MiddlewareContext, call_next):
+        headers = get_http_headers()
+
+        # During inspection or when headers are not available, skip validation
+        # and use a dummy Bugzilla instance so `fastmcp inspect` works without credentials
+        if not headers:
+            bz = Bugzilla(url="https://bugzilla.example.com", api_key="inspection-placeholder")
+        else:
+            if "api_key" not in headers:
+                raise ValidationError("`api_key` header is required")
+
+            if "bugzilla_url" not in headers:
+                raise ValidationError("`bugzilla_url` header is required")
+
+            bugzilla_url = headers["bugzilla_url"]
+
+            # Normalize URL: add https:// if no protocol is specified
+            if bugzilla_url and not bugzilla_url.startswith(("http://", "https://")):
+                bugzilla_url = f"https://{bugzilla_url}"
+
+            bz = Bugzilla(url=bugzilla_url, api_key=headers["api_key"])
+
+        # all the tools & prompts read this for making api calls
+        token = utils.current_bz.set(bz)
+        try:
+            return await call_next(middleware_context)
+        finally:
+            utils.current_bz.reset(token)
+            await bz.close()

bugzilla_mcp/tools/__init__.py

@@ -0,0 +1,22 @@
+"""Tools package for Bugzilla MCP server"""
+
+from .bugzilla import (
+    bug_info,
+    bug_comments,
+    add_comment,
+    bugs_quicksearch,
+    learn_quicksearch_syntax,
+    server_url,
+    bug_url,
+)
+
+__all__ = [
+    "bug_info",
+    "bug_comments",
+    "add_comment",
+    "bugs_quicksearch",
+    "learn_quicksearch_syntax",
+    "server_url",
+    "bug_url",
+]
+