Metadata-Version: 2.4
Name: maeris
Version: 0.9.0b5
Summary: MCP server and CLI for API management, security scanning, and Playwright test generation — powered by Claude
Project-URL: Documentation, https://maeris.io/docs
Project-URL: Homepage, https://maeris.io
Author-email: Maeris <support@maeris.io>
License: MIT License
        
        Copyright (c) 2024 Maeris
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pydantic<3.0,>=2.5
Requires-Dist: pyjwt>=2.8
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0
Requires-Dist: starlette>=0.36
Requires-Dist: structlog>=24.1
Requires-Dist: uvicorn>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.2; extra == 'dev'
Description-Content-Type: text/markdown

<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>
