# ats-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an LLM drive
[ActionTestScript](https://actiontestscript.org) test sessions — web,
mobile, desktop, and API — through ats-core's REPL.

Use it with Claude Code, Claude Desktop, Cursor, or any MCP-capable client
to have the assistant **actually interact** with a system under test:
launch channels, click elements, capture screenshots, inspect the DOM or
the mobile view hierarchy, run ATS scripts — all as tool calls.

Two distributions are available, both wired to the **same set of tools**:

| | Install | Best for |
|---|---|---|
| **npm** | `npx -y ats-mcp` ([package](https://www.npmjs.com/package/ats-mcp)) | Node-friendly devs, the broader MCP community |
| **JAR** | Download `ats-mcp-X.Y.Z.jar` from [Releases](https://gitlab.com/actiontestscript/ats-mcp/-/releases) | Users who already have Java but no Node |

## How it works

```
MCP client (Claude Code / Desktop / …)
         │
         ▼
   ats-mcp launcher  (Node OR Java — see /node and /java in this repo)
         │
   spawns / loads
         │
         ▼
  AtsReplServer (ats-core)
         │
  ┌──────┼──────┬───────┐
  ▼      ▼      ▼       ▼
 web   mobile  desktop api
```

On first use, the launcher provisions everything ATS needs under
`~/.actiontestscript/`:

- **libs** — downloaded from
  `https://actiontestscript.org/releases/ats-libs/<version>.zip` if
  `~/.actiontestscript/libs/` is missing.
- **system driver** (for desktop-app automation) — latest version pulled
  from `https://actiontestscript.org/releases/ats-drivers/<os>/system/`,
  upgraded automatically when a newer one is published.
- **browser drivers** — fetched on-demand by ats-core itself on the
  first `start_channel` per browser/version.

No manual install step — `npx -y ats-mcp` or `java -jar ats-mcp.jar` is
enough to go from zero to web/desktop/api automation.

## Prerequisites

- **Java 17+** (always required — ats-core is JVM). Install from
  [Adoptium Temurin](https://adoptium.net/) or your package manager.
- **Node 18+** (only if you use the npm distribution). Install from
  [nodejs.org](https://nodejs.org/) or your package manager.

No Maven required — both distributions ship pre-built. Maven is only
needed to build the JAR from source (see `java/`).

## Configure your MCP client

### Claude Code

Add a `.mcp.json` at the project root:

```json
{
  "mcpServers": {
    "ats": {
      "command": "npx",
      "args": ["-y", "ats-mcp@latest"]
    }
  }
}
```

Or, with the JAR:

```json
{
  "mcpServers": {
    "ats": {
      "command": "java",
      "args": ["-jar", "/path/to/ats-mcp-0.4.0.jar"]
    }
  }
}
```

### Claude Desktop

Same shape, in `claude_desktop_config.json`.

## Environment variables

| Name                    | Purpose                                                          | Default                                |
|-------------------------|------------------------------------------------------------------|----------------------------------------|
| `ATS_VERSION`           | Version of `ats-automated-testing` to bootstrap.                 | `3.6.6`                                |
| `ATS_HOME`              | Where ATS libs and drivers live.                                  | `~/.actiontestscript`                  |
| `JAVA_BIN`              | Path to the `java` executable.                                    | `java` on PATH                         |

## Tools exposed

**30 tools**, grouped by purpose:

**Session / channels**
| Tool | What it does |
|---|---|
| `start_channel` | Open a web / mobile / desktop / api / SAP channel |
| `stop_channel` | Close a channel |
| `switch_channel` | Make a channel active |

**Navigation (web)**
| Tool | What it does |
|---|---|
| `goto_url` | Navigate to a URL |
| `navigate_back` | Browser history back |
| `navigate_forward` | Browser history forward |
| `refresh` | Reload the current page |

**Interaction**
| Tool | What it does |
|---|---|
| `click` | Mouse-click on an element |
| `hover` | Mouse-over an element |
| `send_keys` | Type text into an element |
| `press_key` | Press a special key (ENTER, TAB, arrows, F-keys…) |
| `scroll` | Scroll an element by a signed pixel offset |
| `drag` / `drop` | Two-step drag-and-drop on source → target |
| `select_option` | Select a `<select>` option by text/value/index |
| `file_upload` | Upload a local file to a file-input |
| `handle_dialog` | Accept/dismiss/default a JS alert/confirm/prompt |

**Inspection**
| Tool | What it does |
|---|---|
| `screenshot` | Capture a PNG of the current state |
| `capture_tree` | Dump the DOM / view hierarchy |
| `find_elements` | Enumerate elements matching a CSS selector (web) or SAP tag |
| `evaluate_js` | Run JavaScript in the page and return its value |
| `console_logs` | JS console messages captured on the active web channel |
| `network_list` | HTTP requests captured (with index for `network_detail`) |
| `network_detail` | Full request/response for one exchange |
| `network_cookies` | Cookies on the active web channel |

**Window / tabs**
| Tool | What it does |
|---|---|
| `window_resize` | Resize (and optionally move) the window |
| `window_switch` | Switch tabs by index / name / URL substring |
| `window_new_tab` | Open a new tab, optionally at a URL |
| `window_close` | Close the current tab/window |

**Escape hatch**
| Tool | What it does |
|---|---|
| `run_ats_block` | Execute a sequence of raw ATS action lines |

## Positioning vs Playwright MCP

ats-mcp covers the same interaction surface as `@playwright/mcp` for the
web, plus three things Playwright doesn't do:

- **Multi-platform** — web, mobile (Android/iOS physical, simulators,
  emulators, Genymotion Cloud), desktop apps (via the ATS system driver),
  REST/SOAP APIs, and SAP GUI.
- **Implicit wait built-in** — element lookups retry with backoff, so
  the LLM doesn't need to stitch `wait_for` calls around every action.
- **Raw escape hatch** — `run_ats_block` exposes the full ATS action
  vocabulary when a purpose-built tool isn't enough.

## Repo layout

```
ats-mcp/
├── node/      — TypeScript implementation (published to npm)
├── java/      — Maven implementation (released as a fat JAR)
├── README.md
└── .gitlab-ci.yml
```

Both implementations target the same protocol surface and share the same
tool definitions.

## License

Apache-2.0 — same as ats-core.