air-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# AIR MCP Server
+
+The **AIR MCP Server** (Model Context Protocol) provides AI agents (like Claude Desktop, Gemini, or Cline) with deterministic, semantic access to your web automation recordings.
+
+It acts as the intelligent bridge between the [AIR VS Code Extension]https://marketplace.visualstudio.com/items?itemName=TestMasterHubAI.AIRAIInteractionRecorder and your LLMs, allowing AI to review user flows,intent, extract resilient locators, and generate Playwright tests with minimal effort to no effort.
+
+---
+
+## 🚀 Quick Start (Zero Installation)
+
+If you have the AIR VS Code Extension installed and have recorded a session, you do **not** need to install this package manually. 
+
+You can connect your AI directly using `npx`. Just add this configuration to your MCP client:
+
+### Claude Desktop Configuration
+Open your `claude_desktop_config.json` (or your chosen MCP client's config file) and add:
+
+```json
+{
+  "mcpServers": {
+    "air-desktop": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "air-mcp-server@latest"
+      ]
+    }
+  }
+}
+```
+*Note for Windows users: Depending on your terminal environment, you may need to use `"npx.cmd"` instead of `"npx"`.*
+
+Restart Claude Desktop, and your AI will immediately have access to your AIR recordings!
+
+---
+
+## 🛠️ Requirements
+
+- **Node.js 22 or higher** (Required for native `node:sqlite` database support).
+- Sessions recorded via the **AIR VS Code Extension**.
+
+---
+
+## 🧠 Capabilities (MCP Tools)
+
+This server exposes powerful tools directly to the LLM:
+
+1. **`list_recorded_sessions`**
+   - Retrieves all sessions recorded locally on your machine.
+   - LLMs use this to discover what web flows you have automated.
+
+2. **`get_session_flow_review`**
+   - Generates a human-readable summary of a specific session.
+   - Provides the AI with the overarching "intent" of the recording, the sequence of pages visited, and any warnings (like user interventions or assertions).
+
+3. **`get_session_generation_context`**
+   - The core engine for test generation. 
+   - Retrieves the machine-readable "AIR Selector Proof Packets" for every step in the session. This provides the LLM with the deterministic data needed to write resilient, self-healing Playwright scripts.
+
+---
+
+## ⚙️ Advanced: Custom Database Paths
+
+By default, the server reads the recording database from your unified AIR home directory (`~/.air/air-data.db`). 
+
+If you are running in a CI/CD environment or need to point to a specific database file, you can override this by passing the `--db` flag:
+
+```json
+{
+  "mcpServers": {
+    "air-desktop": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "air-mcp-server@latest",
+        "--db",
+        "/absolute/path/to/custom-air-data.db"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 📖 About AIR (Autonomous Interaction Recorder)
+
+AIR is designed to bridge the gap between human intent and deterministic web automation. By capturing semantic state changes rather than brittle XPaths, AIR ensures your UI tests remain resilient across app updates.
+
+

package/bin/air-mcp-http.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/http.js');

package/bin/air-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 22) {
+  console.error('[AIR MCP] Error: Node.js version 22 or higher is required.');
+  console.error(`[AIR MCP] You are currently running Node.js ${process.versions.node}.`);
+  console.error('[AIR MCP] Please upgrade Node.js to use the AIR MCP Server.');
+  process.exit(1);
+}
+
+require('../dist/index.js');

package/dist/core/utils/air-home.d.ts

@@ -0,0 +1,6 @@
+export declare function getAirHome(): string;
+export declare function ensureAirHome(): void;
+export declare function getDatabasePath(): string;
+export declare function getConfigPath(): string;
+export declare function getExportsPath(): string;
+export declare function getSessionMapsPath(): string;

package/dist/core/utils/air-home.js

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAirHome = getAirHome;
+exports.ensureAirHome = ensureAirHome;
+exports.getDatabasePath = getDatabasePath;
+exports.getConfigPath = getConfigPath;
+exports.getExportsPath = getExportsPath;
+exports.getSessionMapsPath = getSessionMapsPath;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+function getAirHome() {
+    if (process.env.AIR_HOME) {
+        return process.env.AIR_HOME;
+    }
+    if (process.env.AIR_DB_PATH) {
+        return path.dirname(process.env.AIR_DB_PATH);
+    }
+    return path.join(os.tmpdir(), 'air-desktop');
+}
+function ensureAirHome() {
+    const home = getAirHome();
+    if (!fs.existsSync(home)) {
+        fs.mkdirSync(home, { recursive: true });
+    }
+}
+function getDatabasePath() {
+    if (process.env.AIR_DB_PATH) {
+        return process.env.AIR_DB_PATH;
+    }
+    return path.join(getAirHome(), 'air-data.db');
+}
+function getConfigPath() {
+    return path.join(getAirHome(), 'config.json');
+}
+function getExportsPath() {
+    const exportsPath = path.join(getAirHome(), 'exports');
+    if (!fs.existsSync(exportsPath)) {
+        fs.mkdirSync(exportsPath, { recursive: true });
+    }
+    return exportsPath;
+}
+function getSessionMapsPath() {
+    const sessionMapsPath = path.join(getAirHome(), 'session-maps');
+    if (!fs.existsSync(sessionMapsPath)) {
+        fs.mkdirSync(sessionMapsPath, { recursive: true });
+    }
+    return sessionMapsPath;
+}