<p align="center">
  <h1 align="center">Maeris</h1>
  <p align="center">
    <strong>Test, scan, and manage your APIs — right from your terminal or AI editor.</strong>
  </p>
  <p align="center">
    <a href="https://pypi.org/project/maeris/"><img src="https://img.shields.io/pypi/v/maeris?color=blue&label=PyPI" alt="PyPI"></a>
    <a href="https://pypi.org/project/maeris/"><img src="https://img.shields.io/pypi/pyversions/maeris" alt="Python"></a>
    <a href="https://github.com/abhinavelight/maeris-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/abhinavelight/maeris-mcp" alt="License"></a>
  </p>
</p>

Maeris connects your codebase to the [Maeris Portal](https://light.maeris.io), giving you the tools to generate UI tests, extract API definitions, run security scans, and manage everything through a simple CLI or your AI assistant.

---

## Highlights

<table>
<tr>
<td width="50%">

### Generate UI Tests
Scans your frontend code and produces ready-to-run **Playwright** tests — grounded in your actual source, not guesswork.

</td>
<td width="50%">

### Extract APIs
Finds API endpoints across your codebase and catalogs them into organized **collections**.

</td>
</tr>
<tr>
<td width="50%">

### Security Scanning
Checks your code against **OWASP Top 10** vulnerabilities with AI-guided static analysis.

</td>
<td width="50%">

### API Management
Create, organize, and run APIs with **collections**, **environments**, and multi-step **flows**.

</td>
</tr>
<tr>
<td width="50%">

### Test Management
Run tests, **auto-fix** broken selectors, track coverage, and export reports.

</td>
<td width="50%">

### Portal Sync
Push everything to [Maeris Portal](https://light.maeris.io) so your **whole team** stays in the loop.

</td>
</tr>
</table>

---

## Installation

```bash
pip install maeris
```

> **Requirements:** Python 3.10+ and [Claude Code](https://claude.ai/code) for AI-powered features.

---

## Quick Start

```bash
# 1. Set up Maeris in your project
cd your-project
maeris app init

# 2. Restart your editor to pick up the MCP config

# 3. (Optional) Sign in for portal features
maeris auth login
```

**That's it.** Now you can use Maeris from the CLI or just ask your AI assistant:

<table>
<tr>
<th>From the CLI</th>
<th>From your AI assistant</th>
</tr>
<tr>
<td>

```bash
maeris scan security
maeris scan api
maeris test generate
maeris test run
```

</td>
<td>

> "Scan this repo for security issues"

> "Extract all API endpoints from my codebase"

> "Generate UI tests for the login flow"

</td>
</tr>
</table>

---

## CLI Reference

<details>
<summary><strong>Setup & Authentication</strong></summary>

| Command | What it does |
|---|---|
| `maeris app init` | Set up Maeris for this project |
| `maeris auth login` | Sign in to Maeris Portal |
| `maeris auth logout` | Sign out |
| `maeris auth status` | Check who you're logged in as |
| `maeris doctor` | Diagnose setup issues |

</details>

<details>
<summary><strong>Test Generation & Management</strong></summary>

| Command | What it does |
|---|---|
| `maeris test generate` | Generate Playwright tests from your source code |
| `maeris test run` | Run tests (filter with `--name`, `--folder`, `--smoke`, `--regression`) |
| `maeris test list` | List all test cases |
| `maeris test import <file>` | Import existing Playwright/Cypress/Selenium tests |
| `maeris test fix` | Auto-fix broken test selectors using AI |
| `maeris test recalibrate` | Regenerate tests after UI changes |
| `maeris test delete` | Delete test cases |

**Test Folders**

| Command | What it does |
|---|---|
| `maeris folder create --name "Login Tests"` | Create a folder to organize tests |
| `maeris folder list` | List all test folders |
| `maeris folder delete` | Delete a folder |

</details>

<details>
<summary><strong>Scanning</strong></summary>

| Command | What it does |
|---|---|
| `maeris scan security` | Run a security scan (OWASP Top 10) |
| `maeris scan api` | Extract API definitions from source code |
| `maeris scan push` | Push scan results to the portal |

> Use `--quick` for a fast scan or `--deep` for thorough analysis.

</details>

<details>
<summary><strong>API Management</strong></summary>

| Command | What it does |
|---|---|
| `maeris api list` | List all APIs |
| `maeris api get <name>` | View API details |
| `maeris api create --name N --method GET --url /path` | Create an API |
| `maeris api bulk` | Create multiple APIs at once |
| `maeris api update <name>` | Update an API |
| `maeris api delete <name>` | Delete an API |
| `maeris api move <name> --to-collection C` | Move to a collection |
| `maeris api clone <name>` | Duplicate an API |
| `maeris api import` | Import from Postman |
| `maeris api param add <api>` | Add headers or query params |

</details>

<details>
<summary><strong>Collections</strong></summary>

| Command | What it does |
|---|---|
| `maeris collection list` | List all collections |
| `maeris collection create --name "Auth APIs"` | Create a collection |
| `maeris collection get <name>` | View collection details |
| `maeris collection clone <name>` | Deep-copy a collection |
| `maeris collection rename <name>` | Rename a collection |
| `maeris collection delete <name>` | Delete a collection |

</details>

<details>
<summary><strong>Environments</strong></summary>

| Command | What it does |
|---|---|
| `maeris env list` | List all environments |
| `maeris env create --name "Staging"` | Create an environment |
| `maeris env rename <name>` | Rename an environment |
| `maeris env delete <name>` | Delete an environment |
| `maeris env data list <env>` | View environment variables |
| `maeris env data add <env>` | Add variables to an environment |
| `maeris env data update <env>` | Update a variable |

</details>

<details>
<summary><strong>API Flows</strong></summary>

| Command | What it does |
|---|---|
| `maeris flow list` | List all flows |
| `maeris flow create --name "Checkout"` | Create a flow |
| `maeris flow run <name>` | Execute a flow end-to-end |
| `maeris flow map set <flow>` | Define the step sequence |
| `maeris flow param add <flow>` | Add parameter mappings between steps |

</details>

<details>
<summary><strong>Assertions</strong></summary>

| Command | What it does |
|---|---|
| `maeris assertion list` | List all assertions |
| `maeris assertion create --api A --nature N --type T --value V` | Create an assertion |
| `maeris assertion update` | Update an assertion |
| `maeris assertion delete` | Delete an assertion |

</details>

<details>
<summary><strong>Coverage & Reports</strong></summary>

| Command | What it does |
|---|---|
| `maeris coverage ui` | View UI test coverage by feature area |
| `maeris coverage api` | View API test coverage |
| `maeris report tests` | Export a test report (HTML, JSON, or CSV) |
| `maeris report coverage` | Export a coverage report |
| `maeris report security` | Export a security scan report |

</details>

<details>
<summary><strong>Repair & Maintenance</strong></summary>

| Command | What it does |
|---|---|
| `maeris repair ui` | Fix broken CSS selectors in tests |
| `maeris repair api` | Reconcile stale API references |
| `maeris repair flow` | Repair flow parameter mappings |
| `maeris repair contract` | Validate API contracts |
| `maeris baseline generate` | Build a full baseline test suite |

</details>

<details>
<summary><strong>Push to Portal</strong></summary>

| Command | What it does |
|---|---|
| `maeris push tests --folder "Smoke"` | Push generated tests to Maeris Portal |

</details>

<details>
<summary><strong>Configuration & Other</strong></summary>

| Command | What it does |
|---|---|
| `maeris listen` | Listen for commands from the Maeris web UI |
| `maeris config set <key> <value>` | Set a CLI config value |
| `maeris config get <key>` | Read a config value |
| `maeris config completions` | Output shell completions (bash/zsh) |
| `maeris welcome` | Show the onboarding screen |

</details>

---

## Linking Additional Repos

If your tests need context from another repository (e.g., a shared component library):

```bash
maeris app link ../my-frontend-repo     # Add context source
maeris app links                         # See all linked repos
maeris app unlink ../my-frontend-repo   # Remove a link
```

---

## Troubleshooting

```bash
maeris doctor
```

Checks your Python version, CLI installation, editor config, credentials, and backend connectivity — and tells you exactly what to fix.

---

## How It Works

Maeris runs as an [MCP server](https://modelcontextprotocol.io/) alongside your AI editor. When you ask your assistant to scan code or generate tests, it calls Maeris tools under the hood.

```
┌──────────┐     ┌─────────────┐     ┌──────────────────┐     ┌────────────────┐
│ Your Code │────▶│ Claude Code │────▶│ Maeris MCP Server│────▶│ Maeris Portal  │
│          │◀────│             │◀────│  (runs locally)  │◀────│(cloud dashboard)│
└──────────┘     └─────────────┘     └──────────────────┘     └────────────────┘
```

All scanning and test generation happens **on your machine**. Only results you explicitly push leave your local environment.

---

<p align="center">
  <a href="https://light.maeris.io">Portal</a> &nbsp;&middot;&nbsp;
  <a href="https://discord.gg/maeris">Discord</a> &nbsp;&middot;&nbsp;
  <a href="mailto:support@maeris.io">Support</a>
</p>

<p align="center">
  MIT License
</p>
