Skip to main content

Connect shaft-mcp

shaft-mcp is the Model Context Protocol server for SHAFT browser, mobile, Capture, Doctor, and healer automation. Web GUI tools default to SHAFT WebDriver; choose the playwright_* tools when the project already uses SHAFT.GUI.Playwright or the user explicitly asks for Playwright code. It is published to Maven Central as the thin io.github.shafthq:shaft-mcp JAR, built in the SHAFT reactor, and depends on the canonical shaft-engine module. It does not add any dependency to ordinary shaft-engine consumers.

Applications​

Choose your MCP client and copy its command. The page detects your operating system after it loads and hides desktop applications that are unavailable there.

Execute these commands only after your security team approves runtime-script execution for your environment. Prefer manual configuration for production, high-security, or air-gapped contexts. Verify command output before you grant any approval prompts. A selected MCP client, network access, and compatible desktop platform are required. The command bootstraps Python and Java only when missing, then installs shaft-mcp from this repository's release script flow.

Codex CLI / IDEGlobal Codex configuration
curl -fsSL https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install-shaft-mcp.sh | sh -s -- --codex
Claude CodeUser-scope MCP server
curl -fsSL https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install-shaft-mcp.sh | sh -s -- --claude
Claude DesktopLocal desktop MCP server
curl -fsSL https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install-shaft-mcp.sh | sh -s -- --claude-desktop
GitHub Copilot CLIUser-level Copilot configuration
curl -fsSL https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install-shaft-mcp.sh | sh -s -- --copilot
GitHub Copilot in IntelliJ IDEAJetBrains MCP configuration
curl -fsSL https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/scripts/mcp/install-shaft-mcp.sh | sh -s -- --copilot-intellij

Need to inspect or edit the configuration yourself? Open the manual configuration guide.

The command downloads a repository-hosted bootstrap script. The bootstrapper uses Python 3.9+ when available, or installs a checksum-verified portable Python runtime in the per-user SHAFT cache when Python is missing. The shared Python installer prints the SHAFT MCP banner, shows the selected client, resolves io.github.shafthq:shaft-mcp:LATEST from Maven Central without requiring a local project, verifies checksums, shows progress for long downloads, downloads the thin JAR and its runtime dependencies to versioned per-user application data, writes a Java argfile, verifies it over stdio, and updates the selected user configuration without creating a second shaft-mcp entry. Run the same command later to install a newer release. If you run the script without a target, it prompts you to choose a supported client.

The resulting local stdio process lets SHAFT launch the browser on your desktop so you can see and interact with the automation session. Do not use the Docker image for interactive local browser work: its browser runs inside the container and is not displayed on your desktop.

Then ask your client:

Use SHAFT to open https://example.com, verify the page title, and summarize the generated test evidence.

The model provider remains owned by the client. shaft-mcp does not request, store, or proxy the client's model credentials.

Runtime workspace​

shaft-mcp chooses a writable runtime root for SHAFT engine artifacts. It no longer depends on the directory from which the MCP client launched the Java process.

The installer writes the Java argfile with both -Duser.dir=<runtime-root> and -Dshaft.mcp.workspaceRoot=<runtime-root> so GUI clients that launch from a system directory still use a writable per-user workspace. Manual configurations can set the same shaft.mcp.workspaceRoot JVM property, or set SHAFT_MCP_WORKSPACE_ROOT in the MCP server environment. If neither is set, shaft-mcp uses the process current directory only when that directory is writable and, on Windows, not under a protected system directory. Otherwise it falls back to per-user application data:

  • Windows: %LOCALAPPDATA%\ShaftHQ\shaft-mcp\work
  • macOS: ~/Library/Application Support/ShaftHQ/shaft-mcp/work
  • Linux: ${XDG_DATA_HOME:-~/.local/share}/shafthq/shaft-mcp/work

During MCP runs, relative SHAFT artifact paths are resolved under the runtime root. This includes generated Allure results and reports, downloaded properties, downloads, videos, services files, dynamic object repository files, test data, Extent reports, execution summaries, and performance reports. Explicit absolute path overrides remain absolute.

The element action tools stay explicit and locator-based. Use element_click and element_type with a locator strategy and locator value for default WebDriver sessions; use playwright_element_click, playwright_element_type, and the other playwright_* browser or element tools for SHAFT Playwright sessions. The older semantic click/type aliases are not exposed to MCP clients; for approved natural-language execution, use natural_act.

Guide search for agents​

Use shaft_guide_search before asking an agent to write or repair SHAFT code. The tool searches the live official SHAFT guide index and returns cited guide sections, short excerpts, nearby Java examples, and rules the agent must follow while generating code.

Good queries are direct and task-shaped:

  • page object model locators SHAFT.GUI.Locator
  • API request builder response validation
  • CLI terminal actions files
  • mobile Appium native locators
  • Allure failed test troubleshooting

The guide search covers public docs for GUI, API, CLI, mobile, reporting, configuration, locators, Page Object Model, Capture, Doctor, Heal, and troubleshooting. Agents should use the returned URLs as source citations, copy SHAFT method names only from the guide examples, prefer SHAFT.GUI.WebDriver and SHAFT.GUI.Locator for GUI code, use Selenium By objects instead of @FindBy/PageFactory, and say when the guide does not contain enough evidence for an answer.

Test automation scenario catalog​

Use test_automation_scenarios when the user asks an agent to create, refactor, or troubleshoot a SHAFT test suite and the agent needs a concrete flow to follow. The tool returns scenario ids, sample prompts, the MCP tools to call, the repository pattern to use, guardrails, and completion criteria.

Common catalog entries include:

ScenarioAgent actionFlow concludes when
api-openapi-contract-suiteRead the Swagger/OpenAPI contract, group operations by tag/resource, write reusable request builders and response validators under src/main/java, then write TestNG scenarios under src/test/java.Focused API tests compile, run, and validate against the configured OpenAPI contract.
web-pom-fluent-testInspect the page with browser DOM/screenshot tools, create or extend Page Object classes, and write fluent SHAFT actions and assertions.The headless GUI test passes and page object methods are reusable.
web-locator-refactorReplace brittle locators with SHAFT smart locators, ARIA locators, SHAFT.GUI.Locator, or stable Selenium By locators.Affected tests pass without @FindBy, PageFactory, or absolute XPath.
web-capture-to-pomRecord with Capture, generate WebDriver replay snippets, then move stable locators and actions into existing page objects.Replay-derived code is integrated instead of pasted as a generic generated class.
web-playwright-pom-fluent-testUse playwright_* browser and element tools to inspect the page, then write fluent SHAFT.GUI.Playwright page objects and tests.The Playwright test compiles and follows the existing project backend.
web-playwright-record-replayRecord Playwright MCP actions, generate replay snippets, and move stable actions into Playwright page methods.The replay code is reviewed, guarded, and inserted into Playwright classes.
mobile-native-appiumInspect contexts and accessibility trees, prefer accessibility ids/Appium locators, and create mobile page objects plus TestNG tests.The native mobile test compiles; any unavailable device/cloud run is reported.
mobile-record-replayRecord mobile actions through MCP, generate code blocks, and move them into mobile page methods.The replay code is reviewed, guarded, and inserted into the right classes.
failure-doctor-analysisAnalyze Allure results with Doctor and separate product defects, test defects, and infrastructure issues.The first actionable failure and next validation step are reported.
failure-healer-loopRerun a guarded failing Selenium or Playwright test, analyze fresh evidence, and propose review-only fixes.The failure is fixed by validation or reported as blocked/product behavior.
report-generate-and-summarizeGenerate the report and summarize SHAFT/Allure evidence.The report path and high-signal pass/fail summary are returned.
ci-local-validationLoad validation gotchas, run affected checks first, then escalate only when needed.The agent reports exact commands, results, and remaining risk.

Before finalizing generated Java, call test_code_guardrails_check. It fails code that contains Thread.sleep(...) or absolute XPath such as By.xpath("/html/body/..."). Prefer SHAFT waits/actions/assertions and the locator order from the catalog: smart/semantic locators, ARIA locators, SHAFT.GUI.Locator, stable By/AppiumBy, then non-absolute XPath only when nothing better exists.

If you see an AccessDeniedException under C:\Windows\system32, the MCP host launched from a protected Windows directory. Upgrade to a release with the app-data fallback, or set SHAFT_MCP_WORKSPACE_ROOT to a writable directory.

Build from source​

Run from the repository root:

mvn -pl shaft-mcp -am test
mvn -pl shaft-mcp -am install -DskipTests -Dgpg.skip
mvn -pl shaft-mcp dependency:copy-dependencies -DincludeScope=runtime \
  '-DoutputDirectory=${maven.multiModuleProjectDirectory}/shaft-mcp/target/dependency' \
  -DskipTests -Dgpg.skip
python3 scripts/ci/validate_shaft_mcp_transports.py

The packaged server supports:

  • stdio by default, with protocol messages only on stdout and logs on stderr;
  • Streamable HTTP with --spring.profiles.active=http, at /mcp;
  • managed recording through capture_start, capture_status, and capture_stop, with no AI provider required;
  • deterministic WebDriver TestNG generation through capture_generate, capture_generate_replay, and capture_code_blocks, with compile, optional replay, and review-only AI enrichment phases;
  • deterministic Playwright TestNG generation through playwright_capture_generate_replay and playwright_capture_code_blocks when the target repository uses SHAFT.GUI.Playwright;
  • explicit Playwright browser, element, screenshot, DOM, action recording, playback, and copy-paste replay tools through the playwright_* tool family;
  • deterministic diagnosis through doctor_analyze_failed_allure for WebDriver remediation and playwright_doctor_analyze_failed_allure for Playwright remediation, restricted to explicit input paths and allowed roots, with an optional separately identified provider advisory when Pilot AI is explicitly enabled;
  • guarded test healing through healer_run_failed_test for Selenium/WebDriver and playwright_healer_run_failed_test for SHAFT Playwright, which rerun tokenized Maven validation commands, analyze fresh Allure evidence through Doctor, and return review-only fixes plus an agent replay handoff;
  • explicit browser element actions through element_click and element_type, using locator strategy and locator value arguments;
  • official guide search through shaft_guide_search, so agents can retrieve cited SHAFT best practices, API/GUI/CLI examples, locators, Page Object Model guidance, and troubleshooting steps before writing code;
  • structured test automation playbooks through test_automation_scenarios, plus generated-code guardrail checks through test_code_guardrails_check;
  • mobile web emulation and native Android/iOS execution through mobile_initialize_web_emulation and mobile_initialize_native;
  • mobile inspection through mobile_take_screenshot, mobile_get_accessibility_tree, context switching, and action tools for tapping, typing, swiping, rotation, keyboard, backgrounding, app activation, recording, playback, and copy-pasteable Java action blocks;
  • wrapped Appium Inspector mobile recording through mobile_toolchain_status, mobile_inspector_record_prepare, mobile_inspector_record_start, mobile_inspector_record_control, and mobile_inspector_record_stop. The prepare step reports adb devices -l, cached Android AVDs, missing local dependencies, suggested capabilities, and any Android emulator creation proposal before the user confirms startup;
  • trust-gated natural-language browser, element, and touch execution through natural_act, using the active SHAFT driver and the same driver.act(...) planner rules;
  • legacy SSE endpoint properties as configuration aliases during migration.

The HTTP port defaults to 8081 and can be overridden with PORT or --server.port.

The same main class also provides local SHAFT Capture and Doctor CLIs. Use ; instead of : in MCP_CP on Windows:

MCP_CP="shaft-mcp/target/shaft-mcp-<version>.jar:shaft-mcp/target/dependency/*"
MCP_MAIN="com.shaft.mcp.ShaftMcpApplication"

java -cp "$MCP_CP" "$MCP_MAIN" capture start \
  --url https://example.test --browser chrome --output recordings/example.json
java -cp "$MCP_CP" "$MCP_MAIN" capture status
java -cp "$MCP_CP" "$MCP_MAIN" capture stop
java -cp "$MCP_CP" "$MCP_MAIN" capture generate \
  --session recordings/example.json --output-dir generated-tests
java -cp "$MCP_CP" "$MCP_MAIN" doctor analyze \
  --input allure-results --allowed-root "$PWD" \
  --output-dir target/shaft-doctor

See SHAFT Capture for checkpoint, runtime-directory, privacy, generation, replay, enrichment approval, browser-support, and recovery details.

See SHAFT Doctor for evidence categories, allowlisted path handling, deterministic rules, redaction, offline bundle analysis, optional provider advisories, and safe fallback behavior.

Healing failed Selenium or Playwright tests​

healer_run_failed_test is the Selenium/SHAFT counterpart to test-agent healer loops: it reruns the failing test, inspects the fresh SHAFT Allure evidence, asks Doctor for the latest diagnosis, and stops when the guarded run passes or when guardrails block more attempts.

Use playwright_healer_run_failed_test for tests built around SHAFT.GUI.Playwright. It uses the same guardrails and evidence handling, but returns Playwright-oriented remediation snippets and directs the agent to the playwright_* replay and inspection tools.

The tool accepts a repository root, a tokenized Maven command, an output directory, optional source-path allowlists, and explicit approvals for screenshots, page snapshots, network validation, and configured SHAFT provider advisories. Test-running commands are forced headless and run offline by default. Shell syntax, release/deploy goals, external Maven settings, and worktree-escape paths are rejected.

When the healer returns a failed diagnosis, the calling MCP agent may use its own LLM and the matching SHAFT MCP browser, DOM, screenshot, element, and replay tools to inspect the current UI. Use the existing WebDriver tool names for Selenium tests and the playwright_* names for Playwright tests. This agent-side reasoning does not require a SHAFT provider API key.

The healer never edits source or publishes a change by itself. Locator, wait, test-data, assertion, and product-bug recommendations remain review-only until the user confirms the fix. If Doctor classifies the failure as product behavior, the result is reported as a suspected product bug instead of a test patch.

See Mobile and Flutter testing for Appium setup, mobile web emulation, native device configuration, MCP screenshots, accessibility trees, and record/playback usage.

See Natural Language Actions for deterministic driver.act(...) patterns, trust thresholds, allowed-action filters, and optional planner fallback behavior.

See SHAFT Pilot for installation, provider configuration, Capture and Doctor examples, privacy defaults, and client-specific MCP setup. Maintainers should use the SHAFT Pilot release runbook for the deterministic release gate and standalone-repository archival order.

Authentication boundary​

shaft-mcp does not require or store OpenAI, Anthropic, Google, Microsoft, or Ollama credentials. The MCP client authenticates its own model/provider session. Configure only browser/Grid settings required by the SHAFT tools, such as REMOTE_DRIVER_ADDRESS.

Browser, filesystem, and GitHub mutations should remain approval-gated in the client. Start with a tool allowlist when the client supports one.

natural_act temporarily enables natural-language execution for the call and restores the previous current-thread settings afterward. MCP clients may pass a per-call minimumTrustPercentage, planner, aiFallbackEnabled, and allowedActions. Argument values are not written to SHAFT logs; only intent length, argument count, threshold, planner, and fallback state are logged.

What the installer configures​

The bootstrap script uses Python 3.9+ when available. If Python is missing, it installs a checksum-verified portable Python runtime under the per-user SHAFT cache. The shared Python installer then uses the local Java 25 when available. If Java 25 is missing, it installs a per-user cached Java 25 runtime during the same command. It downloads the released thin shaft-mcp JAR and runtime dependencies directly from Maven Central, verifies checksums, shows progress for large downloads, writes a Java argfile, probes the server over stdio, and writes the selected client configuration itself.

The script creates a local stdio server named shaft-mcp. It records the absolute Java 25 executable and the absolute versioned argfile path so GUI clients do not depend on their inherited PATH. The argfile also pins user.dir and shaft.mcp.workspaceRoot to the per-user SHAFT work directory so Allure results, downloads, reports, and other SHAFT artifacts are not created under a protected client launch directory.

claude configures Claude Code. claude-desktop configures Claude Desktop on Windows or macOS and requires restarting Claude Desktop. GitHub Copilot for IntelliJ IDEA uses the JetBrains Copilot mcp.json configuration and may need the IDE to reload after the file changes.

Configuration is per-user only. If the current project already defines a shaft-mcp server that would override the user entry, the installer stops without editing the project. Every user configuration mutation is backed up, verified, and rolled back on failure.

At the end of a successful install, the script prints the installed shaft-mcp version, the configured client, the restart or new-session action, and this user guide link.

The MCP client remains responsible for tool approvals and model authentication.

Codex also supports direct Streamable HTTP:

[mcp_servers.shaft-mcp]
url = "https://your-shaft-mcp.example/mcp"
default_tools_approval_mode = "prompt"

Remote clients​

Containers and Streamable HTTP are intended for remote, shared, or headless deployments where a visible desktop browser is not required.

Start the server locally for testing:

java -cp "$MCP_CP" "$MCP_MAIN" --spring.profiles.active=http

Use the HTTPS /mcp URL for ChatGPT developer mode/apps, the Claude API MCP connector, Copilot cloud agents, Codex, and other Streamable HTTP clients. ChatGPT and cloud-agent clients require a reachable HTTPS deployment; they cannot launch a JAR on the user's workstation.

Current client references:

Doctor invocations cover ChatGPT, Codex, Claude, Gemini, and GitHub Copilot calls to the same doctor_analyze_failed_allure tool. Client authentication remains outside SHAFT; Copilot is not treated as a direct generic API-key provider.

Distribution identity​

The distribution uses:

  • Maven Central: io.github.shafthq:shaft-mcp
  • MCP server name: shaft-mcp
  • Canonical OCI image: ghcr.io/shafthq/shaft-engine-mcp
  • MCP registry name: io.github.ShaftHQ/shaft-mcp
  • Java package and existing tool names

shaft-mcp/server.json is a release template. The publication workflow replaces @project.version@ from the root reactor version before registry validation and publication.