shaft-mcp

Start here

SHAFT is for Java teams who are about to rebuild drivers, waits, assertions, configuration, test data, and Allure plumbing again. Generate a project from the user guide, then run mvn test. The 100-second overview and the feature video release are the short tour; the badge above is the current version, and releases hold history.

Humans: orient here, then CONTRIBUTING.md. Report vulnerabilities through SECURITY.md.

Agents: jump to For agents. This README is orientation, not agent policy.

Add it to a project you already have

Use coordinate io.github.shafthq:shaft-engine. Set the version from the Maven Central badge. The generated project is still the supported first run. Kotlin uses the same coordinate.

<dependency>
    <groupId>io.github.shafthq</groupId>
    <artifactId>shaft-engine</artifactId>
    <version>${shaft.version}</version>
</dependency>

Each reactor module and shaft-intellij has a short README with a purpose line and a use-or-skip note.

Why teams use it

SHAFT removes the repeated plumbing around drivers, waits, assertions, configuration, test data, screenshots, logs, and Allure evidence. The modular reactor keeps the core lean.

• Strong defaults, explicit control. Configuration keeps environments and CI reproducible.
• Modular by design. Start with shaft-engine, then add visual, video, cloud, native, or agentic modules.
• Evidence is part of execution. Logs, screenshots, attachments, and reports share one lifecycle.
• Open and inspectable. MIT licensed, guarded by the pull-request gate, security policy, and release history.

One orchestration layer, every execution surface

Test intent and configuration enter SHAFT's orchestration layer, fan out across the required execution surfaces, and return through one unified evidence flow.

flowchart LR
    accTitle: SHAFT execution and evidence workflow
    accDescr: Test intent and configuration enter SHAFT orchestration, run across Web, Mobile, API, and Native execution surfaces, and produce unified evidence.
    I[Test intent] --> S[SHAFT orchestration]
    C[Configuration] --> S
    S --> W[Web]
    S --> M[Mobile]
    S --> A[API]
    S --> N[Native, CLI, and Database]
    W --> E[Unified evidence]
    M --> E
    A --> E
    N --> E

Engineering need	What SHAFT provides
Stable UI automation	Managed Selenium and Appium drivers, synchronized actions, locator builders, screenshots, and accessibility evidence.
End-to-end coverage	REST, GraphQL, Database, CLI, and native desktop actions in the same test flow.
Trustworthy verdicts	Hard and soft assertions, structured logs, attachments, failure context, and Allure reports.
Scalable execution	Configuration-first local, Grid, BrowserStack, LambdaTest, TestNG, JUnit, and Cucumber runs.
Maintainable architecture	A focused engine, BOM-aligned optional modules, public extension points, and reusable test assets.
Assisted workflows	Capture, Doctor, deterministic Heal, MCP/CLI tools, provider adapters, and an IntelliJ IDEA plugin.

Where to go next

You want to	Open
Learn the product	User guide
Work inside IntelliJ	shaft-intellij
Call a tool from an agent	MCP tool names
Call a tool from the shell	CLI commands
Follow the working policy	AGENTS.md

Maintainer notes for local model runs

• FreeToken / llama.cpp on ROG: resolve with chaos-engine/skills/local-agency (dispatch.py --prefer freetoken or OpenAI-compat on :8080).
• Colibri is optional only when http://127.0.0.1:8000 is READY; not the default on 6GB VRAM laptops.
• Proof runner note (#6045): preferred dense coder is Qwen2.5-Coder-7B Q4_K_M via llama-server when FreeToken KV is ~8k.

Questions

What is SHAFT? A Java framework for web, mobile, API, CLI, database, and desktop end-to-end testing, with one evidence trail.

How do I get a passing run today? Generate a project from the user guide, then run mvn test. Runners are TestNG, JUnit, and Cucumber, local or through Grid, BrowserStack, or LambdaTest.

Where does an agent start? AGENTS.md. Not this file. License: MIT (LICENSE).

For agents

This page is a map. It is not the working policy.

• Start at AGENTS.md. That file names the only policy owner.
• SHAFT ships 30 first-party skills. Start with $shaft-developer; it routes the job to one specialist.
• Exact MCP names and CLI syntax are generated in shaft-mcp-tools.md and shaft-cli-commands.md.

Join the project

Open an issue, read CONTRIBUTING.md and the Code of Conduct, and report vulnerabilities privately through SECURITY.md. Star the repository if SHAFT helps your team.

BrowserStack, LambdaTest, Applitools, and JetBrains have provided tooling or open-source program support. This is support for the project, not a claim of financial sponsorship, customer status, or endorsement.

SHAFT is free and MIT licensed. Support maintenance through GitHub Sponsors.