Metadata-Version: 2.5
Name: miqa-mcp
Version: 0.2.12
Summary: MIQA MCP Server
Author: MIQA / Magna Labs
License: MIT
Keywords: claude,fastmcp,mcp,miqa
Requires-Python: >=3.10
Requires-Dist: fastmcp<4,>=3.4
Requires-Dist: miqatools<3,>=2.0.0rc12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Description-Content-Type: text/markdown

# MIQA MCP

An [MCP](https://modelcontextprotocol.io) server that connects your AI assistant to
MIQA. Ask about test runs in plain English, pull results and sample metadata, and
create component versions or kick off tests — without leaving your editor or terminal.

Works with Claude Code, Cursor, and any other MCP client that speaks stdio.

## Requirements

- [uv](https://docs.astral.sh/uv/) (`brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`)
- A MIQA server URL and API key

## Quickstart

There is nothing to install — `uvx` downloads and runs the server on demand.

### Claude Code

```bash
claude mcp add miqa-mcp \
  --scope user \
  -e MIQA_SERVER_URL=yourco.miqa.io \
  -e MIQA_API_KEY=your-key-here \
  -- uvx --refresh --prerelease=allow miqa-mcp
```

Confirm it registered with `claude mcp list`, and remove it with `claude mcp remove miqa-mcp`.
Use `--scope user` to make it available everywhere, or drop it to register for the
current project only.

### Cursor, Claude Desktop, and other MCP clients

Add this to your client's MCP config file (`~/.cursor/mcp.json` for Cursor,
`claude_desktop_config.json` for Claude Desktop):

```json
{
  "mcpServers": {
    "miqa-mcp": {
      "command": "uvx",
      "args": ["--refresh", "--prerelease=allow", "miqa-mcp"],
      "env": {
        "MIQA_SERVER_URL": "yourco.miqa.io",
        "MIQA_API_KEY": "your-key-here"
      }
    }
  }
}
```

Restart the client afterwards so it picks up the new server.

> `--prerelease=allow` is required while the `miqatools` dependency is on a prerelease.
> Pin a release with `miqa-mcp@0.2.3` if you want reproducible behavior instead of
> always tracking the latest.

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `MIQA_SERVER_URL` | Yes | Your MIQA hostname or API base URL, e.g. `yourco.miqa.io`. Also used to build browser links back into MIQA. |
| `MIQA_API_KEY` | Yes | Your MIQA API key. |
| `MIQA_DOCS_BASE_URL` | No | Base URL for the published MIQA documentation. Used by the output-explorer-translator skill's fallback when no local `miqa-docs` checkout exists. The URL embeds an unlisted-share credential — treat it as a secret: set it only in the environment, never commit it to any file or example. |

## Example prompts

Once the server is connected, talk to your assistant normally:

**Investigating a run**

- "Show me the test chain runs for version `bcftools:1.4.1`."
- "What failed in run 48210? Summarize the assertions that didn't pass."
- "Pull the full report for run 48210 and group the failures by sample."
- "Which sample files went into run 48210, and where did they come from?"
- "What was the execution environment for run 48210?"

**Comparing and tracking versions**

- "List the last 20 versions of component 512 and tell me which ones are one-offs."
- "Has anything run through trigger `abc123` in the last week? Show me the outcomes."
- "Compare the results of the two most recent runs for version `bcftools:1.4.1`."

**Making changes**

- "For trigger `abc123`, create a new component version using docker image
  `myrepo/aligner:2.3.0` — show me the diff first."
- "Update the main command on trigger `abc123` to add `--threads 8` and preview the change."
- "Create version `v2.3.0-rc1` from base version 8891, then run it through trigger `abc123`."

Write operations always preview first and wait for your confirmation — see
[Safety model](#safety-model).

## Tools

### Read-only

| Tool | What it does |
| --- | --- |
| `find_runs_by_version` | Finds test chain runs for a version name, newest first. |
| `find_runs_by_chain_name` | Finds test chain runs by their parent test chain name, newest first. |
| `list_test_triggers` | Lists every trigger with its last successful run date, to resolve a name to an ID. |
| `get_test_run` | Returns details for a single run. |
| `get_test_run_results` | Returns the assertion and result summary table. |
| `get_test_run_report` | Returns the sample-centric structured report. |
| `get_test_run_sample_metadata` | Returns sample names, datasource IDs, and original sources. |
| `get_test_run_environment` | Returns the captured test and execution environment. |
| `get_trigger_template_json` | Returns the components, templates, and edit capabilities a trigger reaches. |
| `list_component_versions` | Lists a component's versions, newest first. |
| `list_trigger_runs` | Lists the runs actually created by a trigger, newest first. |

### Writes

| Tool | What it does |
| --- | --- |
| `create_component_version` | Creates a new component version from a base version. |
| `run_test_trigger` | Runs a trigger against one existing component version. |

Most read tools accept an optional sample (datasource) ID to narrow the response to a
single sample. A few tools depend on server-side feature flags and may be unavailable
on older MIQA deployments.

## Safety model

Both write tools are **preview-first**. They run as a dry run unless you explicitly
opt in, so an assistant can never change or launch something on your behalf by accident.

**`create_component_version`** — By default nothing is persisted: it returns a
validation verdict and a diff of the version it *would* create. Your assistant shows
you that diff and needs your explicit go-ahead before applying it. Applying saves the
new version; it never starts a test run. After a successful apply you get a link to the
resource in MIQA, and the assistant will offer to preview a run for you. Its optional
`is_oneoff` flag marks the created ComponentVersion so it is excluded from "latest
version" base resolution for future creates — it does not select a base version or
start any run.

**`run_test_trigger`** — Also preview-only by default. Applying creates a one-off
workflow version and starts the configured test chain. It accepts one component version
override and one unambiguous baseline state machine, and it does not poll the resulting
run — ask for the run status separately.

These two "one-off" concepts are unrelated: `create_component_version`'s `is_oneoff`
marks a ComponentVersion row, while `run_test_trigger`'s one-off is a StateMachine/workflow
created for that single run. Applying `run_test_trigger` never changes a ComponentVersion's
`is_oneoff` flag.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Server doesn't appear in the client | Confirm `uvx` is on your `PATH` and restart the client. Claude Code users can check with `claude mcp get miqa-mcp`. |
| Authentication or 401 errors | Re-check `MIQA_API_KEY` and that `MIQA_SERVER_URL` points at the right MIQA instance. |
| A tool reports it is unavailable | That endpoint is gated by a feature flag or missing on your MIQA version. For reports, fall back to `get_test_run_results`. |
| Stale behavior after an upgrade | `--refresh` makes `uvx` re-resolve the package; drop any version pin to move to the latest. |
