npm package: @paul.davis/allure-failure-mcp
Description: This project packages an **MCP server + CLI** that reads an `allure-results/` directory, **skips passed tests**, and **skips tests that had retries but eventually passed**, then writes a single aggregated file (JSONL by default). A separate **LLM summariz
Latest version: 1.0.2

# allure-failure-mcp (Pattern 1: MCP → CLI → LLM)

This project packages an **MCP server + CLI** that reads an `allure-results/` directory, **skips passed tests**, and **skips tests that had retries but eventually passed**, then writes a single aggregated file (JSONL by default). A separate **LLM summarizer script** turns that JSONL into an AI summary suitable for GitHub Actions Job Summary.

## Why this works across Java / Python / Playwright
Allure adapters across languages emit the same `*-result.json` format per test execution. We only read that output folder.

## What you get
- `allure.collect_failures` MCP tool (stdio transport)
- CLI mode for CI: `--mode cli`
- AI summarizer (OpenAI-compatible HTTP API) 
- Sample `sample/allure-results` to test retry skipping
- Example GitHub Actions workflow: `.github/workflows/ci-ai-summary.yml`

---

## Project layout

```
allure-failure-mcp/
  src/
    index.ts                 # entrypoint: MCP server OR CLI
    mcp.ts                   # MCP tool registration (stdio)
    cli.ts                   # CLI runner
    allure/                  # Allure parsing + failure collection
      types.ts
      readResults.ts
      normalize.ts
      collectFailures.ts
    ai/
      ai-summary.ts          # reads JSONL, calls LLM, writes Markdown
      prompts.ts             # prompt builder (strict, structured)
      githubSummary.ts       # writes to GITHUB_STEP_SUMMARY if set
  sample/
    allure-results/          # minimal sample with retries
  .github/workflows/
    ci-ai-summary.yml        # end-to-end sample workflow
```

---

## 1) Install and build

```bash
npm install
npm run build
```

## 2) the package contents before publishing
```bash
npm pack
```
## 3) Log in to npm
```bash
npm config get registry
npm config set //registry.npmjs.org/:_authToken=YOUR_TOKEN_HERE
npm login
npm whoami
```

## 4) Publish public scoped packages
```bash
npm version patch
npm publish --access public
```

## 2) Run locally (CLI)

### Using your real Allure output

```bash
node dist/index.js --mode cli --resultsDir sample/allure-results --output sample/allure-failures.jsonl
```

This writes `/path/to/allure-results/allure-failures.jsonl` (unless you pass an absolute output path).

### Run on the bundled sample

```bash
node dist/index.js --mode cli --resultsDir sample/allure-results --output ../../sample/allure-failures.jsonl
cat sample/allure-failures.jsonl
```

Expected behavior on the sample:
- One test has a failed attempt then a passed retry → **skipped** entirely
- One test is broken → included
- One test is failed → included

## 3) Run AI summary locally

The summarizer uses an **OpenAI-compatible** endpoint (works for OpenAI or Azure OpenAI style APIs).

Set env vars:

```bash
export MOODYS_COPILOT_CLIENT_ID="..."
export MOODYS_COPILOT_API_KEY="gpt-4.1-mini"   # example
```

Run:

```bash
node dist/ai/ai-summary.js --input sample/allure-failures.jsonl --out sample/ai-summary.md
cat sample/ai-summary.md
```

> If the input file has 0 failures, the summarizer writes a short "All tests passed" message.

## 4) Run MCP server locally

MCP server runs over **stdio**, intended to be spawned by an MCP client.

```bash
node dist/index.js --mode mcp
```

This will wait for JSON-RPC messages on stdin.

```bash
npx @modelcontextprotocol/inspector
```
---

## 5) GitHub Actions usage (Pattern 1)

See `.github/workflows/ci-ai-summary.yml`.

High level:
1) Run tests → produce `allure-results/`
2) Run CLI to produce `allure-failures.jsonl`
3) Run `ai-summary` to produce Markdown
4) Append Markdown to GitHub Job Summary using `GITHUB_STEP_SUMMARY`

---

## Notes on safety / governance
If you're running this in a corporate environment, ensure the LLM endpoint/model is approved for your use case.

---

## Troubleshooting
- If `allure-failures.jsonl` is empty, it usually means final attempts were `passed` or `skipped`.
- If retries are not detected, ensure your CI rerun does **not wipe** the `allure-results/` directory between attempts.