@shiplightai/mcp 0.1.4 → 0.1.6

package/README.md

@@ -1,400 +1,127 @@
-# Shiplight MCP Server
+# @shiplightai/mcp
 
-**AI-powered web testing through the Model Context Protocol.**
+MCP server for browser UI exploration. Provides tools to launch browser sessions, navigate pages, inspect the DOM, perform actions, and collect locators — designed for coding agents that explore UI then write Playwright tests with [`@shiplightai/sdk`](https://www.npmjs.com/package/@shiplightai/sdk).
 
-Shiplight lets AI coding agents — Claude Code, Cursor, Windsurf, and any MCP-compatible tool — browse, interact with, and test web applications. Write tests in natural language, run them in the cloud, and get detailed results — all from your IDE.
-
-## Why Shiplight
-
-Other browser MCP servers (like [Playwright MCP](https://github.com/microsoft/playwright-mcp)) give your coding agent basic browser control. Shiplight goes further:
-
-| Capability | Playwright MCP | Shiplight |
-|------------|---------------|-----------|
-| Browser automation (click, type, scroll) | Yes | Yes |
-| AI-powered assertions (`verify`) | No | Yes * |
-| AI data extraction (`ai_extract`) | No | Yes * |
-| Natural language test flows (YAML DSL) | No | Yes |
-| Conditional logic (`IF`/`ELSE`) | No | Yes * |
-| Loops (`WHILE`) | No | Yes * |
-| Cloud test execution & results | No | Yes |
-| Test case management (CRUD, folders) | No | Yes |
-| Enrichment workflow (DRAFT to ACTION) | No | Yes |
-
-
-\* Uses the web agent (secondary LLM)
-
-Shiplight also uses **set-of-mark** technology for better identifying interactive elements and handles **cross-frame elements transparently** — no manual iframe switching needed.
-
-Shiplight is not just a browser driver — it's a complete test automation platform accessible through MCP.
-
-## Quick Start
-
-### Install
+## Installation
 
 ```bash
 npm install -g @shiplightai/mcp
 ```
 
-### Claude Code
+## Usage
 
-```bash
-claude mcp add shiplight -- shiplight-mcp \
-  -e GOOGLE_API_KEY=your-google-api-key \
-  -e WEB_AGENT_MODEL=gemini-2.5-pro \
-  -e PWDEBUG=console
-```
-
-### Claude Desktop
+### Claude Code
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add to your Claude Code MCP config (`~/.claude/settings.json`):
 
 ```json
 {
   "mcpServers": {
     "shiplight": {
-      "command": "shiplight-mcp",
-      "env": {
-        "GOOGLE_API_KEY": "your-google-api-key",
-        "WEB_AGENT_MODEL": "gemini-2.5-pro",
-        "PWDEBUG": "console"
-      }
+      "command": "shiplight-mcp"
     }
   }
 }
 ```
 
-### Cursor
+### Claude Desktop
 
-Add to `.cursor/mcp.json` in your project:
+Add to your Claude Desktop config:
 
 ```json
 {
   "mcpServers": {
     "shiplight": {
-      "command": "shiplight-mcp",
-      "env": {
-        "GOOGLE_API_KEY": "your-google-api-key",
-        "WEB_AGENT_MODEL": "gemini-2.5-pro",
-        "PWDEBUG": "console"
-      }
+      "command": "npx",
+      "args": ["-y", "@shiplightai/mcp"]
     }
   }
 }
 ```
 
-The MCP server runs a **web agent** — a secondary LLM that looks at the browser page and decides how to act. This agent powers:
-
-- **AI-powered actions**: `verify`, `ai_extract`, `ai_wait_until`
-- **Natural language test steps**: DRAFT statements and VERIFY assertions in test flows
-- **Conditional evaluation**: IF/ELSE and WHILE conditions written in natural language
-
-Browser actions like `click`, `input_text`, `scroll` etc. do **not** require the web agent — they execute deterministically.
-
-You can use either a Google or Anthropic API key. Set `WEB_AGENT_MODEL` to match your provider:
+### Cursor / Windsurf
 
-| Provider | API Key | Supported Models |
-|----------|---------|-----------------|
-| Google | `GOOGLE_API_KEY` | `gemini-2.5-pro`, `gemini-3-pro-preview` |
-| Anthropic | `ANTHROPIC_API_KEY` | `claude-haiku-4-5`, `claude-sonnet-4-5`, `claude-opus-4-5` |
-
-To unlock cloud test management, add your Shiplight API token:
+Add to your MCP config (`.cursor/mcp.json` or equivalent):
 
 ```json
 {
-  "env": {
-    "GOOGLE_API_KEY": "your-google-api-key",
-    "WEB_AGENT_MODEL": "gemini-2.5-pro",
-    "PWDEBUG": "console",
-    "API_TOKEN": "your-shiplight-api-token-here"
+  "mcpServers": {
+    "shiplight": {
+      "command": "npx",
+      "args": ["-y", "@shiplightai/mcp"]
+    }
   }
 }
 ```
 
-## Free: Browser Automation & UI Verification
-
-No Shiplight account needed. Launch a browser, interact with any web app, and verify UI state — all driven by your AI coding agent.
-
-**Your coding agent can verify UI features by:**
-
-- Opening a browser and navigating to your app
-- Inspecting page state via screenshots and DOM structure
-- Interacting with elements: click, type, select, scroll, upload files
-- Asserting UI state with natural language (e.g., "the login form should be visible")
-- Capturing console errors and network requests
+## Tools
 
-**Example — prompt your coding agent:**
-
-```
-Add a "Forgot Password?" link below the login form. After implementing,
-Use Shiplight to verify your implementation in the browser.
-```
-
-### Free Tools
+### Session Management (5)
 
 | Tool | Description |
 |------|-------------|
-| `new_session` | Create a browser session with optional device emulation and auto-login |
+| `new_session` | Launch a browser session with optional device emulation |
+| `save_storage_state` | Save cookies/localStorage for session reuse |
 | `close_session` | Close a browser session |
 | `close_all` | Close all browser sessions |
-| `get_session_state` | Get current URL and session info |
-| `save_storage_state` | Save cookies/localStorage for fast session restore |
-| `navigate` | Navigate to a URL |
-| `get_page_info` | Get current page URL and title |
-| `inspect_page` | Screenshot + DOM with interactive element indices |
-| `act` | Perform browser actions (click, type, scroll, verify, etc.) |
-| `get_locator` | Extract Playwright locator/xpath for an element |
-| `update_variables` | Set session variables for use in actions |
-| `clear_execution_history` | Reset session action history |
-| `get_browser_console_logs` | Get browser console output with filtering |
-| `get_browser_network_logs` | Get network requests with status filtering |
-| `clear_logs` | Clear console and network logs |
-| `get_artifact` | Retrieve a saved screenshot or DOM snapshot |
-
-### Browser Actions
-
-The `act` tool supports the following actions for interacting with the page:
-
-| Action | Description |
-|--------|-------------|
-| `click` | Click an element |
-| `double_click` | Double-click an element |
-| `right_click` | Right-click an element |
-| `hover` | Hover over an element |
-| `input_text` | Type text into an input field |
-| `clear_input` | Clear an input field |
-| `press` | Press a key or key combination (e.g., `Enter`, `Control+A`) |
-| `send_keys_on_element` | Send keys to a specific element |
-| `select_dropdown_option` | Select from a dropdown by value or label |
-| `get_dropdown_options` | List all options in a dropdown |
-| `set_date_for_native_date_picker` | Set date on a native date picker input |
-| `scroll` | Scroll up or down by number of pages |
-| `scroll_to_text` | Scroll until specific text is visible |
-| `scroll_on_element` | Scroll within a specific scrollable element |
-| `go_to_url` | Navigate to a URL |
-| `go_back` | Go back in browser history |
-| `reload_page` | Reload the current page |
-| `switch_tab` | Switch to a different browser tab |
-| `close_tab` | Close a browser tab |
-| `upload_file` | Upload a file via file input |
-
-### Utility Actions
-
-| Action | Description |
-|--------|-------------|
-| `wait` | Wait for a specified duration |
-| `wait_for_page_ready` | Wait until the page finishes loading |
-| `wait_for_download_complete` | Wait for a file download to complete |
-| `save_variable` | Save a value to a session variable |
-| `generate_2fa_code` | Generate a TOTP 2FA code from a secret key |
-
-### AI-Powered Actions *
-
-These actions use the AI model specified by `WEB_AGENT_MODEL` to reason about the page:
-
-| Action | Description |
-|--------|-------------|
-| `verify` * | Assert page state with a natural language statement |
-| `ai_extract` * | Extract data from the page into a variable |
-| `ai_wait_until` * | Wait until an AI-evaluated condition is true |
-
-## Writing Tests in Natural Language
-
-Shiplight tests are written in YAML using natural language. Start with plain English, then optionally enrich with locators for speed.
-
-**No lock-in**: Test flows are exported as pure Playwright + [Shiplight Agent SDK](https://github.com/ShiplightAI/sdk-examples) code for execution. The YAML DSL is an authoring format — what actually runs is standard Playwright with an AI agent layer on top. You can eject at any time.
-
-### Basic Test (all natural language)
-
-```yaml
-goal: Verify user can create a new project
-url: https://app.example.com/projects
-statements:
-  - Click the "New Project" button
-  - Enter "My Test Project" in the project name field
-  - Select "Public" from the visibility dropdown
-  - Click "Create"
-  - "VERIFY: Project page shows title 'My Test Project'"
-teardown:
-  - Delete the created project
-```
-
-Every line is a plain English instruction. The AI resolves each one at runtime by looking at the page and performing the right action.
-
-### Enriched Test (with locator)
-
-After exploring the UI with the free browser tools, you can add locators for deterministic, fast replay:
-
-```yaml
-goal: Verify user can create a new project
-url: https://app.example.com/projects
-statements:
-  - STEP: Create project
-    statements:
-      - description: Click the New Project button
-        action_entity:
-          action_data:
-            action_name: click
-          locator: "getByRole('button', { name: 'New Project' })"
-      - description: Enter project name
-        action_entity:
-          action_data:
-            action_name: input_text
-            kwargs:
-              text: "My Test Project"
-          locator: "getByRole('textbox', { name: 'Project name' })"
-      - description: Click Create
-        action_entity:
-          action_data:
-            action_name: click
-          locator: "getByRole('button', { name: 'Create' })"
-  - "VERIFY: Project page shows title 'My Test Project'"
-teardown:
-  - Delete the created project
-```
-
-**Natural language statements** (~10-15s each): AI reads the page and figures out what to do.
-**Action statements with locator** (~1s each): Replay deterministically without AI.
-**VERIFY statements**: Always use AI — just provide a clear assertion in plain English.
-
-**Locators are a cache, not a hard dependency.** When the UI changes and a locator becomes stale, Shiplight's agentic layer [auto-heals](https://docs.shiplight.ai/sdk/self-healing.html) by falling back to the natural language description. When running on the Shiplight cloud, the platform automatically updates the cached locator after a successful self-heal — so future runs replay at full speed without manual maintenance.
-
-### Statement Types
-
-| Type | Syntax | Description |
-|------|--------|-------------|
-| Natural language * | `- Click the login button` | AI resolves at runtime |
-| Action with locator | `- description: ...` + `action_entity: ...` | Deterministic replay |
-| Verify * | `- "VERIFY: page shows welcome message"` | AI-powered assertion |
-| Step group | `- STEP: Login` + `statements: [...]` | Group related actions |
-| Conditional * | `- IF: cookie banner is visible` + `THEN: [...]` | Conditional execution |
-| Loop * | `- WHILE: more items to load` + `DO: [...]` | Repeat until condition |
-
-### Conditional Logic & Loops
-
-Shiplight tests support branching and looping — handle real-world UI variability without separate test cases.
-
-**IF / ELSE** — handle optional UI elements:
-
-```yaml
-statements:
-  - IF: cookie consent dialog is visible
-    THEN:
-      - Click "Accept All"
-  - IF: user is logged in
-    THEN:
-      - Click the logout button
-    ELSE:
-      - Click the login button
-      - Enter credentials and submit
-```
-
-**WHILE** — repeat until a condition is met:
-
-```yaml
-statements:
-  - WHILE: "Load More" button is visible
-    DO:
-      - Click the "Load More" button
-      - Wait for new items to appear
-  - "VERIFY: all items are loaded"
-```
+| `get_session_state` | Get current URL and session type |
 
-Conditions are evaluated by AI at runtime using the current page state. You can also use JavaScript conditions with the `js:` prefix:
+### Browser Interaction (7)
 
-```yaml
-  - IF: "js: document.querySelectorAll('.item').length < 10"
-    THEN:
-      - Click "Load More"
-```
+| Tool | Description |
+|------|-------------|
+| `navigate` | Navigate to a URL |
+| `get_page_info` | Get page URL and title (lightweight) |
+| `inspect_page` | Screenshot + DOM with element indices |
+| `act` | Perform browser actions using element indices |
+| `get_locator` | Extract Playwright locator for an element |
+| `update_variables` | Set session variables for browser tasks |
+| `clear_execution_history` | Clear action history for a session |
 
-### The Enrichment Workflow
+### Debug (4)
 
-1. **Draft** — Write tests in plain English
-2. **Explore** — Use `inspect_page` and `act` to walk through the UI
-3. **Collect** — Use `get_locator` to capture element locators
-4. **Enrich** — Replace natural language with action_entity + locator
-5. **Result** — Tests run 10x faster with deterministic replay
+| Tool | Description |
+|------|-------------|
+| `get_browser_console_logs` | Get console logs (errors, warnings) |
+| `get_browser_network_logs` | Get network request logs |
+| `clear_logs` | Clear console and network logs |
+| `get_artifact` | Retrieve screenshots or DOM snapshots |
 
-You can mix natural language and enriched statements in the same test. Start with all natural language, then selectively enrich the most-used flows.
+## Resources
 
-## Cloud: Test Case Management & Execution
+The server exposes two resources for coding agents:
 
-*Requires a Shiplight API token.*
+- **`shiplight://schemas/action-entity`** — Parameter docs for all browser actions
+- **`shiplight://docs/agent-sdk`** — API documentation for `@shiplightai/sdk`, including a workflow guide for turning UI exploration into test code
 
-Store test cases in the cloud, trigger runs, and analyze results with full runner logs, screenshots, and trace files.
+## Workflow
 
-**What you can do:**
+1. **Explore** — Use `inspect_page` + `act` to navigate the app
+2. **Collect locators** — Use `get_locator` on elements you want to test
+3. **Write tests** — Use the locators in Playwright tests, with `@shiplightai/sdk` for AI-powered assertions and self-healing
 
-- Create and update test cases from YAML flows
-- Trigger cloud test runs across environments
-- Get detailed results: step-by-step status, screenshots, runner logs
-- Manage test infrastructure: environments, test accounts, folders
+```typescript
+import { test, expect } from '@playwright/test';
+import { createAgent, configureSdk } from '@shiplightai/sdk';
 
-**Example conversation:**
+configureSdk({ env: { GOOGLE_API_KEY: process.env.GOOGLE_API_KEY! } });
 
-```
-You: Create a test case from my login-test.yaml and run it on staging
+test('checkout flow', async ({ page }) => {
+  const agent = createAgent({ model: 'gemini-2.5-pro' });
 
-Claude: [reads YAML, creates test case, triggers run, polls for results]
-Test case #502 created. Cloud run completed in 1m 23s — all 8 steps passed.
+  await page.goto('https://myshop.example.com');
+  await page.getByRole('button', { name: 'Add to Cart' }).click();
+  await agent.assert(page, 'Item was added to cart');
+  await agent.run(page, 'Complete checkout with test data');
+});
 ```
 
-### Cloud Tools
+## Environment Variables
 
-| Tool | Description |
-|------|-------------|
-| `create_test_case` | Create a test case from a YAML flow or JSON object |
-| `update_test_case` | Update an existing test case flow |
-| `get_test_case` | Get test case details (supports YAML output) |
-| `run_test_case` | Trigger a cloud test run |
-| `list_test_runs` | List test runs with filtering |
-| `get_test_run_details` | Get run status and test case results |
-| `get_test_case_result` | Get detailed result with runner logs (stdout/stderr) |
-| `get_test_case_result_steps` | Get step-by-step execution details |
-| `get_step_artifacts` | Download screenshots and artifacts for a step |
-| `list_environments` | List testing environments |
-| `list_test_accounts` | List test accounts for an environment |
-| `get_test_account` | Get test account details |
-| `create_test_account` | Create a test account with login config |
-| `list_folders` | List test case folders |
-| `create_folder` | Create a folder for organizing test cases |
-| `get_folder` | Get folder details with full path |
-
-## Workflow Examples
-
-Shiplight MCP fits naturally into AI-driven development. Your coding agent can verify UI changes in a live browser as you code, and automatically create enriched test cases from the session — no context switching needed. See the [workflow guide](https://docs.shiplight.ai/mcp/workflows) for detailed examples, including how to set up a Claude Code custom agent for fully autonomous test creation.
-
-## Coming Soon
-
-- **Coordinate-based actions** — `click_by_coordinates`, `drag_drop` for pixel-precise interactions (canvas, maps, visual editors)
-
-## Configuration
-
-| Variable | Required | Description | Default |
-|----------|----------|-------------|---------|
-| `GOOGLE_API_KEY` | One of these | Google AI API key | — |
-| `ANTHROPIC_API_KEY` | required | Anthropic API key | — |
-| `WEB_AGENT_MODEL` | Yes | AI model for browser automation | — |
-| `PWDEBUG` | No | Set to `console` to enable Playwright debug logging | — |
-| `API_TOKEN` | For cloud features | Shiplight API token | — |
-| `API_BASE_URL` | No | Shiplight API URL | `https://api.shiplight.ai` |
-
-## Resources & Prompts
-
-The server exposes MCP resources with schema documentation:
-
-| Resource | Description |
-|----------|-------------|
-| `shiplight://schemas/testflow-v1.2.0` | TestFlow YAML/JSON format, statement types, examples |
-| `shiplight://schemas/action-entity` | Browser action parameters for the `act` tool |
-
-## Getting an API Token
-
-To unlock cloud test management:
-
-1. Visit [shiplight.ai](https://shiplight.ai) to create an account
-2. Generate an API token from your account settings
-3. Set `API_TOKEN` in your MCP server configuration
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WEB_AGENT_MODEL` | `gemini-2.5-pro` | AI model for browser agent |
+| `TERMINATION_TIMEOUT` | (none) | Session auto-close timeout in ms |
 
 ## License
 

package/dist/index.d.ts

@@ -1,96 +1,2 @@
-import { AxiosError, AxiosRequestConfig, AxiosResponse } from 'axios';
 
-/**
- * MCP Server Logger
- *
- * For STDIO-based MCP servers, we must NEVER write to stdout.
- * All logging output goes to stderr to avoid corrupting JSON-RPC messages.
- */
-declare class MCPLogger {
-    private static _instance;
-    private _logLevel;
-    private constructor();
-    static getInstance(): MCPLogger;
-    setLevel(level: number): void;
-    /**
-     * Log debug messages (only shown when LOG_LEVEL=DEBUG)
-     */
-    debug(...args: unknown[]): void;
-    /**
-     * Log informational messages
-     */
-    info(...args: unknown[]): void;
-    /**
-     * Log warning messages
-     */
-    warn(...args: unknown[]): void;
-    /**
-     * Log error messages (always shown)
-     */
-    error(...args: unknown[]): void;
-    /**
-     * Alias for info (for compatibility)
-     */
-    log(...args: unknown[]): void;
-}
-declare const logger: MCPLogger;
-
-declare const LogLevel: {
-    ERROR: number;
-    WARN: number;
-    INFO: number;
-    DEBUG: number;
-};
-
-/**
- * Axios Retry Utility
- *
- * Provides retry logic for axios requests with exponential backoff
- */
-
-interface RetryConfig {
-    maxRetries?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-    backoffMultiplier?: number;
-    retryableStatuses?: number[];
-    onRetry?: (attempt: number, error: AxiosError) => void;
-}
-/**
- * Retry an axios request with exponential backoff
- */
-declare function retryAxios<T = unknown>(requestFn: () => Promise<AxiosResponse<T>>, config?: RetryConfig): Promise<AxiosResponse<T>>;
-/**
- * Create a retry wrapper for axios instance
- */
-declare function createRetryAxios(retryConfig?: RetryConfig): {
-    get: <T = unknown>(url: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
-    post: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
-    put: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
-    delete: <T = unknown>(url: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
-    patch: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
-};
-
-/**
- * Shiplight MCP Server
- *
- * MCP server implementation for Shiplight AI test automation platform.
- * Uses shared tools from mcp-tools with default backends.
- */
-declare class ShiplightMCPServer {
-    private server;
-    private registry;
-    private sessionBackend;
-    private apiClient;
-    private sessionTools;
-    private browserTools;
-    private debugTools;
-    private testCaseTools;
-    private testResultTools;
-    private dataTools;
-    constructor();
-    private setupHandlers;
-    run(): Promise<void>;
-}
-
-export { LogLevel, type RetryConfig, ShiplightMCPServer, createRetryAxios, logger, retryAxios };
+export {  }