@xpufx/paseo-mcp-tools 0.1.3

package/client/vendor/paseo-plugin-helper/utils/clipboard.ts

@@ -0,0 +1,149 @@
+import type { HostToast } from "../host";
+import { getOptionalClientHost } from "../host";
+
+export interface CopyToClipboardOptions {
+  toast?: HostToast;
+  toastMessage?: string;
+}
+
+export type ClipboardTier = "navigator" | "host" | "rnAsync" | "rnSync" | "execCommand";
+
+export interface ClipboardEnvironment {
+  hasNavigatorClipboard: boolean;
+  hasHostCopyText: boolean;
+  hasRnClipboard: boolean;
+  hasRnSetStringAsync: boolean;
+  isDom: boolean;
+}
+
+/**
+ * Deterministic tier order for an explicit copy.
+ *
+ * Web's `navigator.clipboard.writeText` is the only API that rejects when the
+ * clipboard did not change, so it leads. The synchronous
+ * `react-native-web` `Clipboard.setString` reports success even when its
+ * `document.execCommand("copy")` fails, which leaves the previous clipboard
+ * item in place while the UI claims success (xpufx-org/paseo#278); it is only
+ * usable off-DOM (native), where it is the real platform clipboard. In a DOM
+ * the checked `execCommand` fallback is preferred to that unverifiable path.
+ */
+export function clipboardTierOrder(env: ClipboardEnvironment): ClipboardTier[] {
+  const tiers: ClipboardTier[] = [];
+  if (env.hasNavigatorClipboard) tiers.push("navigator");
+  if (env.hasHostCopyText) tiers.push("host");
+  if (env.hasRnSetStringAsync) {
+    tiers.push("rnAsync");
+  } else if (env.hasRnClipboard && !env.isDom) {
+    tiers.push("rnSync");
+  }
+  tiers.push("execCommand");
+  return tiers;
+}
+
+/**
+ * Robust cross-platform clipboard copy helper for Paseo plugins.
+ * Works seamlessly across React Native (mobile), web, and desktop.
+ *
+ * Tier order comes from `clipboardTierOrder`; every tier reports failure
+ * honestly so a denied or blocked write never leaves the previous clipboard
+ * item behind under a fake success.
+ */
+export async function copyToClipboard(
+  text: string,
+  options?: CopyToClipboardOptions,
+): Promise<boolean> {
+  if (text === null || text === undefined) return false;
+  const str = String(text);
+
+  const globalObj = typeof globalThis !== "undefined" ? (globalThis as any) : {};
+
+  let rn: any;
+  try {
+    rn = require("react-native");
+  } catch {
+    // Ignore require error if not in RN context
+  }
+  const rnClipboard = rn?.Clipboard;
+  const rnSetStringAsync =
+    typeof rnClipboard?.setStringAsync === "function" ? rnClipboard.setStringAsync : undefined;
+  const rnSetString =
+    typeof rnClipboard?.setString === "function" ? rnClipboard.setString : undefined;
+  const copyText = getOptionalClientHost()?.copyText;
+
+  const isDom =
+    typeof globalObj.document !== "undefined" &&
+    typeof globalObj.document?.createElement === "function";
+
+  const tiers = clipboardTierOrder({
+    hasNavigatorClipboard: Boolean(globalObj.navigator?.clipboard?.writeText),
+    hasHostCopyText: Boolean(copyText),
+    hasRnClipboard: Boolean(rnSetStringAsync ?? rnSetString),
+    hasRnSetStringAsync: Boolean(rnSetStringAsync),
+    isDom,
+  });
+
+  let success = false;
+  for (const tier of tiers) {
+    if (success) break;
+    try {
+      switch (tier) {
+        case "navigator":
+          await globalObj.navigator.clipboard.writeText(str);
+          success = true;
+          break;
+        case "host":
+          if (copyText) {
+            await copyText(str);
+            success = true;
+          }
+          break;
+        case "rnAsync":
+          // Expo's async API returns a boolean; a rejected promise falls through.
+          success = (await rnSetStringAsync(str)) !== false;
+          break;
+        case "rnSync":
+          // Only reached off-DOM, where this is the native platform clipboard.
+          rnSetString(str);
+          success = true;
+          break;
+        case "execCommand": {
+          const doc = globalObj.document;
+          if (doc?.createElement && doc?.body) {
+            const textarea = doc.createElement("textarea");
+            textarea.value = str;
+            textarea.style.position = "fixed";
+            textarea.style.opacity = "0";
+            textarea.style.left = "-9999px";
+            doc.body.appendChild(textarea);
+            textarea.focus();
+            textarea.select();
+            const res = doc.execCommand("copy");
+            doc.body.removeChild(textarea);
+            success = res === true;
+          }
+          break;
+        }
+      }
+    } catch {
+      // Tier failed; try the next one.
+    }
+  }
+
+  if (success && options?.toast) {
+    try {
+      const toastAny = options.toast as any;
+      if (typeof toastAny.copied === "function") {
+        toastAny.copied(options.toastMessage);
+      } else if (typeof toastAny.show === "function") {
+        const msg = options.toastMessage
+          ? `Copied ${options.toastMessage} to clipboard`
+          : "Copied to clipboard";
+        toastAny.show(msg, { variant: "success" });
+      }
+    } catch {
+      // Ignore toast failure
+    }
+  }
+
+  return success;
+}

package/client/vendor/paseo-plugin-helper/utils/haptics.ts

@@ -0,0 +1,34 @@
+export type HapticFeedbackType =
+  | "light"
+  | "medium"
+  | "heavy"
+  | "success"
+  | "warning"
+  | "error";
+
+const PATTERNS: Record<HapticFeedbackType, number | number[]> = {
+  light: 10,
+  medium: 25,
+  heavy: 45,
+  success: [15, 40, 20],
+  warning: [30, 50, 30],
+  error: [40, 60, 40, 60, 40],
+};
+
+/**
+ * Cross-platform haptic feedback helper for Paseo plugins.
+ * Supports web vibration API and graceful fallback when vibration is unavailable.
+ */
+export function triggerHaptic(type: HapticFeedbackType = "light"): boolean {
+  try {
+    const globalObj = typeof globalThis !== "undefined" ? (globalThis as any) : {};
+    const nav = globalObj.navigator;
+    if (typeof nav?.vibrate === "function") {
+      const pattern = PATTERNS[type] ?? 15;
+      return Boolean(nav.vibrate(pattern));
+    }
+  } catch {
+    // Ignore environments where vibration permissions are denied or unavailable
+  }
+  return false;
+}

package/docs/TEST_METHODOLOGY.md

@@ -0,0 +1,29 @@
+# Testing Notes & Environment Log
+
+## Test Setup
+- **Host**: Ubuntu 24.04 LTS (kernel 6.8, x86_64)
+- **Runtime**: Node.js 22.23
+- **Environment**: Local daemon process running on the host system
+
+---
+
+## What We Tested and How
+
+### 1. Adapter Crash Prevention & Contracts
+We started by writing an automated test runner that loops over every registered adapter. For each one, we simulated a fresh machine with no config files or target software installed. The goal was to make sure no adapter throws an unhandled exception or kills the host process if its target isn't there. We also checked that every adapter returns the exact object shapes the UI expects, and that any API keys or tokens are stripped out before anything gets displayed.
+
+### 2. Config Discovery & File Precedence
+Next, we tested how configs get discovered on disk. We created dummy folder structures with broken JSON, missing paths, and conflicting settings to verify that project-level configs override user-level or global ones. After synthetic tests passed, we ran the parser against real config files already sitting on the machine. This confirmed the parser handles real-world config formats without needing paid accounts or live subscriptions active.
+
+### 3. Transport Layers (Pipes & Local HTTP)
+Once parsing worked, we tested the connections:
+- **Subprocesses**: We checked that background processes spawn cleanly, talk over stdin/stdout pipes, and exit without leaving zombie processes behind.
+- **Local HTTP**: We pointed health checks at a local daemon, timed the handshake, measured ping latency, and pulled the tool lists.
+
+### 4. Running Tools
+With connections healthy, we ran real commands through the tool runner. We picked safe, read-only queries (like listing status or workspaces) and confirmed arguments pass through properly, the response text renders cleanly in the UI, and bad inputs return readable error messages instead of hanging.
+
+### 5. Packaging & Live Plugin Reload
+Finally, we tested the build and installation flow:
+- We verified that protocol libraries get bundled directly into the build so the plugin doesn't break on a machine without those packages installed globally.
+- We installed the build into the running daemon, triggered a hot reload, watched the daemon logs to verify clean startup with no warnings, and clicked through the UI to verify everything loaded and ran.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@xpufx/paseo-mcp-tools",
+  "private": false,
+  "version": "0.1.3",
+  "license": "MIT",
+  "scripts": {
+    "stamp": "node scripts/version.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@getpaseo/plugin": "0.9.0-beta.2",
+    "@getpaseo/protocol": "0.9.0-beta.2",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.10",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "paseo-plugin.json",
+    "README.md",
+    "LICENSE",
+    "client",
+    "server",
+    "shared",
+    "docs",
+    "scripts",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.test.mjs",
+    "!**/.DS_Store"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xpufx/paseo.git"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,4 @@
+{
+  "id": "mcp-tools",
+  "requirements": { "paseo": ">=0.8.0" }
+}

package/scripts/version.mjs

@@ -0,0 +1,4 @@
+const { stampVersion } = await import("../server/vendor/paseo-plugin-helper/version.ts");
+
+const { version, updated } = stampVersion({ targetFile: "./shared/version.ts" });
+console.log(`[build] PLUGIN_VERSION ${updated ? "stamped" : "up to date"}: "${version}" in shared/version.ts`);

package/server/discovery/extract.ts

@@ -0,0 +1,277 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { redactSecrets, tryParseJsonc } from "paseo-plugin-helper/server";
+import type { McpServer, DiagnosticStep } from "./types";
+
+export interface CandidatePath {
+  path: string;
+  label: string;
+}
+
+/**
+ * Redacts tokens, keys, passwords, and sensitive auth data via helper.
+ */
+export function redact(text: string): string {
+  return redactSecrets(text, { mask: "•••" });
+}
+
+/**
+ * Universal JSON / JSONC / Trailing-comma tolerant parser via helper.
+ * Returns null instead of throwing so callers degrade gracefully.
+ */
+export function parseJsonc(raw: string): unknown | null {
+  if (!raw || typeof raw !== "string") return null;
+  const parsed = tryParseJsonc<unknown>(raw, null);
+  if (parsed !== null) return parsed;
+  return tryParseJsonc<unknown>(raw.replace(/,\s*([}\]])/g, "$1"), null);
+}
+
+/**
+ * Heuristically finds the container holding MCP server definitions in arbitrary JSON.
+ */
+function findServersContainer(data: unknown): Record<string, unknown> | Array<unknown> | null {
+  if (!data || typeof data !== "object") return null;
+
+  if (Array.isArray(data)) {
+    return data;
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  // Common root key heuristics across all ecosystem tools
+  const candidateKeys = [
+    "mcpServers",
+    "mcp-servers",
+    "mcp_servers",
+    "servers",
+    "mcp",
+    "plugins",
+  ];
+
+  for (const key of candidateKeys) {
+    if (key in obj && obj[key] && typeof obj[key] === "object") {
+      return obj[key] as Record<string, unknown> | Array<unknown>;
+    }
+  }
+
+  // Heuristic: Is the root object itself a map of servers?
+  // Check if properties look like server definitions (have command, url, type, transport, args, or module)
+  const entries = Object.entries(obj);
+  if (entries.length > 0) {
+    const looksLikeServers = entries.every(([_, val]) => {
+      if (!val || typeof val !== "object" || Array.isArray(val)) return false;
+      const v = val as Record<string, unknown>;
+      return Boolean(v.command || v.url || v.type || v.transport || v.args || v.module || v.entrypoint);
+    });
+    if (looksLikeServers) {
+      return obj;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Normalizes an arbitrary server definition entry into a standard McpServer.
+ */
+export function normalizeMcpServer(
+  idPrefix: string,
+  nameHint: string,
+  defRaw: unknown,
+  sourcePath: string,
+  sourceLabel: string,
+): McpServer | null {
+  if (!defRaw || typeof defRaw !== "object" || Array.isArray(defRaw)) return null;
+  const def = defRaw as Record<string, unknown>;
+
+  // Check disabled heuristics
+  if (def.disabled === true || def.enabled === false || def.active === false) {
+    return null;
+  }
+
+  const name = typeof def.name === "string" && def.name.trim() ? def.name.trim() : nameHint;
+  if (!name) return null;
+
+  // Extract URL
+  const url =
+    typeof def.url === "string"
+      ? def.url
+      : typeof def.endpoint === "string"
+        ? def.endpoint
+        : typeof def.serverUrl === "string"
+          ? def.serverUrl
+          : null;
+
+  // Extract command & args. Keep the structured args alongside the
+  // joined command string so dialers can spawn the exact argv.
+  let command: string | null = null;
+  let argv: string[] | null = null;
+  if (typeof def.command === "string") {
+    const argList = Array.isArray(def.args) ? def.args.filter((a) => typeof a === "string") : [];
+    if (argList.length > 0) argv = argList;
+    const args = argList.join(" ");
+    command = args ? `${def.command} ${args}` : def.command;
+  } else if (typeof def.socket === "string") {
+    command = def.socket;
+  } else if (typeof def.module === "string") {
+    command = `node ${def.module}`;
+  }
+
+  // Determine transport
+  let transport: McpServer["transport"] = "unknown";
+  if (url) {
+    const isSse = def.type === "sse" || def.transport === "sse" || url.includes("/sse");
+    transport = isSse ? "sse" : "http";
+  } else if (command) {
+    transport = "stdio";
+  } else if (def.transport === "stdio" || def.transport === "http" || def.transport === "sse") {
+    transport = def.transport;
+  }
+
+  // Detect secrets
+  const hasSecrets = Boolean(
+    def.env ||
+    def.headers ||
+    def.auth ||
+    def.bearerToken ||
+    def.apiKey ||
+    def.token ||
+    def.secret
+  );
+
+  // Description heuristic
+  const description =
+    (typeof def.description === "string" && def.description) ||
+    url ||
+    command ||
+    "";
+
+  return {
+    id: `session:${idPrefix}:${name}`,
+    name,
+    transport,
+    source: {
+      kind: "session",
+      label: sourceLabel,
+      path: sourcePath,
+    },
+    command,
+    args: argv,
+    url,
+    description,
+    hasSecrets,
+    configPreview: JSON.stringify(redactSecrets(def, { mask: "•••" }), null, 2),
+  };
+}
+
+/**
+ * Extracts all valid MCP servers from raw JSON/JSONC text using heuristics.
+ */
+export function extractMcpServersFromText(
+  rawText: string,
+  idPrefix: string,
+  sourcePath: string,
+  sourceLabel: string,
+): McpServer[] {
+  const parsed = parseJsonc(rawText);
+  if (!parsed) return [];
+
+  const container = findServersContainer(parsed);
+  if (!container) return [];
+
+  const servers: McpServer[] = [];
+
+  if (Array.isArray(container)) {
+    for (let i = 0; i < container.length; i++) {
+      const item = container[i];
+      const s = normalizeMcpServer(idPrefix, `server-${i + 1}`, item, sourcePath, sourceLabel);
+      if (s) servers.push(s);
+    }
+  } else {
+    for (const [name, item] of Object.entries(container)) {
+      const s = normalizeMcpServer(idPrefix, name, item, sourcePath, sourceLabel);
+      if (s) servers.push(s);
+    }
+  }
+
+  return servers;
+}
+
+/**
+ * Discovers MCP servers across multiple candidate paths with low -> high precedence merging.
+ */
+export async function discoverFromCandidates(
+  idPrefix: string,
+  candidates: CandidatePath[],
+): Promise<{ servers: McpServer[]; error: string | null; steps: DiagnosticStep[] }> {
+  const merged = new Map<string, { def: unknown; name: string; source: CandidatePath }>();
+  const steps: DiagnosticStep[] = [];
+
+  for (const cand of candidates) {
+    if (!existsSync(cand.path)) {
+      steps.push({
+        target: cand.path,
+        status: "missing",
+        details: `${cand.label} does not exist`,
+        contentPreview: null,
+      });
+      continue;
+    }
+    try {
+      const raw = await readFile(cand.path, "utf8");
+      const parsed = parseJsonc(raw);
+      if (!parsed) {
+        steps.push({
+          target: cand.path,
+          status: "error",
+          details: `${cand.label} (${raw.length} bytes) · Invalid JSON/JSONC syntax`,
+          contentPreview: redact(raw.slice(0, 1000)),
+        });
+        continue;
+      }
+
+      const container = findServersContainer(parsed);
+      let count = 0;
+      if (container) {
+        if (Array.isArray(container)) {
+          count = container.length;
+          for (let i = 0; i < container.length; i++) {
+            const item = container[i];
+            const name = (item && typeof item === "object" && typeof (item as Record<string, unknown>).name === "string")
+              ? (item as Record<string, unknown>).name as string
+              : `server-${i + 1}`;
+            merged.set(name, { def: item, name, source: cand });
+          }
+        } else {
+          const entries = Object.entries(container);
+          count = entries.length;
+          for (const [name, item] of entries) {
+            merged.set(name, { def: item, name, source: cand });
+          }
+        }
+      }
+
+      steps.push({
+        target: cand.path,
+        status: "found",
+        details: `${cand.label} (${raw.length} bytes) · Valid config with ${count} MCP server(s)`,
+        contentPreview: redact(raw.slice(0, 1000)),
+      });
+    } catch (e) {
+      steps.push({
+        target: cand.path,
+        status: "error",
+        details: `${cand.label} failed to read: ${e instanceof Error ? e.message : String(e)}`,
+        contentPreview: null,
+      });
+    }
+  }
+
+  const servers: McpServer[] = [];
+  for (const [_, { def, name, source }] of merged) {
+    const s = normalizeMcpServer(idPrefix, name, def, source.path, source.label);
+    if (s) servers.push(s);
+  }
+
+  return { servers, error: null, steps };
+}

package/server/discovery/types.ts

@@ -0,0 +1,23 @@
+import type { McpServer, DiagnosticStep } from "../../shared/mcp";
+
+export type { McpServer, DiagnosticStep };
+
+export interface ProbeContext {
+  agentId: string;
+  provider: string;
+  cwd: string;
+  sessionId?: string | null;
+}
+
+export interface ProbeResult {
+  servers: McpServer[];
+  error?: string | null;
+  steps?: DiagnosticStep[];
+}
+
+export interface McpProbe {
+  id: string;
+  label: string;
+  matches(provider: string): boolean;
+  probe(ctx: ProbeContext): Promise<ProbeResult>;
+}