miqa-mcp 0.1.0__tar.gz

miqa_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# python build + env artifacts (this dir is intentionally not a git repo yet,
+# but keeping this here means a later `git init` stays clean).
+.venv/
+*.egg-info/
+__pycache__/
+*.pyc
+dist/
+build/
+.pytest_cache/

miqa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: miqa-mcp
+Version: 0.1.0
+Summary: MIQA MCP Server
+Author: MIQA / Magna Labs
+License: MIT
+Keywords: claude,fastmcp,mcp,miqa
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: miqatools>=2.0.0rc0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MIQA MCP
+
+A read-only MCP server built with FastMCP. It exposes MIQA test-reporting data to
+Claude Code (and any MCP client) over stdio. It is a thin MCP surface on top of the
+[`miqatools`](../magna-cli) library: the tools call `miqatools`' read-only reporting
+wrappers, which resolve credentials and talk to the MIQA v2 REST API.
+
+The packaging shape — a console script that runs a stdio `main()`, configured via
+environment variables — is what makes it registerable with `claude mcp add`.
+
+Tools exposed (all READ-ONLY; none mutate MIQA state):
+
+- `find_runs_by_version(version_name: str, limit: int = 100) -> list` — find Test
+  Chain Runs for a version name (newest-first; empty list if none match).
+- `get_test_run(run_id: int, sample_ds_id: int | None = None) -> dict` — JSON details
+  for a single Test Chain Run (optionally narrowed to one sample).
+- `get_test_run_results(run_id: int, sample_ds_id: int | None = None)` — the
+  assertion/result summary table (JSON or CSV depending on the server).
+- `get_test_run_report(run_id: int, sample_ds_id: int | None = None, format="json")` —
+  the sample-centric structured report (feature-flag gated on the server).
+
+Built on the standalone `fastmcp` package (jlowin). Requires Python >= 3.10.
+
+## Configuration
+
+The server reads its MIQA credentials from environment variables (resolved by the
+`miqatools` client):
+
+- `MIQA_SERVER_URL` — MIQA server hostname (e.g. `yourco.miqa.io`).
+- `MIQA_API_KEY` — MIQA API key.
+
+Claude Code injects these into the server subprocess via the `--env` block (see
+"Register with Claude Code" below).
+
+## Prerequisite: install miqatools first (not yet on PyPI)
+
+This server depends on `miqatools>=2.0.0rc0`, which is **not yet published to PyPI**.
+Until it is, install `miqatools` from its local checkout first (editable), then install
+this server:
+
+```
+pip install -e ../magna-cli   # the miqatools library
+pip install -e .              # this server
+```
+
+Once `miqatools` is published, `pip install .` (or `uvx miqa-mcp`) will resolve it from
+PyPI automatically and this extra step goes away.
+
+---
+
+## 1. Install options
+
+Because `miqatools` is not yet on PyPI (see "Prerequisite" above), install it locally
+first, then install this server. A plain virtualenv with editable installs is best while
+`miqatools` is unpublished:
+
+```
+python -m venv .venv
+.venv/bin/pip install -e ../magna-cli   # miqatools (the library dependency)
+.venv/bin/pip install -e .              # this server
+```
+
+The console script then lives at `.venv/bin/miqa-mcp`. It starts and waits silently on
+stdin — that is correct: it is a stdio MCP server waiting for a client to speak the
+protocol. Press Ctrl-C to stop; you normally let Claude Code launch it rather than running
+it by hand.
+
+### Eventual published form
+
+Once both `miqatools` and this server are published to PyPI, the local-editable dance
+collapses to a normal install (dependencies resolve automatically):
+
+```
+uvx miqa-mcp        # ephemeral
+pipx install miqa-mcp
+```
+
+---
+
+## 2. Register with Claude Code
+
+`claude mcp add <name> [flags] -- <command> [args...]` registers a stdio server. Claude
+Code launches `<command>` as a subprocess and speaks MCP over its stdin/stdout. The `--`
+separates Claude's own flags from the subprocess command line.
+
+Since `miqatools` is unpublished, install into a venv (see above) so `miqa-mcp` is on the
+venv's PATH, then register that console script — passing MIQA credentials via `--env`:
+
+```
+claude mcp add miqa-mcp \
+  --env MIQA_SERVER_URL=yourco.miqa.io \
+  --env MIQA_API_KEY=your-key-here \
+  -- /absolute/path/to/.venv/bin/miqa-mcp
+```
+
+If `miqa-mcp` is already on your PATH (activated venv or pipx install), the command is just
+the script name:
+
+```
+claude mcp add miqa-mcp --env MIQA_SERVER_URL=yourco.miqa.io --env MIQA_API_KEY=your-key-here -- miqa-mcp
+```
+
+### Passing configuration via env
+
+A stdio server cannot receive HTTP headers, so its configuration is passed as environment
+variables, which Claude Code injects into the subprocess. Use `--env KEY=value` (short form
+`-e KEY=value`), and put it before the `--` so it is read as one of Claude's own flags.
+
+This server reads `MIQA_SERVER_URL` and `MIQA_API_KEY` from its environment (the
+`miqatools` client resolves them), so both must be passed via `--env`:
+
+```
+claude mcp add miqa-mcp --env MIQA_SERVER_URL=yourco.miqa.io --env MIQA_API_KEY=your-key-here -- /absolute/path/to/.venv/bin/miqa-mcp
+```
+
+Repeat `--env` for each variable. This env-block mechanism is the stdio equivalent of the
+`--header` flag that HTTP-transport servers use; stdio servers get their config through env,
+not headers.
+
+By default the server is registered at `local` scope (this project only). Add
+`--scope user` to make it available across all your projects.
+
+---
+
+## 3. Verify
+
+List registered servers — `miqa-mcp` should appear, and Claude Code will have started it
+and confirmed the connection:
+
+```
+claude mcp list
+```
+
+You can also inspect just this one:
+
+```
+claude mcp get miqa-mcp
+```
+
+Inside a Claude Code session, the tools surface as `find_runs_by_version`, `get_test_run`,
+`get_test_run_results`, and `get_test_run_report`. With valid `MIQA_SERVER_URL` /
+`MIQA_API_KEY` in the env, ask the session to find runs for a version name and it will call
+the MIQA API through the server.
+
+---
+
+## 4. Remove
+
+```
+claude mcp remove miqa-mcp
+```
+
+If you installed with pipx and want to uninstall the package too:
+
+```
+pipx uninstall miqa-mcp
+```
+
+---
+
+## 5. Run the tests
+
+The test suite asserts the four tools register on the FastMCP instance and that each
+delegates to the corresponding `miqatools` wrapper (the wrappers are mocked, so no network
+is touched). Install `miqatools` first, then this package with its dev extra:
+
+```
+.venv/bin/pip install -e ../magna-cli
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+---
+
+## 6. How this fits together
+
+This server is a thin, read-only MCP surface; all MIQA client logic lives in the
+`miqatools` library. The reporting wrappers (`find_tcrs_by_version`, `get_tcr_summary`,
+`get_tcr_report`) and the existing `get_tcr_info_json` helper stay in `miqatools` as client
+code; this repo only adds the FastMCP tools and the stdio entry point. The packaging shape —
+console script -> stdio `main()` -> env-based config (`MIQA_SERVER_URL`, `MIQA_API_KEY`) — is
+what `claude mcp add` launches.

miqa_mcp-0.1.0/README.md

@@ -0,0 +1,182 @@
+# MIQA MCP
+
+A read-only MCP server built with FastMCP. It exposes MIQA test-reporting data to
+Claude Code (and any MCP client) over stdio. It is a thin MCP surface on top of the
+[`miqatools`](../magna-cli) library: the tools call `miqatools`' read-only reporting
+wrappers, which resolve credentials and talk to the MIQA v2 REST API.
+
+The packaging shape — a console script that runs a stdio `main()`, configured via
+environment variables — is what makes it registerable with `claude mcp add`.
+
+Tools exposed (all READ-ONLY; none mutate MIQA state):
+
+- `find_runs_by_version(version_name: str, limit: int = 100) -> list` — find Test
+  Chain Runs for a version name (newest-first; empty list if none match).
+- `get_test_run(run_id: int, sample_ds_id: int | None = None) -> dict` — JSON details
+  for a single Test Chain Run (optionally narrowed to one sample).
+- `get_test_run_results(run_id: int, sample_ds_id: int | None = None)` — the
+  assertion/result summary table (JSON or CSV depending on the server).
+- `get_test_run_report(run_id: int, sample_ds_id: int | None = None, format="json")` —
+  the sample-centric structured report (feature-flag gated on the server).
+
+Built on the standalone `fastmcp` package (jlowin). Requires Python >= 3.10.
+
+## Configuration
+
+The server reads its MIQA credentials from environment variables (resolved by the
+`miqatools` client):
+
+- `MIQA_SERVER_URL` — MIQA server hostname (e.g. `yourco.miqa.io`).
+- `MIQA_API_KEY` — MIQA API key.
+
+Claude Code injects these into the server subprocess via the `--env` block (see
+"Register with Claude Code" below).
+
+## Prerequisite: install miqatools first (not yet on PyPI)
+
+This server depends on `miqatools>=2.0.0rc0`, which is **not yet published to PyPI**.
+Until it is, install `miqatools` from its local checkout first (editable), then install
+this server:
+
+```
+pip install -e ../magna-cli   # the miqatools library
+pip install -e .              # this server
+```
+
+Once `miqatools` is published, `pip install .` (or `uvx miqa-mcp`) will resolve it from
+PyPI automatically and this extra step goes away.
+
+---
+
+## 1. Install options
+
+Because `miqatools` is not yet on PyPI (see "Prerequisite" above), install it locally
+first, then install this server. A plain virtualenv with editable installs is best while
+`miqatools` is unpublished:
+
+```
+python -m venv .venv
+.venv/bin/pip install -e ../magna-cli   # miqatools (the library dependency)
+.venv/bin/pip install -e .              # this server
+```
+
+The console script then lives at `.venv/bin/miqa-mcp`. It starts and waits silently on
+stdin — that is correct: it is a stdio MCP server waiting for a client to speak the
+protocol. Press Ctrl-C to stop; you normally let Claude Code launch it rather than running
+it by hand.
+
+### Eventual published form
+
+Once both `miqatools` and this server are published to PyPI, the local-editable dance
+collapses to a normal install (dependencies resolve automatically):
+
+```
+uvx miqa-mcp        # ephemeral
+pipx install miqa-mcp
+```
+
+---
+
+## 2. Register with Claude Code
+
+`claude mcp add <name> [flags] -- <command> [args...]` registers a stdio server. Claude
+Code launches `<command>` as a subprocess and speaks MCP over its stdin/stdout. The `--`
+separates Claude's own flags from the subprocess command line.
+
+Since `miqatools` is unpublished, install into a venv (see above) so `miqa-mcp` is on the
+venv's PATH, then register that console script — passing MIQA credentials via `--env`:
+
+```
+claude mcp add miqa-mcp \
+  --env MIQA_SERVER_URL=yourco.miqa.io \
+  --env MIQA_API_KEY=your-key-here \
+  -- /absolute/path/to/.venv/bin/miqa-mcp
+```
+
+If `miqa-mcp` is already on your PATH (activated venv or pipx install), the command is just
+the script name:
+
+```
+claude mcp add miqa-mcp --env MIQA_SERVER_URL=yourco.miqa.io --env MIQA_API_KEY=your-key-here -- miqa-mcp
+```
+
+### Passing configuration via env
+
+A stdio server cannot receive HTTP headers, so its configuration is passed as environment
+variables, which Claude Code injects into the subprocess. Use `--env KEY=value` (short form
+`-e KEY=value`), and put it before the `--` so it is read as one of Claude's own flags.
+
+This server reads `MIQA_SERVER_URL` and `MIQA_API_KEY` from its environment (the
+`miqatools` client resolves them), so both must be passed via `--env`:
+
+```
+claude mcp add miqa-mcp --env MIQA_SERVER_URL=yourco.miqa.io --env MIQA_API_KEY=your-key-here -- /absolute/path/to/.venv/bin/miqa-mcp
+```
+
+Repeat `--env` for each variable. This env-block mechanism is the stdio equivalent of the
+`--header` flag that HTTP-transport servers use; stdio servers get their config through env,
+not headers.
+
+By default the server is registered at `local` scope (this project only). Add
+`--scope user` to make it available across all your projects.
+
+---
+
+## 3. Verify
+
+List registered servers — `miqa-mcp` should appear, and Claude Code will have started it
+and confirmed the connection:
+
+```
+claude mcp list
+```
+
+You can also inspect just this one:
+
+```
+claude mcp get miqa-mcp
+```
+
+Inside a Claude Code session, the tools surface as `find_runs_by_version`, `get_test_run`,
+`get_test_run_results`, and `get_test_run_report`. With valid `MIQA_SERVER_URL` /
+`MIQA_API_KEY` in the env, ask the session to find runs for a version name and it will call
+the MIQA API through the server.
+
+---
+
+## 4. Remove
+
+```
+claude mcp remove miqa-mcp
+```
+
+If you installed with pipx and want to uninstall the package too:
+
+```
+pipx uninstall miqa-mcp
+```
+
+---
+
+## 5. Run the tests
+
+The test suite asserts the four tools register on the FastMCP instance and that each
+delegates to the corresponding `miqatools` wrapper (the wrappers are mocked, so no network
+is touched). Install `miqatools` first, then this package with its dev extra:
+
+```
+.venv/bin/pip install -e ../magna-cli
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+---
+
+## 6. How this fits together
+
+This server is a thin, read-only MCP surface; all MIQA client logic lives in the
+`miqatools` library. The reporting wrappers (`find_tcrs_by_version`, `get_tcr_summary`,
+`get_tcr_report`) and the existing `get_tcr_info_json` helper stay in `miqatools` as client
+code; this repo only adds the FastMCP tools and the stdio entry point. The packaging shape —
+console script -> stdio `main()` -> env-based config (`MIQA_SERVER_URL`, `MIQA_API_KEY`) — is
+what `claude mcp add` launches.

miqa_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "miqa-mcp"
+version = "0.1.0"
+description = "MIQA MCP Server"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "MIQA / Magna Labs" }]
+keywords = ["mcp", "fastmcp", "claude", "miqa"]
+dependencies = [
+    "fastmcp>=2.0",
+    "miqatools>=2.0.0rc0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+miqa-mcp = "miqa_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/miqa_mcp"]

miqa_mcp-0.1.0/src/miqa_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""MIQA MCP — a read-only FastMCP server over the miqatools client."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("miqa-mcp")
+except PackageNotFoundError:
+    # running from a source checkout that was never installed.
+    __version__ = "0.0.0+source"
+
+__all__ = ["__version__"]

miqa_mcp-0.1.0/src/miqa_mcp/server.py

@@ -0,0 +1,92 @@
+"""MIQA MCP server - a FastMCP surface over the miqatools client"""
+
+from typing import Optional
+
+from fastmcp import FastMCP
+
+from miqatools.reporting import (
+    find_tcrs_by_version,
+    get_tcr_report,
+    get_tcr_summary,
+)
+from miqatools.remoteexecution.triggertest_helpers import get_tcr_info_json
+
+mcp = FastMCP("miqa-mcp")
+
+
+@mcp.tool
+def find_runs_by_version(version_name: str, limit: int = 100) -> list:
+    """Find Miqa Test Chain Runs for a given version name.
+
+    Results are newest-first. Returns an empty list when nothing matches.
+
+    Args:
+        version_name: The version identifier to search for (e.g. "bcftools:1.4.1").
+        limit: Maximum number of runs to return (default 100).
+
+    Returns:
+        A list of run summary dicts, each including id, testchain_id,
+        testchain_name, status, outcome, version_name, start and end.
+    """
+    return find_tcrs_by_version(version_name=version_name, limit=limit)
+
+
+@mcp.tool
+def get_test_run(run_id: int, sample_ds_id: Optional[int] = None) -> dict:
+    """Get JSON details describing a single Miqa Test Chain Run.
+
+    Args:
+        run_id: The Miqa Test Chain Run ID.
+        sample_ds_id: Optional Datasource (sample) ID to narrow the details to
+            a single sample within the run.
+
+    Returns:
+        A dict describing the Test Chain Run.
+    """
+    return get_tcr_info_json(run_id, ds_id=sample_ds_id)
+
+
+@mcp.tool
+def get_test_run_results(run_id: int, sample_ds_id: Optional[int] = None):
+    """Get the assertion/result summary table for a Miqa Test Chain Run.
+
+    The response may be JSON (dict/list) or CSV/plain text depending on the
+    server configuration.
+
+    Args:
+        run_id: The Miqa Test Chain Run ID.
+        sample_ds_id: Optional Datasource (sample) ID to narrow the summary to
+            a single sample.
+
+    Returns:
+        Parsed JSON when the server returns JSON, otherwise the raw text body
+        (e.g. CSV).
+    """
+    return get_tcr_summary(run_id, ds_id=sample_ds_id)
+
+
+@mcp.tool
+def get_test_run_report(run_id: int, sample_ds_id: Optional[int] = None, format: str = "json"):
+    """Get the sample-centric structured report for a Miqa Test Chain Run.
+
+    This report is gated by a server feature flag; if it is disabled the call
+    raises an error and the caller should fall back to get_test_run_results.
+
+    Args:
+        run_id: The Miqa Test Chain Run ID.
+        sample_ds_id: Optional Datasource (sample) ID to narrow the report to a
+            single sample.
+        format: Report mode; "json" (default) returns structured JSON.
+
+    Returns:
+        The structured report (JSON) as returned by the server.
+    """
+    return get_tcr_report(run_id, mode=format, ds_id=sample_ds_id)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

miqa_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,68 @@
+import pytest
+
+# The server depends on fastmcp (and miqatools); skip if fastmcp is absent.
+pytest.importorskip("fastmcp")
+
+from miqa_mcp import server  # noqa: E402
+
+
+EXPECTED_TOOLS = {
+    "find_runs_by_version",
+    "get_test_run",
+    "get_test_run_results",
+    "get_test_run_report",
+}
+
+
+def _registered_tool_names():
+    """Return the set of registered tool names across fastmcp versions.
+
+    FastMCP exposes registered tools via an (async) ``list_tools()`` /
+    ``get_tools()`` API; handle both coroutine and sync return values.
+    """
+    import asyncio
+    import inspect
+
+    mcp = server.mcp
+    lister = getattr(mcp, "list_tools", None) or getattr(mcp, "get_tools", None)
+    assert lister is not None, "Could not introspect registered FastMCP tools"
+
+    tools = lister()
+    if inspect.iscoroutine(tools):
+        tools = asyncio.run(tools)
+
+    if isinstance(tools, dict):
+        return set(tools.keys())
+    return {t.name for t in tools}
+
+
+def test_exactly_four_read_tools_registered():
+    names = _registered_tool_names()
+    # Exactly the four read tools — no mutating tools, no leftover demo tools.
+    assert names == EXPECTED_TOOLS
+
+
+def test_main_calls_run(monkeypatch):
+    called = {}
+    monkeypatch.setattr(server.mcp, "run", lambda *a, **k: called.setdefault("ran", True))
+    server.main()
+    assert called.get("ran") is True
+
+
+def test_tools_delegate_to_miqatools_wrappers(monkeypatch):
+    """Each tool delegates to the corresponding miqatools wrapper (no network)."""
+    monkeypatch.setattr(server, "find_tcrs_by_version", lambda version_name, limit=100: ["run"])
+    monkeypatch.setattr(server, "get_tcr_info_json", lambda run_id, ds_id=None: {"id": run_id})
+    monkeypatch.setattr(server, "get_tcr_summary", lambda run_id, ds_id=None: "summary")
+    monkeypatch.setattr(
+        server, "get_tcr_report", lambda run_id, mode="json", ds_id=None: {"mode": mode}
+    )
+
+    # FastMCP may wrap the function; unwrap via .fn when present.
+    def _fn(tool_obj):
+        return getattr(tool_obj, "fn", tool_obj)
+
+    assert _fn(server.find_runs_by_version)("bcftools:1.4.1") == ["run"]
+    assert _fn(server.get_test_run)(1386) == {"id": 1386}
+    assert _fn(server.get_test_run_results)(1386) == "summary"
+    assert _fn(server.get_test_run_report)(1386) == {"mode": "json"}