openqa-mcp 0.1.0__py3-none-any.whl

openqa_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openqa_mcp/__main__.py

@@ -0,0 +1,91 @@
+"""Command-line entry point for the openQA MCP server.
+
+Selects the transport and, for HTTP, the bind address. Flags override the
+environment; the environment (``OPENQA_MCP_TRANSPORT``/``HOST``/``PORT``)
+supplies the defaults. Run with ``openqa-mcp`` or ``python -m openqa_mcp``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+from .server import disable_mutating_tools, mcp
+
+
+def _env_flag(name: str) -> bool:
+    """Interpret an environment variable as a boolean toggle.
+
+    Truthy values (case-insensitive): ``1``, ``true``, ``yes``, ``on``.
+    Anything else (including unset) is false.
+    """
+    return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser.
+
+    ``--http``/``--stdio`` are mutually exclusive; neither (nor
+    ``OPENQA_MCP_TRANSPORT=http``) means stdio. ``--server``/``--port`` set the
+    HTTP bind address, defaulting from ``OPENQA_MCP_HOST``/``OPENQA_MCP_PORT``.
+    """
+    parser = argparse.ArgumentParser(
+        prog="openqa-mcp",
+        description="Run the openQA MCP server over stdio (default) or HTTP.",
+    )
+    transport = parser.add_mutually_exclusive_group()
+    transport.add_argument(
+        "--http",
+        action="store_true",
+        help="serve over HTTP instead of stdio",
+    )
+    transport.add_argument(
+        "--stdio",
+        action="store_true",
+        help="serve over stdio (default; overrides OPENQA_MCP_TRANSPORT=http)",
+    )
+    parser.add_argument(
+        "--server",
+        dest="host",
+        default=os.environ.get("OPENQA_MCP_HOST", "127.0.0.1"),
+        help="HTTP bind host (default: %(default)s, or OPENQA_MCP_HOST)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("OPENQA_MCP_PORT", "8000")),
+        help="HTTP bind port (default: %(default)s, or OPENQA_MCP_PORT)",
+    )
+    parser.add_argument(
+        "--readonly",
+        action="store_true",
+        default=_env_flag("OPENQA_READONLY"),
+        help="disable all mutating tools (default: OPENQA_READONLY)",
+    )
+    return parser
+
+
+def main() -> None:
+    """Parse arguments and run the server on the selected transport."""
+    args = build_parser().parse_args()
+
+    if args.readonly:
+        disable_mutating_tools()
+
+    # An explicit --stdio wins; otherwise --http or the env toggle selects HTTP.
+    http = not args.stdio and (
+        args.http or os.environ.get("OPENQA_MCP_TRANSPORT") == "http"
+    )
+    try:
+        if http:
+            mcp.run(transport="http", host=args.host, port=args.port)
+        else:
+            mcp.run()
+    except KeyboardInterrupt:
+        # Ctrl-C: the lifespan's finally block already closed the client as the
+        # async context unwound; swallow the traceback and exit cleanly.
+        pass
+
+
+if __name__ == "__main__":
+    main()

openqa_mcp/client.py

@@ -0,0 +1,101 @@
+"""Shared ``AsyncOpenQAClient`` construction and FastMCP lifespan wiring.
+
+``get_client`` builds a client from environment configuration, optionally
+overriding the API credentials baked in by ``openqa-async``'s config-file
+loading. ``lifespan`` exposes a single shared client to the server for the
+duration of its run.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+import httpx
+from openqa_async.aclient import AsyncOpenQAClient
+
+_FALSE_TOKENS = frozenset({"0", "false", "no"})
+_TRUE_TOKENS = frozenset({"1", "true", "yes"})
+
+
+def _parse_verify(raw: str | None) -> bool | str:
+    """Map ``OPENQA_VERIFY`` to an httpx ``verify`` value.
+
+    Bool-ish tokens toggle verification; any other non-empty value is
+    treated as a path to a CA bundle. Unset defaults to ``True``.
+    """
+    if raw is None:
+        return True
+    token = raw.strip()
+    lowered = token.lower()
+    if lowered in _FALSE_TOKENS:
+        return False
+    if lowered in _TRUE_TOKENS:
+        return True
+    if token:
+        return token  # CA bundle path
+    return True
+
+
+def _apply_env_credentials(client: AsyncOpenQAClient) -> None:
+    """Override the client's API credentials from the environment.
+
+    Only applied when both ``OPENQA_API_KEY`` and ``OPENQA_API_SECRET``
+    are set, avoiding a half-configured client that signs with an empty
+    secret.
+
+    NOTE (library-internal touch-point): ``AsyncOpenQAClient`` bakes auth
+    into ``self.client`` at construction time -- the httpx client's static
+    ``X-API-Key`` header comes from ``_apikey`` via ``_default_headers()``
+    and the HMAC auth from ``apisecret`` via ``_build_auth()``. Assigning
+    the credentials alone does nothing until ``client.client`` is rebuilt
+    the same way the constructor does. Keep this the only place that
+    reaches into these private attributes; prefer ``client.conf`` in docs.
+    """
+    api_key = os.environ.get("OPENQA_API_KEY")
+    api_secret = os.environ.get("OPENQA_API_SECRET")
+    if not (api_key and api_secret):
+        return
+
+    client._apikey = api_key
+    client.apisecret = api_secret
+    client.client = httpx.AsyncClient(
+        base_url=client.baseurl,
+        headers=client._default_headers(),
+        auth=client._build_auth(),
+        trust_env=True,
+        verify=client.verify,
+    )
+
+
+def get_client() -> AsyncOpenQAClient:
+    """Build a shared ``AsyncOpenQAClient`` from environment configuration.
+
+    Reads ``OPENQA_SERVER`` (empty falls back to the openqa-async default),
+    ``OPENQA_VERIFY``, and optionally ``OPENQA_API_KEY`` /
+    ``OPENQA_API_SECRET`` to override config-file credentials.
+    """
+    server = os.environ.get("OPENQA_SERVER", "")
+    verify = _parse_verify(os.environ.get("OPENQA_VERIFY"))
+    client = AsyncOpenQAClient(server=server, verify=verify)
+    _apply_env_credentials(client)
+    return client
+
+
+@dataclass
+class AppContext:
+    """Shared state made available to tools for the server's lifetime."""
+
+    client: AsyncOpenQAClient
+
+
+@asynccontextmanager
+async def lifespan(server: object) -> AsyncIterator[AppContext]:
+    """Open a single shared client on startup, close it on shutdown."""
+    client = get_client()
+    try:
+        yield AppContext(client=client)
+    finally:
+        await client.aclose()

openqa_mcp/server.py

@@ -0,0 +1,246 @@
+"""Curated openQA MCP tools.
+
+Each tool is a thin, typed wrapper over ``AsyncOpenQAClient.openqa_request``:
+it drops ``None`` params and returns the parsed dict/list body. One-line
+docstrings become the MCP tool descriptions. Mutating tools are tagged
+``mutating`` and require API credentials (openQA answers ``403`` without them).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+from fastmcp import Context, FastMCP
+from openqa_async.aclient import AsyncOpenQAClient
+
+from .client import AppContext, lifespan
+
+#: Tag marking tools that mutate openQA state; stripped in read-only mode.
+MUTATING_TAG = "mutating"
+
+mcp = FastMCP(
+    "openQA",
+    instructions=(
+        "Query and control an openQA instance. Read tools inspect jobs, "
+        "machines, test suites, and products; mutating tools (tagged "
+        "'mutating') restart/cancel/delete jobs, comment, and trigger ISOs, "
+        "and require API credentials."
+    ),
+    lifespan=lifespan,
+)
+
+
+def _client(ctx: Context) -> AsyncOpenQAClient:
+    """Return the shared client from the lifespan context."""
+    return cast(AppContext, ctx.lifespan_context).client
+
+
+def _drop_none(params: dict[str, Any]) -> dict[str, Any]:
+    """Strip keys whose value is ``None`` so they are not sent as query params."""
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _api(path: str) -> str:
+    """Prefix a REST endpoint with ``api/v1/``.
+
+    ``openqa-async`` joins request paths straight onto the server host, so
+    the ``/api/v1`` prefix that fronts every REST endpoint must be supplied
+    here; without it requests hit non-existent web-UI routes and 404.
+    """
+    return f"api/v1/{path}"
+
+
+# --------------------------------------------------------------------------- #
+# READ tools                                                                   #
+# --------------------------------------------------------------------------- #
+
+
+@mcp.tool
+async def list_jobs(
+    ctx: Context,
+    state: str | None = None,
+    result: str | None = None,
+    distri: str | None = None,
+    version: str | None = None,
+    build: str | None = None,
+    test: str | None = None,
+    arch: str | None = None,
+    machine: str | None = None,
+    groupid: int | None = None,
+    group: str | None = None,
+    latest: int | None = None,
+    limit: int | None = None,
+    page: int | None = None,
+    ids: list[int] | None = None,
+) -> dict | list:
+    """List jobs matching the given filters."""
+    params = _drop_none(
+        {
+            "state": state,
+            "result": result,
+            "distri": distri,
+            "version": version,
+            "build": build,
+            "test": test,
+            "arch": arch,
+            "machine": machine,
+            "groupid": groupid,
+            "group": group,
+            "latest": latest,
+            "limit": limit,
+            "page": page,
+            "ids": ids,
+        }
+    )
+    return await _client(ctx).openqa_request("GET", _api("jobs"), params=params)
+
+
+@mcp.tool
+async def list_jobs_overview(
+    ctx: Context,
+    state: str | None = None,
+    result: str | None = None,
+    distri: str | None = None,
+    version: str | None = None,
+    build: str | None = None,
+    test: str | None = None,
+    arch: str | None = None,
+    machine: str | None = None,
+    groupid: int | None = None,
+    group: str | None = None,
+    latest: int | None = None,
+    limit: int | None = None,
+    page: int | None = None,
+    ids: list[int] | None = None,
+) -> dict | list:
+    """List a condensed jobs overview matching the given filters."""
+    params = _drop_none(
+        {
+            "state": state,
+            "result": result,
+            "distri": distri,
+            "version": version,
+            "build": build,
+            "test": test,
+            "arch": arch,
+            "machine": machine,
+            "groupid": groupid,
+            "group": group,
+            "latest": latest,
+            "limit": limit,
+            "page": page,
+            "ids": ids,
+        }
+    )
+    return await _client(ctx).openqa_request(
+        "GET", _api("jobs/overview"), params=params
+    )
+
+
+@mcp.tool
+async def get_job(ctx: Context, job_id: int) -> dict | list:
+    """Get full details for a single job."""
+    return await _client(ctx).openqa_request("GET", _api(f"jobs/{job_id}"))
+
+
+@mcp.tool
+async def get_job_comments(ctx: Context, job_id: int) -> dict | list:
+    """List comments on a job."""
+    return await _client(ctx).openqa_request("GET", _api(f"jobs/{job_id}/comments"))
+
+
+@mcp.tool
+async def list_machines(ctx: Context) -> dict | list:
+    """List configured worker machines."""
+    return await _client(ctx).openqa_request("GET", _api("machines"))
+
+
+@mcp.tool
+async def list_test_suites(ctx: Context) -> dict | list:
+    """List configured test suites."""
+    return await _client(ctx).openqa_request("GET", _api("test_suites"))
+
+
+@mcp.tool
+async def list_products(ctx: Context) -> dict | list:
+    """List configured products (mediums)."""
+    return await _client(ctx).openqa_request("GET", _api("products"))
+
+
+@mcp.tool
+async def find_jobs_by_setting(ctx: Context, key: str, list_value: str) -> dict | list:
+    """Find jobs whose setting ``key`` equals ``list_value``."""
+    params = {"key": key, "list_value": list_value}
+    return await _client(ctx).openqa_request(
+        "GET", _api("job_settings/jobs"), params=params
+    )
+
+
+# --------------------------------------------------------------------------- #
+# MUTATING tools (require credentials; 403 without)                            #
+# --------------------------------------------------------------------------- #
+
+
+@mcp.tool(tags={MUTATING_TAG})
+async def restart_jobs(ctx: Context, job_ids: list[int]) -> list:
+    """Restart each of the given jobs (requires credentials)."""
+    client = _client(ctx)
+    results = []
+    for job_id in job_ids:
+        results.append(
+            await client.openqa_request("POST", _api(f"jobs/{job_id}/restart"))
+        )
+    return results
+
+
+@mcp.tool(tags={MUTATING_TAG})
+async def cancel_job(ctx: Context, job_id: int) -> dict | list:
+    """Cancel a running or scheduled job (requires credentials)."""
+    return await _client(ctx).openqa_request("POST", _api(f"jobs/{job_id}/cancel"))
+
+
+@mcp.tool(tags={MUTATING_TAG})
+async def add_job_comment(ctx: Context, job_id: int, text: str) -> dict | list:
+    """Add a comment to a job (requires credentials)."""
+    return await _client(ctx).openqa_request(
+        "POST", _api(f"jobs/{job_id}/comments"), data={"text": text}
+    )
+
+
+@mcp.tool(tags={MUTATING_TAG})
+async def trigger_isos(
+    ctx: Context,
+    distri: str,
+    version: str,
+    flavor: str,
+    arch: str,
+    extra: dict[str, str] | None = None,
+) -> dict | list:
+    """Trigger ISO test scheduling for a product (requires credentials)."""
+    body = {"DISTRI": distri, "VERSION": version, "FLAVOR": flavor, "ARCH": arch}
+    if extra:
+        body.update(extra)
+    return await _client(ctx).openqa_request("POST", _api("isos"), data=body)
+
+
+@mcp.tool(tags={MUTATING_TAG})
+async def delete_job(ctx: Context, job_id: int) -> dict | list:
+    """Delete a job (requires credentials)."""
+    result = await _client(ctx).openqa_request("DELETE", _api(f"jobs/{job_id}"))
+    # A 204 No Content yields a raw httpx Response, not a dict/list; normalize.
+    return result if isinstance(result, (dict, list)) else {}
+
+
+def disable_mutating_tools() -> list[str]:
+    """Unregister every tool tagged ``mutating`` (read-only mode).
+
+    ``FastMCP.list_tools`` is a coroutine but does no real I/O here, so it is
+    safe to drive with ``asyncio.run`` from the synchronous CLI before
+    ``mcp.run`` starts its own event loop. Returns the removed tool names.
+    """
+    tools = asyncio.run(mcp.list_tools())
+    removed = [t.name for t in tools if MUTATING_TAG in t.tags]
+    for name in removed:
+        mcp.local_provider.remove_tool(name)
+    return removed

openqa_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.3
+Name: openqa-mcp
+Version: 0.1.0
+Summary: Local openQA mcp client
+Requires-Dist: fastmcp>=3.4.3
+Requires-Dist: openqa-async>=0.1.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# openqa-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes curated,
+typed tools over the [openQA](https://open.qa) REST API. It is built on
+[fastmcp](https://github.com/jlowin/fastmcp) 3.x and the
+[openqa-async](https://pypi.org/project/openqa-async/) transport client.
+
+Read tools work anonymously; mutating tools require API credentials and
+return `403` without them.
+
+## Install
+
+```sh
+uv sync
+```
+
+This installs the package and its dependencies into a project virtualenv
+and exposes the `openqa-mcp` console script.
+
+## Configuration
+
+The server reads its configuration from environment variables, falling back
+to the openQA client config file for credentials.
+
+### Environment variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPENQA_SERVER` | openqa-async default | openQA host (e.g. `openqa.opensuse.org`). |
+| `OPENQA_API_KEY` | *(unset)* | API key; overrides the config file when set. |
+| `OPENQA_API_SECRET` | *(unset)* | API secret; overrides the config file when set. |
+| `OPENQA_VERIFY` | `true` | TLS verification: `true`/`false`, or a path to a CA bundle. |
+
+`OPENQA_API_KEY` and `OPENQA_API_SECRET` only take effect when **both** are
+set; a partial pair is ignored so the client is never half-configured.
+
+### Config file
+
+If the env credentials are not set, openqa-async loads them from
+`~/.config/openqa/client.conf` (or `/etc/openqa/client.conf`). Generate a
+key/secret from the *API keys* page of your openQA instance and add a section
+keyed by the host:
+
+```ini
+[openqa.opensuse.org]
+key = YOUR_API_KEY
+secret = YOUR_API_SECRET
+```
+
+Without any credentials the server is GET-only (read tools succeed, mutating
+tools get `403`).
+
+## Tools
+
+### Read tools
+
+| Tool | Description |
+| --- | --- |
+| `list_jobs` | List jobs matching the given filters. |
+| `list_jobs_overview` | List a condensed jobs overview matching the given filters. |
+| `get_job` | Get full details for a single job. |
+| `get_job_comments` | List comments on a job. |
+| `list_machines` | List configured worker machines. |
+| `list_test_suites` | List configured test suites. |
+| `list_products` | List configured products (mediums). |
+| `find_jobs_by_setting` | Find jobs whose setting `key` equals `list_value`. |
+
+`list_jobs` and `list_jobs_overview` accept the same optional filters:
+`state`, `result`, `distri`, `version`, `build`, `test`, `arch`, `machine`,
+`groupid`, `group`, `latest`, `limit`, `page`, `ids`. Unset filters are
+dropped from the request.
+
+### Mutating tools (require credentials)
+
+| Tool | Description |
+| --- | --- |
+| `restart_jobs` | Restart each of the given jobs. |
+| `cancel_job` | Cancel a running or scheduled job. |
+| `add_job_comment` | Add a comment to a job. |
+| `trigger_isos` | Trigger ISO test scheduling for a product. |
+| `delete_job` | Delete a job. |
+
+Mutating tools carry the `mutating` tag so MCP clients can gate them behind
+confirmation. To drop them entirely, start the server in read-only mode with
+`--readonly` (or `OPENQA_READONLY=true`): the mutating tools are never
+registered, so clients see only the read tools.
+
+## Running
+
+### stdio (default)
+
+Most local MCP clients spawn the server over stdio. Wire it in with:
+
+```sh
+uv run openqa-mcp
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "openqa": {
+      "command": "uv",
+      "args": ["run", "openqa-mcp"],
+      "env": {
+        "OPENQA_SERVER": "openqa.opensuse.org"
+      }
+    }
+  }
+}
+```
+
+### HTTP (optional)
+
+For remote or shared deployments, run over HTTP with `--http`:
+
+```sh
+uv run openqa-mcp --http --server 127.0.0.1 --port 8000
+```
+
+The server can also be launched as a module:
+
+```sh
+uv run python -m openqa_mcp --http --port 8000
+```
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--http` | off | Serve over HTTP instead of stdio. |
+| `--stdio` | on | Serve over stdio; overrides `OPENQA_MCP_TRANSPORT=http`. |
+| `--server` | `127.0.0.1` | HTTP bind host. |
+| `--port` | `8000` | HTTP bind port. |
+| `--readonly` | off | Unregister all mutating tools (read-only server). |
+
+Flags override the environment, which supplies the defaults:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPENQA_MCP_TRANSPORT` | `stdio` | Set to `http` to serve over HTTP. |
+| `OPENQA_MCP_HOST` | `127.0.0.1` | Default HTTP bind host. |
+| `OPENQA_MCP_PORT` | `8000` | Default HTTP bind port. |
+| `OPENQA_READONLY` | `false` | Set truthy (`1`/`true`/`yes`/`on`) to disable mutating tools. |
+
+Press `Ctrl-C` to stop; the server shuts down cleanly and closes its client.
+
+## Development
+
+```sh
+uv run pytest        # run the test suite
+uv run ruff check .  # lint
+```

openqa_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+openqa_mcp/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+openqa_mcp/__main__.py,sha256=W4nGmb-0NPJNcvNF0kTLzP95swVLgsWg_RwGQsRUG1k,2888
+openqa_mcp/client.py,sha256=wzslDDudSieh0UN1E_w74lxPO5sZXRX2_o8R6nXXIFU,3374
+openqa_mcp/server.py,sha256=yplE1hT29JzkHth2GDo5h6wfkQ4s7YZtY--Wd6cYPn8,7954
+openqa_mcp-0.1.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
+openqa_mcp-0.1.0.dist-info/entry_points.txt,sha256=UAAZK9lOv7Kh-h22BEUkQV4zPKhTcXQQamOeLQ2kokQ,57
+openqa_mcp-0.1.0.dist-info/METADATA,sha256=Ld_JGrJwo4xNawXQGhIPeCsETyqnHd4nvKToFCOypQs,4842
+openqa_mcp-0.1.0.dist-info/RECORD,,

openqa_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.26
+Root-Is-Purelib: true
+Tag: py3-none-any

openqa_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+openqa-mcp = openqa_mcp.__main__:main
+