@muggleai/mcp 1.0.0

package/dist/shared/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Shared type definitions for @muggleai/mcp.
+ */
+/**
+ * Auth0 configuration for device code flow.
+ */
+export interface IAuth0Config {
+    /** Auth0 domain (e.g., login.muggle-ai.com). */
+    domain: string;
+    /** Auth0 client ID for device code grant. */
+    clientId: string;
+    /** Auth0 API audience. */
+    audience: string;
+    /** OAuth scopes to request. */
+    scope: string;
+}
+/**
+ * Stored credentials from device code authentication.
+ */
+export interface IStoredCredentials {
+    /** Access token for API calls. */
+    accessToken: string;
+    /** Token expiration timestamp (ISO string). */
+    expiresAt: string;
+    /** User ID. */
+    userId?: string;
+    /** User email. */
+    email?: string;
+    /** API key (if created). */
+    apiKey?: string;
+    /** API key ID (if created). */
+    apiKeyId?: string;
+}
+/**
+ * Configuration for QA Gateway (cloud) operations.
+ */
+export interface IQaConfig {
+    /** Base URL of the prompt service backend. */
+    promptServiceBaseUrl: string;
+    /** Request timeout in milliseconds. */
+    requestTimeoutMs: number;
+    /** Workflow timeout in milliseconds. */
+    workflowTimeoutMs: number;
+}
+/**
+ * Configuration for Local QA operations.
+ */
+export interface ILocalQaConfig {
+    /** Base URL of the local web-service. */
+    webServiceUrl: string;
+    /** Base URL of the prompt service (for cloud sync). */
+    promptServiceUrl: string;
+    /** Path to data directory. */
+    dataDir: string;
+    /** Path to sessions directory. */
+    sessionsDir: string;
+    /** Path to projects directory. */
+    projectsDir: string;
+    /** Path to temp directory. */
+    tempDir: string;
+    /** Path to credentials file. */
+    credentialsFilePath: string;
+    /** Path to auth file (local auth storage). */
+    authFilePath: string;
+    /** Path to electron-app executable (null if not installed). */
+    electronAppPath: string | null;
+    /** Path to web-service entry point (null if not found). */
+    webServicePath: string | null;
+    /** Path to web-service PID file. */
+    webServicePidFile: string;
+    /** Auth0 configuration for local auth. */
+    auth0: ILocalAuth0Config;
+}
+/**
+ * Auth0 configuration for local auth (with scopes array).
+ */
+export interface ILocalAuth0Config {
+    /** Auth0 domain. */
+    domain: string;
+    /** Auth0 client ID. */
+    clientId: string;
+    /** Auth0 audience. */
+    audience: string;
+    /** OAuth scopes to request (as array). */
+    scopes: string[];
+}
+/**
+ * Unified configuration for @muggleai/mcp.
+ */
+export interface IConfig {
+    /** Server name for MCP protocol. */
+    serverName: string;
+    /** Server version. */
+    serverVersion: string;
+    /** Log level. */
+    logLevel: string;
+    /** Auth0 configuration. */
+    auth0: IAuth0Config;
+    /** QA Gateway configuration. */
+    qa: IQaConfig;
+    /** Local QA configuration. */
+    localQa: ILocalQaConfig;
+}
+/**
+ * Caller credentials for API requests.
+ */
+export interface ICallerCredentials {
+    /** Bearer token (from device code flow or config). */
+    bearerToken?: string;
+    /** API key (from device code flow or config). */
+    apiKey?: string;
+}
+/**
+ * Device code flow response from Auth0.
+ */
+export interface IDeviceCodeResponse {
+    /** Device code for polling. */
+    deviceCode: string;
+    /** User-visible code to enter. */
+    userCode: string;
+    /** URL for user to visit. */
+    verificationUri: string;
+    /** URL with code pre-filled. */
+    verificationUriComplete: string;
+    /** Seconds until code expires. */
+    expiresIn: number;
+    /** Polling interval in seconds. */
+    interval: number;
+    /** Whether browser was successfully opened. */
+    browserOpened: boolean;
+    /** Error message if browser failed to open. */
+    browserOpenError?: string;
+}
+/**
+ * Device code poll response.
+ */
+export interface IDeviceCodePollResponse {
+    /** Poll status. */
+    status: "authorized" | "authorization_pending" | "slow_down" | "expired_token" | "access_denied";
+    /** Access token (when authorized). */
+    accessToken?: string;
+    /** Token type (when authorized). */
+    tokenType?: string;
+    /** Token expiry in seconds (when authorized). */
+    expiresIn?: number;
+    /** Error code (when not authorized). */
+    error?: string;
+    /** Error description (when not authorized). */
+    errorDescription?: string;
+}
+/**
+ * MCP tool result structure.
+ */
+export interface IMcpToolResult {
+    /** Result content (text). */
+    content: string;
+    /** Whether this is an error result. */
+    isError?: boolean;
+}
+/**
+ * MCP tool definition.
+ */
+export interface IMcpTool {
+    /** Tool name. */
+    name: string;
+    /** Tool description. */
+    description: string;
+    /** Input schema (Zod schema). */
+    inputSchema: unknown;
+    /** Whether tool requires authentication (default: true for QA tools). */
+    requiresAuth?: boolean;
+    /** Execute the tool. */
+    execute: (params: {
+        input: unknown;
+        correlationId: string;
+    }) => Promise<IMcpToolResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@muggleai/mcp",
+  "version": "1.0.0",
+  "description": "Unified MCP server for Muggle AI - Cloud QA and Local Testing tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "muggle-mcp": "bin/muggle-mcp.js"
+  },
+  "files": [
+    "dist",
+    "bin/muggle-mcp.js",
+    "scripts/postinstall.mjs"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build:release": "npm run build",
+    "postinstall": "node scripts/postinstall.mjs",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "muggleConfig": {
+    "electronAppVersion": "1.0.0",
+    "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-mcp/releases/download"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "axios": "^1.7.9",
+    "commander": "^12.0.0",
+    "open": "^10.0.0",
+    "ulid": "^2.3.0",
+    "uuid": "^10.0.0",
+    "winston": "^3.17.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.21.0",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.34.0",
+    "@typescript-eslint/parser": "^8.34.0",
+    "eslint": "^9.28.0",
+    "eslint-plugin-unused-imports": "^4.2.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "muggle-ai",
+    "qa",
+    "testing",
+    "automation",
+    "localhost"
+  ],
+  "author": "Muggle AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/multiplex-ai/muggle-ai-mcp.git"
+  },
+  "homepage": "https://www.muggle-ai.com/muggleTestV0/docs/mcp/mcp-overview"
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script for @muggleai/mcp.
+ * Downloads the Electron app binary for local testing.
+ */
+
+import { exec } from "child_process";
+import { createWriteStream, existsSync, mkdirSync, rmSync } from "fs";
+import { homedir, platform } from "os";
+import { join } from "path";
+import { pipeline } from "stream/promises";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Get the Muggle AI data directory.
+ * @returns {string} Path to ~/.muggle-ai
+ */
+function getDataDir() {
+  return join(homedir(), ".muggle-ai");
+}
+
+/**
+ * Get the Electron app directory.
+ * @returns {string} Path to ~/.muggle-ai/electron-app
+ */
+function getElectronAppDir() {
+  return join(getDataDir(), "electron-app");
+}
+
+/**
+ * Get platform-specific binary name.
+ * @returns {string} Binary filename
+ */
+function getBinaryName() {
+  const os = platform();
+  const arch = process.arch;
+
+  switch (os) {
+    case "darwin":
+      // Support both Apple Silicon (arm64) and Intel (x64) Macs
+      return arch === "arm64"
+        ? "MuggleAI-darwin-arm64.zip"
+        : "MuggleAI-darwin-x64.zip";
+    case "win32":
+      return "MuggleAI-win32-x64.zip";
+    case "linux":
+      return "MuggleAI-linux-x64.zip";
+    default:
+      throw new Error(`Unsupported platform: ${os}`);
+  }
+}
+
+/**
+ * Download and extract the Electron app.
+ */
+async function downloadElectronApp() {
+  try {
+    // Read config from package.json
+    const packageJson = require("../package.json");
+    const config = packageJson.muggleConfig || {};
+    const version = config.electronAppVersion || "1.0.0";
+    const baseUrl = config.downloadBaseUrl || "https://github.com/multiplex-ai/muggle-ai-mcp/releases/download";
+
+    const binaryName = getBinaryName();
+    const downloadUrl = `${baseUrl}/electron-app-v${version}/${binaryName}`;
+
+    const appDir = getElectronAppDir();
+    const versionDir = join(appDir, version);
+
+    // Check if already downloaded
+    if (existsSync(versionDir)) {
+      console.log(`Electron app v${version} already installed at ${versionDir}`);
+      return;
+    }
+
+    console.log(`Downloading Muggle Test Electron app v${version}...`);
+    console.log(`URL: ${downloadUrl}`);
+
+    // Create directories
+    mkdirSync(versionDir, { recursive: true });
+
+    // Download using fetch
+    const response = await fetch(downloadUrl);
+    if (!response.ok) {
+      throw new Error(`Download failed: ${response.status} ${response.statusText}`);
+    }
+
+    const tempFile = join(versionDir, binaryName);
+    const fileStream = createWriteStream(tempFile);
+    await pipeline(response.body, fileStream);
+
+    console.log("Download complete, extracting...");
+
+    // Extract based on file type
+    if (binaryName.endsWith(".zip")) {
+      await extractZip(tempFile, versionDir);
+    } else if (binaryName.endsWith(".tar.gz")) {
+      await extractTarGz(tempFile, versionDir);
+    }
+
+    // Clean up temp file
+    rmSync(tempFile, { force: true });
+
+    console.log(`Electron app installed to ${versionDir}`);
+  } catch (error) {
+    console.warn("Warning: Failed to download Electron app.");
+    console.warn("You can manually download it later using: muggle-mcp setup");
+    console.warn(`Error: ${error.message}`);
+  }
+}
+
+/**
+ * Extract a zip file.
+ * @param {string} zipPath - Path to zip file
+ * @param {string} destDir - Destination directory
+ */
+async function extractZip(zipPath, destDir) {
+  return new Promise((resolve, reject) => {
+    const cmd = platform() === "win32"
+      ? `powershell -command "Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force"`
+      : `unzip -o "${zipPath}" -d "${destDir}"`;
+
+    exec(cmd, (error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+/**
+ * Extract a tar.gz file.
+ * @param {string} tarPath - Path to tar.gz file
+ * @param {string} destDir - Destination directory
+ */
+async function extractTarGz(tarPath, destDir) {
+  return new Promise((resolve, reject) => {
+    exec(`tar -xzf "${tarPath}" -C "${destDir}"`, (error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+// Run postinstall
+downloadElectronApp().catch(console.error);