@xpufx/paseo-mcp-tools 0.1.3

package/server/providers/README.md

@@ -0,0 +1,51 @@
+# Provider Probes — Contract-First
+
+You don't test people's probe logic, you test that they satisfy the interface. Adding a new provider only touches **one file + 1 line in catalog**.
+
+## Contract
+
+`discovery/types.ts: McpProbe`
+
+```ts
+interface McpProbe {
+  id: string;                      // key in registry, e.g. "opencode"
+  label: string;                   // human, e.g. "opencode · live"
+  matches(provider: string): bool  // does this probe handle this Paseo provider id?
+  probe(ctx: ProbeContext): Promise<ProbeResult> // live probe run
+}
+
+interface ProbeContext { agentId: string; provider: string; cwd: string; sessionId?: string | null }
+interface ProbeResult { servers: McpServer[]; error?: string | null; steps?: DiagnosticStep[] }
+```
+
+`McpServer` is `shared/mcp.ts: McpServerSchema` — `id, name, transport, source{kind,label,path}, command, url, description, hasSecrets, configPreview`.
+
+## Adding a provider
+
+1. Create `providers/<id>.ts`:
+   ```ts
+   import type { McpProbe, ProbeContext } from "../discovery/types";
+
+   const myProbe: McpProbe = {
+     id: "mycli",
+     label: "mycli · live",
+     matches: (p) => p === "mycli",
+     async probe(ctx: ProbeContext) {
+       // discover servers
+       return { servers: [...], error: null };
+     },
+   };
+
+   export default myProbe;
+   ```
+
+2. Add 1 line to `providers/catalog.ts`:
+   ```ts
+   export { default as mycli } from "./mycli";
+   ```
+
+3. Done. The probe is automatically indexed into `probes`, used by `probeForProvider`, reported in diagnostics, and validated by `npm test`.
+
+## Tests
+
+`providers/providers.test.ts` checks contract compliance — `id` format, `probe` execution, and Zod validation for every returned server.

package/server/providers/antigravity.ts

@@ -0,0 +1,22 @@
+import os from "node:os";
+import path from "node:path";
+import { matchesFamily } from "./family";
+import { discoverFromCandidates } from "../discovery/extract";
+import type { McpProbe, ProbeContext } from "../discovery/types";
+
+export const antigravityProbe: McpProbe = {
+  id: "antigravity",
+  label: "antigravity · live",
+  matches: (provider) => matchesFamily(provider, "antigravity"),
+  async probe(ctx: ProbeContext) {
+    const home = os.homedir();
+    return discoverFromCandidates("antigravity", [
+      { path: path.join(home, ".gemini", "config", "mcp_config.json"), label: "antigravity · user global" },
+      { path: path.join(home, ".gemini", "antigravity", "mcp_config.json"), label: "antigravity · app global" },
+      { path: path.join(ctx.cwd, ".gemini", "mcp_config.json"), label: "antigravity · project config" },
+      { path: path.join(ctx.cwd, "mcp_config.json"), label: "antigravity · project root" },
+    ]);
+  },
+};
+
+export default antigravityProbe;

package/server/providers/catalog.ts

@@ -0,0 +1,6 @@
+export { default as antigravity } from "./antigravity";
+export { default as claude } from "./claude";
+export { default as codex } from "./codex";
+export { default as opencode } from "./opencode";
+export { default as paseo } from "./paseo";
+export { default as pi } from "./pi";

package/server/providers/claude.ts

@@ -0,0 +1,21 @@
+import os from "node:os";
+import path from "node:path";
+import { matchesFamily } from "./family";
+import { discoverFromCandidates } from "../discovery/extract";
+import type { McpProbe, ProbeContext } from "../discovery/types";
+
+export const claudeProbe: McpProbe = {
+  id: "claude",
+  label: "claude · live",
+  matches: (provider) => matchesFamily(provider, "claude"),
+  async probe(ctx: ProbeContext) {
+    const home = os.homedir();
+    return discoverFromCandidates("claude", [
+      { path: path.join(home, ".claude.json"), label: "claude · user global" },
+      { path: path.join(home, ".claude", "settings.json"), label: "claude · settings global" },
+      { path: path.join(ctx.cwd, ".claude.json"), label: "claude · project shared" },
+    ]);
+  },
+};
+
+export default claudeProbe;

package/server/providers/codex.ts

@@ -0,0 +1,85 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { matchesFamily } from "./family";
+import type { McpProbe, McpServer, ProbeContext } from "../discovery/types";
+
+export const codexProbe: McpProbe = {
+  id: "codex",
+  label: "codex · live",
+  matches: (provider) => matchesFamily(provider, "codex"),
+  async probe(ctx: ProbeContext) {
+    const home = os.homedir();
+    const candidatePaths = [
+      { path: path.join(home, ".codex", "config.toml"), label: "codex · user global" },
+      { path: path.join(ctx.cwd, ".codex", "config.toml"), label: "codex · project override" },
+    ];
+
+    const merged = new Map<string, McpServer>();
+    const steps: Array<{ target: string; status: "found" | "missing" | "error" | "skipped"; details: string; contentPreview: string | null }> = [];
+
+    for (const cand of candidatePaths) {
+      if (!existsSync(cand.path)) {
+        steps.push({
+          target: cand.path,
+          status: "missing",
+          details: `${cand.label} does not exist`,
+          contentPreview: null,
+        });
+        continue;
+      }
+      try {
+        const text = await readFile(cand.path, "utf8");
+        const sections = text.split(/^\s*\[mcp_servers\./gm).slice(1);
+        let count = 0;
+        for (const sec of sections) {
+          const lines = sec.split("\n");
+          const name = (lines[0] || "").replace(/\][\s\S]*$/, "").trim();
+          if (!name) continue;
+          count++;
+          const body = lines.slice(1).join("\n");
+          const cmdMatch = body.match(/^\s*command\s*=\s*"([^"]+)"/m);
+          const urlMatch = body.match(/^\s*url\s*=\s*"([^"]+)"/m);
+          const command = cmdMatch ? cmdMatch[1] : null;
+          const url = urlMatch ? urlMatch[1] : null;
+          const transport = url ? ("http" as const) : command ? ("stdio" as const) : ("unknown" as const);
+
+          merged.set(name, {
+            id: `session:codex:${name}`,
+            name,
+            transport,
+            source: { kind: "session" as const, label: cand.label, path: cand.path },
+            command,
+            url,
+            description: url ?? command ?? "codex mcp (toml)",
+            hasSecrets: /env|token|key|secret/i.test(body),
+            configPreview: `[mcp_servers.${name}]\n${body.slice(0, 500).trim()}`,
+          });
+        }
+        steps.push({
+          target: cand.path,
+          status: "found",
+          details: `${cand.label} (${text.length} bytes) · Valid TOML with ${count} MCP server(s)`,
+          contentPreview: text.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,
+        });
+        return { servers: [], error: e instanceof Error ? e.message : String(e), steps };
+      }
+    }
+
+    return {
+      servers: [...merged.values()],
+      error: null,
+      steps,
+    };
+  },
+};
+
+export default codexProbe;

package/server/providers/family.ts

@@ -0,0 +1,24 @@
+const AFFIX_SEPS = ["-", "_", ":", "/"];
+
+function norm(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function matchesFamily(provider: string, family: string): boolean {
+  const p = norm(provider);
+  const f = norm(family);
+  if (!p || !f) return false;
+  if (p === f) return true;
+  return AFFIX_SEPS.some((sep) => p.startsWith(f + sep) || p.endsWith(sep + f));
+}
+
+export function matchesAnyFamily(provider: string, families: string[]): boolean {
+  return families.some((family) => matchesFamily(provider, family));
+}
+
+export const OPENCODE_FORK_IDS = ["example-fork", "sample-fork"];
+
+export function matchesOpencodeFamily(provider: string): boolean {
+  const p = norm(provider);
+  return matchesFamily(p, "opencode") || OPENCODE_FORK_IDS.includes(p);
+}

package/server/providers/index.ts

@@ -0,0 +1,11 @@
+import type { McpProbe } from "../discovery/types";
+import * as catalog from "./catalog";
+
+export const probes: McpProbe[] = Object.values(catalog);
+
+export function probeForProvider(provider: string, ...labels: Array<string | null | undefined>): McpProbe | null {
+  const candidates = [provider, ...labels].filter((c): c is string => typeof c === "string" && c.length > 0);
+  return probes.find((p) => candidates.some((c) => p.matches(c))) ?? null;
+}
+
+export * from "./catalog";

package/server/providers/opencode.ts

@@ -0,0 +1,95 @@
+import os from "node:os";
+import path from "node:path";
+import { safeSpawn } from "paseo-plugin-helper/server";
+import { stripAnsi } from "paseo-plugin-helper/shared";
+import type { McpProbe, ProbeContext, McpServer } from "../discovery/types";
+import { matchesOpencodeFamily } from "./family";
+import { redact } from "../discovery/extract";
+
+function parseOpencodeMcpList(output: string, cfgPath: string): McpServer[] {
+  const clean = stripAnsi(output);
+  const lines = clean.split("\n");
+  const servers: McpServer[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const m = line.match(/^[●○•]\s*[✓✗○●]?\s*(\S+)\s+(connected|disabled|failed|connecting)?/);
+    if (!m) continue;
+    const name = m[1];
+    const status = m[2] ?? "unknown";
+    const next = lines[i + 1]?.trim().replace(/^│\s*/, "") ?? "";
+    const isUrl = next.startsWith("http");
+    const isDisabled = status === "disabled";
+    if (isDisabled) continue;
+    const url = isUrl ? next : null;
+    const command = !isUrl && next ? next : null;
+    const transport: McpServer["transport"] = url ? "http" : command ? "stdio" : "unknown";
+    servers.push({
+      id: `session:opencode:${name}`,
+      name,
+      transport,
+      source: { kind: "session", label: "opencode · live", path: cfgPath },
+      command,
+      url,
+      description: `${next} [${status}]`,
+      hasSecrets: false,
+      configPreview: redact(next),
+    });
+  }
+  return servers;
+}
+
+export const opencodeProbe: McpProbe = {
+  id: "opencode",
+  label: "opencode · live",
+  matches: (provider) => matchesOpencodeFamily(provider),
+  async probe(ctx: ProbeContext) {
+    const globalCfg = path.join(os.homedir(), ".config", "opencode", "opencode.jsonc");
+    const localCfg = path.join(ctx.cwd, "opencode.json");
+    const cfgPath = `${globalCfg} + ${localCfg} (cwd-merged)`;
+    const target = "opencode mcp list (CLI)";
+    let out: string;
+    try {
+      const res = await safeSpawn("opencode", ["mcp", "list"], { cwd: ctx.cwd, timeoutMs: 5000 });
+      out = res.stdout;
+      if (res.code !== 0 && !out) {
+        const msg = res.stderr || `opencode mcp list exited ${res.code}`;
+        return {
+          servers: [],
+          error: msg,
+          steps: [{ target, status: "error" as const, details: msg, contentPreview: null }],
+        };
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return {
+        servers: [],
+        error: msg,
+        steps: [{ target, status: "error" as const, details: msg, contentPreview: null }],
+      };
+    }
+    try {
+      const servers = parseOpencodeMcpList(out, cfgPath);
+      return {
+        servers,
+        error: null,
+        steps: [
+          {
+            target,
+            status: "found" as const,
+            details: `CLI returned ${servers.length} active server(s)`,
+            contentPreview: redact(out.slice(0, 1000)),
+          },
+        ],
+      };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return {
+        servers: [],
+        error: msg,
+        steps: [{ target, status: "error" as const, details: msg, contentPreview: redact(out.slice(0, 1000)) }],
+      };
+    }
+  },
+};
+
+export default opencodeProbe;

package/server/providers/paseo.ts

@@ -0,0 +1,112 @@
+import os from "node:os";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { matchesFamily } from "./family";
+import type { McpProbe, ProbeContext, ProbeResult, DiagnosticStep } from "../discovery/types";
+import type { McpServer } from "../../shared/mcp";
+
+export async function findStoredAgentRecord(agentId: string): Promise<Record<string, unknown> | null> {
+  const base = path.join(os.homedir(), ".paseo", "agents");
+  if (!existsSync(base)) return null;
+  try {
+    const projects = await readdir(base, { withFileTypes: true });
+    for (const ent of projects) {
+      const cand = ent.isDirectory()
+        ? path.join(base, ent.name, `${agentId}.json`)
+        : path.join(base, ent.name);
+      if (ent.isFile() && ent.name !== `${agentId}.json`) continue;
+      if (existsSync(cand)) {
+        try {
+          return JSON.parse(await readFile(cand, "utf8")) as Record<string, unknown>;
+        } catch {}
+      }
+    }
+  } catch {}
+  return null;
+}
+
+export const paseoProbe: McpProbe = {
+  id: "paseo",
+  label: "Paseo · Built-in",
+  matches: (provider) => matchesFamily(provider, "paseo"),
+  async probe(ctx: ProbeContext): Promise<ProbeResult> {
+    const steps: DiagnosticStep[] = [];
+    const record = await findStoredAgentRecord(ctx.agentId);
+    const cfg = (record?.config ?? {}) as Record<string, unknown>;
+    const meta = (record?.metadata ?? {}) as Record<string, unknown>;
+    const mcpServers = ((cfg.mcpServers ?? meta.mcpServers ?? {}) as Record<string, unknown>);
+    const paseoDef = mcpServers.paseo as Record<string, unknown> | undefined;
+
+    if (record) {
+      steps.push({
+        target: "Paseo Agent Record",
+        status: "found",
+        details: paseoDef?.url ? `Active session endpoint: ${paseoDef.url}` : "Found record, no explicit paseo MCP entry",
+        contentPreview: paseoDef ? JSON.stringify(paseoDef, null, 2) : null,
+      });
+    } else {
+      steps.push({
+        target: "Paseo Agent Record",
+        status: "missing",
+        details: `No stored agent record found for ID ${ctx.agentId}`,
+        contentPreview: null,
+      });
+    }
+
+    let url: string | null = null;
+    let hasSecrets = false;
+    if (paseoDef && typeof paseoDef.url === "string") {
+      url = paseoDef.url;
+      hasSecrets = Boolean(paseoDef.headers);
+    } else {
+      const configPath = path.join(os.homedir(), ".paseo", "config.json");
+      if (existsSync(configPath)) {
+        try {
+          const configJson = JSON.parse(await readFile(configPath, "utf8")) as Record<string, unknown>;
+          const daemon = (configJson.daemon ?? {}) as Record<string, unknown>;
+          const mcp = (daemon.mcp ?? {}) as Record<string, unknown>;
+          const enabled = mcp.enabled !== false && mcp.injectIntoAgents !== false;
+          steps.push({
+            target: "Paseo Daemon MCP Config",
+            status: enabled ? "found" : "skipped",
+            details: `mcp.enabled=${mcp.enabled !== false}, injectIntoAgents=${mcp.injectIntoAgents !== false}, listen=${daemon.listen ?? "default"}`,
+            contentPreview: JSON.stringify(daemon.mcp, null, 2),
+          });
+
+          if (enabled) {
+            const listen = typeof daemon.listen === "string" ? daemon.listen : "127.0.0.1:6767";
+            url = `http://${listen}/mcp/agents?callerAgentId=${ctx.agentId}`;
+          }
+        } catch (e) {
+          steps.push({
+            target: "Paseo Daemon MCP Config",
+            status: "error",
+            details: e instanceof Error ? e.message : String(e),
+            contentPreview: null,
+          });
+        }
+      }
+    }
+
+    if (!url) {
+      return { servers: [], steps };
+    }
+
+    const server: McpServer = {
+      id: "session:paseo",
+      name: "Paseo (Builtin)",
+      transport: "http",
+      source: { kind: "paseo", label: "Paseo · Built-in", path: url },
+      command: null,
+      url,
+      description: "Paseo control plane, agent automation & browser tools",
+      hasSecrets,
+      configPreview: JSON.stringify({ name: "Paseo (Builtin)", url }, null, 2),
+    };
+
+    return { servers: [server], steps };
+  },
+};
+
+export default paseoProbe;

package/server/providers/pi.ts

@@ -0,0 +1,39 @@
+import os from "node:os";
+import path from "node:path";
+import { matchesFamily } from "./family";
+import { discoverFromCandidates } from "../discovery/extract";
+import type { McpProbe, ProbeContext } from "../discovery/types";
+
+export const piProbe: McpProbe = {
+  id: "pi",
+  label: "pi · live",
+  matches: (provider) => matchesFamily(provider, "pi"),
+  async probe(ctx: ProbeContext) {
+    const home = os.homedir();
+    const envDir = process.env.PI_CODING_AGENT_DIR?.trim()
+      ? path.resolve(process.env.PI_CODING_AGENT_DIR.trim().replace(/^~\//, `${home}/`))
+      : null;
+
+    // Precedence: lower index = base default, higher index = override wins
+    return discoverFromCandidates("pi", [
+      { path: path.join(home, ".config", "mcp", "mcp.json"), label: "pi · global shared" },
+      { path: path.join(home, ".agents", "mcp.json"), label: "pi · agents global" },
+      { path: path.join(home, ".agents", "mcp", "mcp.json"), label: "pi · agents nested" },
+      { path: path.join(home, ".pi", "agent", "mcp.json"), label: "pi · agent global" },
+      { path: path.join(home, ".pi", "mcp.json"), label: "pi · user config" },
+      { path: path.join(home, ".pi", ".mcp.json"), label: "pi · user config" },
+      ...(envDir
+        ? [
+            { path: path.join(envDir, "mcp.json"), label: "pi · env config" },
+            { path: path.join(envDir, ".mcp.json"), label: "pi · env config" },
+          ]
+        : []),
+      { path: path.join(ctx.cwd, "mcp.json"), label: "pi · project shared" },
+      { path: path.join(ctx.cwd, ".mcp.json"), label: "pi · project shared" },
+      { path: path.join(ctx.cwd, ".pi", "mcp.json"), label: "pi · project override" },
+      { path: path.join(ctx.cwd, ".pi", ".mcp.json"), label: "pi · project override" },
+    ]);
+  },
+};
+
+export default piProbe;

package/server/settings.ts

@@ -0,0 +1,19 @@
+import { PluginStorage, createSettingsHandlers } from "paseo-plugin-helper/server";
+import { log } from "./mcp";
+import { mcpToolsSettingsContract, type McpToolsSettings } from "../shared/mcp";
+
+export const settingsStorage = new PluginStorage<McpToolsSettings>("mcp-tools", "settings.json", {
+  schema: mcpToolsSettingsContract.schema,
+});
+
+// Plain handler functions on purpose: index.server.ts wires them via
+// server.handle, which is the only call form the compiler strips
+// from the client bundle.
+export const settingsHandlers = createSettingsHandlers(mcpToolsSettingsContract, settingsStorage, {
+  onUpdate: (next) => {
+    log.info("Settings updated", next);
+  },
+  onReset: () => {
+    log.info("Settings reset to defaults");
+  },
+});

package/server/vendor/paseo-plugin-helper/agent.ts

@@ -0,0 +1,85 @@
+import { safeExec } from "./process";
+
+export interface AgentIdentity {
+  id?: string;
+  name?: string;
+  model?: string;
+  provider?: string;
+  repo?: string;
+  branch?: string;
+  envelopeText?: string;
+}
+
+export interface AgentIdentityOptions {
+  timeoutMs?: number;
+  envelopeCommand?: string;
+}
+
+const ENV_KEYS = [
+  "AGENT_ID",
+  "AGENT_NAME",
+  "AGENT_MODEL",
+  "AGENT_PROVIDER",
+  "PASEO_AGENT_ID",
+] as const;
+
+function readEnvIdentity(env: NodeJS.ProcessEnv = process.env): AgentIdentity | null {
+  const id = env.PASEO_AGENT_ID || env.AGENT_ID || undefined;
+  const name = env.AGENT_NAME || undefined;
+  const model = env.AGENT_MODEL || undefined;
+  const provider = env.AGENT_PROVIDER || undefined;
+  if (!id && !name && !model && !provider) return null;
+  return { id, name, model, provider };
+}
+
+function normalizeEnvelopeJson(raw: unknown): AgentIdentity | null {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? v : undefined;
+  const identity: AgentIdentity = {
+    id: str(o.id) ?? str(o.agentId),
+    name: str(o.name) ?? str(o.agentName),
+    model: str(o.model),
+    provider: str(o.provider),
+    repo: str(o.repo) ?? str(o.workspace),
+    branch: str(o.branch),
+    envelopeText: str(o.envelopeText) ?? str(o.envelope),
+  };
+  if (!identity.id && !identity.name && !identity.model && !identity.provider && !identity.repo && !identity.branch) return null;
+  return identity;
+}
+
+export async function getAgentIdentity(
+  options: AgentIdentityOptions = {},
+): Promise<AgentIdentity | null> {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const command = options.envelopeCommand ?? "xpufx-tool envelope --format json";
+  const envIdentity = readEnvIdentity();
+  void ENV_KEYS;
+  try {
+    const result = await safeExec(command, { timeoutMs });
+    if (result.code !== 0) return envIdentity;
+    const text = result.stdout.trim();
+    if (!text) return envIdentity;
+    try {
+      const parsed: unknown = JSON.parse(text);
+      const cliIdentity = normalizeEnvelopeJson(parsed);
+      if (!cliIdentity) return envIdentity;
+      if (!envIdentity) return cliIdentity;
+      return {
+        id: envIdentity.id ?? cliIdentity.id,
+        name: envIdentity.name ?? cliIdentity.name,
+        model: envIdentity.model ?? cliIdentity.model,
+        provider: envIdentity.provider ?? cliIdentity.provider,
+        repo: cliIdentity.repo,
+        branch: cliIdentity.branch,
+        envelopeText: cliIdentity.envelopeText,
+      };
+    } catch {
+      return envIdentity;
+    }
+  } catch {
+    return envIdentity;
+  }
+}