@qualitas-id/mcp 1.0.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@qualitas-id/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Qualitas - AI-powered test automation platform",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "qualitas-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "docker:build": "docker build -t qualitas-mcp .",
+    "docker:run": "docker run -it --rm -e QUALITAS_API_KEY=${QUALITAS_API_KEY} qualitas-mcp",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "qualitas",
+    "test-automation",
+    "playwright",
+    "flow-builder",
+    "ai-agent",
+    "e2e-testing"
+  ],
+  "author": "Qualitas <support@qualitas.id>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/firdyfirdy/qualitas-mcp-server.git"
+  },
+  "homepage": "https://qualitas.id",
+  "bugs": {
+    "url": "https://github.com/firdyfirdy/qualitas-mcp-server/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "axios": "^1.7.9",
+    "tesseract.js": "^7.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@qualitas-id/shared-types": "^1.2.0",
+    "@types/node": "^22.19.19",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^1.6.0"
+  }
+}

package/skills/qualitas.md

@@ -0,0 +1,253 @@
+---
+name: qualitas
+description: Guide for Qualitas MCP server - test automation with flow builder, fragments, validation, OCR, and executeScript tools
+license: MIT
+metadata:
+  audience: developers
+  workflow: test-automation
+---
+
+# Qualitas MCP - Skills & Best Practices
+
+Use this guide when working with the Qualitas MCP server for test automation.
+
+## MCP Tools Reference (20 tools)
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects with search/filter/sort |
+| `get_project` | Get project details with stats |
+| `create_project` | Create a new project |
+| `update_project` | Update project settings |
+
+### Flows
+| Tool | Description |
+|------|-------------|
+| `list_flows` | List flows in a project |
+| `get_flow` | Get flow details (nodes, edges, variables) |
+| `create_flow` | Create a flow with explicit nodes/edges |
+| `update_flow` | Update flow nodes/edges/variables |
+| `delete_flow` | Delete a flow permanently |
+| `publish_flow` | Publish flow/fragment (draft → active) |
+| `generate_flow_from_scenario` | Generate a flow from natural language |
+
+### Runs
+| Tool | Description |
+|------|-------------|
+| `run_flow` | Trigger flow execution |
+| `get_run_status` | Get run status and step details |
+| `list_runs` | List run history for a flow |
+
+### Variables
+| Tool | Description |
+|------|-------------|
+| `list_variables` | List project environment variables |
+| `create_variable` | Create environment variable |
+| `update_variable` | Update environment variable |
+| `delete_variable` | Delete environment variable |
+
+### Utility
+| Tool | Description |
+|------|-------------|
+| `extract_screenshot_text` | OCR from image URL, extract text and error messages |
+| `get_run_screenshot` | Get screenshot URLs for failed steps in a run |
+
+## Fragment Rules
+
+### CRITICAL: No Start Node in Fragments
+Fragments MUST NOT have a `start` node. When expanded, fragment nodes are inlined into the calling flow. A start node creates duplicate start nodes → 0 steps executed.
+
+**Wrong:**
+```json
+{
+  "nodes": [
+    {"id": "start", "type": "start", ...},
+    {"id": "nav_login", "type": "navigate", ...}
+  ]
+}
+```
+
+**Correct:**
+```json
+{
+  "nodes": [
+    {"id": "nav_login", "type": "navigate", ...},
+    {"id": "fill_email", "type": "fill", ...}
+  ]
+}
+```
+
+### When to Create a Fragment
+Any flow that is repetitive across multiple flows:
+- Login steps (customer or admin)
+- Common setup steps (navigate + wait + assert)
+- Reusable verification patterns
+- Multi-step form submissions
+
+## Variable Usage
+
+### Use BASE_URL for Repeated URLs
+```json
+// Create variable
+{ "name": "BASE_URL", "values": { "dev": "https://dev.example.com", "staging": "...", "prod": "..." } }
+
+// Reference in flows
+{"url": "{{project.BASE_URL}}/auth/login"}
+{"url": "{{project.BASE_URL}}/app/dashboard"}
+```
+
+## Node Type Selection
+
+### File Upload: 4 Modes
+The `upload` node supports 4 file source modes:
+
+```json
+// 1. Local file (uploaded to B2 storage at design time)
+{"type": "upload", "data": {"selector": "input[type=file]", "filePath": "https://b2.example.com/file.pdf"}}
+
+// 2. URL (downloaded at runtime)
+{"type": "upload", "data": {"selector": "input[type=file]", "filePath": "https://example.com/file.pdf"}}
+
+// 3. Base64 (decoded at runtime, max 10MB)
+{"type": "upload", "data": {"selector": "input[type=file]", "filePath": "data:application/pdf;base64,JVBERi0x..."}}
+
+// 4. Variable reference
+{"type": "upload", "data": {"selector": "input[type=file]", "filePath": "{{project.TEST_FILE}}"}}
+```
+
+**Detection logic:** Runner auto-detects source from `filePath` value:
+- `data:` prefix → base64 decode to temp file
+- `http://` or `https://` → download to temp file
+- Otherwise → local file path
+
+### Execute Script: Run Custom JavaScript
+The `executeScript` node runs custom JavaScript in the browser context.
+
+```json
+{"type": "executeScript", "data": {"script": "return document.title", "description": "Get page title"}}
+```
+
+**Use cases:**
+- Extract dynamic values from page
+- Check computed styles
+- Evaluate complex conditions
+- Get data from JavaScript variables
+
+**Security restrictions (sandboxed):**
+- ❌ `fetch()`, `XMLHttpRequest`, `WebSocket` (no network access)
+- ❌ `eval()`, `Function()` (no code execution)
+- ❌ `window.location =` (no navigation)
+- ❌ `document.write()`, `innerHTML =` (no DOM mutation)
+- ❌ `document.cookie`, `localStorage`, `sessionStorage` (no storage access)
+- ❌ `import()`, `require()` (no dynamic imports)
+- ✅ `document.querySelector()`, `element.textContent` (read DOM)
+- ✅ `return` statement (output value)
+- ⏱️ 10s timeout (prevents infinite loops)
+
+**Examples:**
+```json
+// Get page title
+{"type": "executeScript", "data": {"script": "return document.title"}}
+
+// Get element count
+{"type": "executeScript", "data": {"script": "return document.querySelectorAll('button').length"}}
+
+// Check if element exists
+{"type": "executeScript", "data": {"script": "return !!document.querySelector('.error-message')"}}
+
+// Get input value
+{"type": "executeScript", "data": {"script": "return document.querySelector('#email').value"}}
+```
+
+### Form Submission: Use `press` Enter, NOT `click`
+```json
+// WRONG - unreliable on SPA
+{"type": "click", "data": {"selector": "button:has-text('Sign In')"}}
+
+// CORRECT - more reliable
+{"type": "press", "data": {"key": "Enter", "description": "Press Enter to submit"}}
+```
+
+### Page Assertions: Be Specific
+```json
+{"type": "assertVisible", "data": {"selector": "h1:has-text('Register')", "state": "visible"}}
+{"type": "assertVisible", "data": {"selector": "text=Halo", "state": "visible"}}
+```
+
+### URL Assertions: Use HTTPS
+```json
+// WRONG - HTTP redirects cause timeout
+{"type": "assertUrl", "data": {"expectedUrl": "http://dev.example.com/app/dashboard"}}
+
+// CORRECT
+{"type": "assertUrl", "data": {"expectedUrl": "https://dev.example.com/app/dashboard"}}
+```
+
+## Wait Strategy
+
+### After Navigation
+```json
+{"type": "navigate", "data": {"url": "{{project.BASE_URL}}/auth/login", "waitUntil": "load"}},
+{"type": "wait", "data": {"duration": 3000, "description": "Wait for page to fully load"}}
+```
+
+### After Form Submission
+```json
+{"type": "press", "data": {"key": "Enter"}},
+{"type": "wait", "data": {"duration": 3000, "description": "Wait for API response and redirect"}},
+{"type": "assertUrl", "data": {"expectedUrl": "{{project.BASE_URL}}/app/dashboard"}}
+```
+
+### Use `waitUntil: "load"` NOT `"networkidle"`
+`networkidle` can timeout on SPA pages with persistent connections.
+
+## Flow Structure Templates
+
+### Standard Flow with Login Fragment
+```
+start → callFragment (Login Fragment) → navigate → wait → assertVisible → ... test steps ...
+```
+
+### Registration Flow
+```
+start → navigate → assertVisible → fill fields → press Enter → wait → assertUrl
+```
+
+## Debugging Failed Runs
+
+### Get Step Details
+```
+get_run_status({ project_id: "...", flow_id: "...", run_id: "..." })
+```
+
+### Get Screenshot from Failed Step
+```
+get_run_screenshot({ run_id: "...", node_id: "assert_page" })
+```
+
+### Extract Text from Screenshot (OCR)
+```
+extract_screenshot_text({ image_url: "https://..." })
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Fragment with start node | Remove start node from fragments |
+| Using `click` for form submit | Use `press Enter` |
+| HTTP URLs | Use HTTPS |
+| `networkidle` waitUntil | Use `load` |
+| No wait after API call | Add 3s wait |
+| Hardcoded domain URLs | Use `{{project.BASE_URL}}` variable |
+| executeScript with `fetch()` | Use `apiCall` node instead |
+| executeScript with `async/await` | Use synchronous code only |
+| executeScript without `return` | Add `return` to get output |
+
+## Notes
+
+- Flows are `draft` by default. Call `publish_flow` before running.
+- Each test run needs a unique email. Use timestamp: `testuser+$(date +%s)@example.com`
+- Step details come from `/runs/:runId/steps` endpoint.
+- API client has auto-retry (3 attempts, exponential backoff).