@xpufx/paseo-mcp-tools 0.1.3

package/server/health/health.ts

@@ -0,0 +1,274 @@
+import { McpClient } from "paseo-plugin-helper/mcp";
+import { withTimeout } from "paseo-plugin-helper/shared";
+import type { McpServer } from "../../shared/mcp";
+
+// GTD: generic health check that works with *every* MCP.
+// This is a CLIENT — we are not an MCP server, we just dial MCP servers.
+// Runs on the Paseo daemon (Node, can spawn), no extra daemon needed.
+// All transports (stdio, HTTP, SSE) go through the zero-dependency
+// helper McpClient — no @modelcontextprotocol/sdk required.
+
+export type HealthStatus = "healthy" | "degraded" | "down" | "unknown";
+
+export interface ToolInfo {
+  name: string;
+  description?: string;
+  inputSchema?: {
+    type?: string;
+    properties?: Record<string, {
+      type?: string;
+      description?: string;
+      default?: unknown;
+      enum?: string[];
+      items?: { type?: string };
+    }>;
+    required?: string[];
+  };
+}
+
+export interface HealthResult {
+  serverId: string;
+  name: string;
+  status: HealthStatus;
+  latencyMs: number;
+  toolCount: number | null;
+  tools: string[] | null;
+  toolDetails?: ToolInfo[] | null;
+  instructions: string | null;
+  error: string | null;
+  checkedAt: string;
+}
+
+export interface ToolCallResult {
+  content: Array<{ type: string; text?: string; [key: string]: unknown }>;
+  isError?: boolean;
+}
+
+export interface HealthCheckOptions {
+  timeoutMs?: number; // default 7000
+  includeTools?: boolean; // default true (list_tools)
+}
+
+type HelperClient = ReturnType<typeof McpClient.forStdio> | ReturnType<typeof McpClient.forHttp>;
+
+// command is e.g. "npx -y some-mcp" stored as string — first token is the
+// executable, the rest are args.
+function splitCommand(command: string): { command: string; args: string[] } {
+  const parts = command.trim().split(/\s+/);
+  return { command: parts[0], args: parts.slice(1) };
+}
+
+function dial(server: McpServer, timeoutMs: number): HelperClient | null {
+  const clientInfo = { name: "paseo-mcp-health", version: "1.0.0" };
+  if (server.url) {
+    return McpClient.forHttp(server.url, { timeoutMs, clientInfo });
+  }
+  if (server.command) {
+    // Prefer the structured args when the server definition carries
+    // them. Falling back to splitting the command string would drop
+    // them and spawn a bare runtime that hangs until timeout.
+    const { command, args } =
+      server.args && server.args.length > 0
+        ? { command: server.command, args: server.args }
+        : splitCommand(server.command);
+    return McpClient.forStdio(command, args, undefined, { timeoutMs, clientInfo });
+  }
+  return null;
+}
+
+function readInstructions(client: HelperClient): string | null {
+  const raw = client.instructions;
+  return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+
+function stderrOf(client: HelperClient): string | null {
+  if ("getStderr" in client && typeof client.getStderr === "function") {
+    try {
+      const text = (client.getStderr as () => string)();
+      return text?.trim() ? text : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function toToolDetails(list: Array<{ name: string; description?: string; inputSchema?: unknown }>): {
+  tools: string[];
+  toolDetails: ToolInfo[];
+} {
+  return {
+    tools: list.map((t) => t.name),
+    toolDetails: list.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema as ToolInfo["inputSchema"],
+    })),
+  };
+}
+
+export async function checkMcpServerHealth(
+  server: McpServer,
+  opts: HealthCheckOptions = {},
+): Promise<HealthResult> {
+  const timeoutMs = opts.timeoutMs ?? 7000;
+  const started = Date.now();
+  const checkedAt = new Date().toISOString();
+
+  const client = dial(server, timeoutMs);
+  if (!client) {
+    return {
+      serverId: server.id,
+      name: server.name,
+      status: "unknown",
+      latencyMs: 0,
+      toolCount: null,
+      tools: null,
+      instructions: null,
+      error: "No command or url to dial — unknown transport",
+      checkedAt,
+    };
+  }
+
+  const down = (base: string, includeStderr: boolean): HealthResult => {
+    const stderr = includeStderr ? stderrOf(client) : null;
+    return {
+      serverId: server.id,
+      name: server.name,
+      status: "down",
+      latencyMs: Date.now() - started,
+      toolCount: null,
+      tools: null,
+      toolDetails: null,
+      instructions: null,
+      error: stderr ? `${base}\nRecent stderr:\n${stderr}` : base,
+      checkedAt,
+    };
+  };
+
+  try {
+    if (opts.includeTools !== false) {
+      try {
+        const list = await withTimeout(client.listTools(), timeoutMs, "listTools");
+        const { tools, toolDetails } = toToolDetails(list);
+        const result: HealthResult = {
+          serverId: server.id,
+          name: server.name,
+          status: "healthy",
+          latencyMs: Date.now() - started,
+          toolCount: tools.length,
+          tools,
+          toolDetails,
+          instructions: readInstructions(client),
+          error: null,
+          checkedAt,
+        };
+        try {
+          await client.close();
+        } catch {}
+        return result;
+      } catch (e) {
+        // Connected but can't list tools = degraded. Verify reachability first.
+        try {
+          const ping = await withTimeout(client.ping(), timeoutMs, "ping");
+          if (ping.healthy) {
+            const result: HealthResult = {
+              serverId: server.id,
+              name: server.name,
+              status: "degraded",
+              latencyMs: Date.now() - started,
+              toolCount: null,
+              tools: null,
+              toolDetails: null,
+              instructions: readInstructions(client),
+              error: e instanceof Error ? e.message : String(e),
+              checkedAt,
+            };
+            try {
+              await client.close();
+            } catch {}
+            return result;
+          }
+        } catch {}
+        const result = down(e instanceof Error ? e.message : String(e), true);
+        try {
+          await client.close();
+        } catch {}
+        return result;
+      }
+    }
+
+    const ping = await withTimeout(client.ping(), timeoutMs, "ping");
+    const latencyMs = Date.now() - started;
+    const result: HealthResult = ping.healthy
+      ? {
+        serverId: server.id,
+        name: server.name,
+        status: "healthy",
+        latencyMs,
+        toolCount: null,
+        tools: null,
+        toolDetails: null,
+        instructions: readInstructions(client),
+        error: null,
+        checkedAt,
+      }
+      : {
+        serverId: server.id,
+        name: server.name,
+        status: "down",
+        latencyMs,
+        toolCount: null,
+        tools: null,
+        toolDetails: null,
+        instructions: null,
+        error: ping.error ?? "ping failed",
+        checkedAt,
+      };
+    try {
+      await client.close();
+    } catch {}
+    return result;
+  } catch (e) {
+    const result = down(e instanceof Error ? e.message : String(e), true);
+    try {
+      await client.close();
+    } catch {}
+    return result;
+  }
+}
+
+export async function callMcpServerTool(
+  server: McpServer,
+  toolName: string,
+  args: Record<string, unknown> = {},
+  timeoutMs = 15000,
+): Promise<ToolCallResult> {
+  const client = dial(server, timeoutMs);
+  if (!client) {
+    throw new Error(`Cannot execute tool on ${server.name}: unknown transport`);
+  }
+  try {
+    const result = await withTimeout(client.callTool(toolName, args), timeoutMs, `callTool:${toolName}`);
+    return result as ToolCallResult;
+  } finally {
+    try {
+      await client.close();
+    } catch {}
+  }
+}
+
+// Batch helper — parallel with concurrency cap so we don't fork-bomb the daemon.
+export async function checkMany(
+  servers: McpServer[],
+  opts: HealthCheckOptions & { concurrency?: number } = {},
+): Promise<HealthResult[]> {
+  const concurrency = opts.concurrency ?? 4;
+  const out: HealthResult[] = [];
+  for (let i = 0; i < servers.length; i += concurrency) {
+    const chunk = servers.slice(i, i + concurrency);
+    const results = await Promise.all(chunk.map((s) => checkMcpServerHealth(s, opts)));
+    out.push(...results);
+  }
+  return out;
+}

package/server/inject.ts

@@ -0,0 +1,32 @@
+import type { PluginBeforeRequests } from "@getpaseo/plugin/server";
+
+export const GATEWAY_SERVER_NAME = "gateway";
+
+export interface GatewayInjectOptions {
+  enabled: boolean;
+  url: string;
+}
+
+type CreateRequest = PluginBeforeRequests["agent.create"];
+
+// Returns a modified agent.create request with the gateway MCP server
+// injected, or undefined to keep the caller's request unchanged.
+export function injectGatewayIntoCreateRequest(
+  request: CreateRequest,
+  opts: GatewayInjectOptions,
+): CreateRequest | undefined {
+  if (!opts.enabled) return undefined;
+  if (!opts.url) return undefined;
+  const mcpServers = request.config.mcpServers ?? {};
+  if (mcpServers[GATEWAY_SERVER_NAME]) return undefined;
+  return {
+    ...request,
+    config: {
+      ...request.config,
+      mcpServers: {
+        ...mcpServers,
+        [GATEWAY_SERVER_NAME]: { type: "http", url: opts.url },
+      },
+    },
+  };
+}

package/server/mcp.ts

@@ -0,0 +1,365 @@
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { McpServerSchema, McpStatusSnapshot, McpToolsSettings } from "../shared/mcp";
+import { McpToolsSettingsSchema, buildHealthDigest } from "../shared/mcp";
+import { z } from "zod";
+import { probeForProvider } from "./providers";
+import { paseo as paseoProbe } from "./providers/catalog";
+import { PLUGIN_VERSION } from "../shared/version";
+// Direct source import. The helper MCP client has zero runtime deps,
+// so no bundling step is needed for the daemon to resolve it.
+import { createPluginLogger, PluginStorage, redactSecrets } from "paseo-plugin-helper/server";
+import { checkMany, checkMcpServerHealth, callMcpServerTool } from "./health/health";
+
+type McpServer = z.infer<typeof McpServerSchema>;
+
+export const log = createPluginLogger("mcp-tools");
+
+// Shared health snapshot for other plugins to consume without re-probing.
+const statusStorage = new PluginStorage<McpStatusSnapshot>("mcp-tools", "status.json");
+
+// Local settings reader. Kept separate from server/settings.ts to avoid
+// a module cycle, since that module imports the logger from here.
+const settingsReader = new PluginStorage<McpToolsSettings>("mcp-tools", "settings.json", {
+  schema: McpToolsSettingsSchema,
+});
+
+function healthDigestRowsEnabled(): boolean {
+  try {
+    return settingsReader.read().healthDigestRows === true;
+  } catch {
+    return false;
+  }
+}
+
+const PASEO_TOOLS: Array<{ name: string; description: string; category: string }> = [
+  { name: "create_agent", description: "Create an agent, optionally in a workspace", category: "Agents" },
+  { name: "send_agent_prompt", description: "Send a task to a running agent", category: "Agents" },
+  { name: "get_agent_status", description: "Return latest snapshot for an agent", category: "Agents" },
+  { name: "list_agents", description: "List recent agents as compact metadata", category: "Agents" },
+  { name: "archive_agent", description: "Soft-delete an agent", category: "Agents" },
+  { name: "create_workspace", description: "Create a local or worktree-isolated workspace", category: "Workspaces" },
+  { name: "list_workspaces", description: "List active workspaces", category: "Workspaces" },
+  { name: "archive_workspace", description: "Archive a workspace and its sessions", category: "Workspaces" },
+  { name: "list_workspace_scripts", description: "List configured workspace scripts", category: "Scripts" },
+  { name: "start_workspace_script", description: "Start a configured script", category: "Scripts" },
+  { name: "stop_workspace_script", description: "Stop a running script", category: "Scripts" },
+  { name: "list_terminals", description: "List terminal sessions", category: "Terminals" },
+  { name: "create_terminal", description: "Create a terminal session", category: "Terminals" },
+  { name: "capture_terminal", description: "Capture terminal output", category: "Terminals" },
+  { name: "send_terminal_keys", description: "Send keys to a terminal", category: "Terminals" },
+  { name: "list_providers", description: "List configured agent providers", category: "Providers" },
+  { name: "list_models", description: "List models for a provider", category: "Providers" },
+  { name: "inspect_provider", description: "Inspect provider capabilities", category: "Providers" },
+];
+
+function redact(text: string): string {
+  return redactSecrets(text, { mask: "•••" });
+}
+
+function redactConfig(def: unknown): string {
+  return JSON.stringify(redactSecrets(def, { mask: "•••" }), null, 2);
+}
+
+async function loadAgent(agentId: string, context: PluginHandlerContext) {
+  const handle = context.paseo.agents.ref(agentId);
+  const refreshed = await handle.refresh();
+  const agent = refreshed?.agent ?? handle.current();
+  if (!agent) throw new Error(`Agent not found: ${agentId}`);
+  const snapshot = agent as Record<string, unknown>;
+  const labelCandidates = ["providerLabel", "label", "displayName", "model"]
+    .map((k) => snapshot[k])
+    .filter((v): v is string => typeof v === "string" && v.length > 0);
+  return { provider: agent.provider, cwd: agent.cwd, handle, snapshot: agent, labelCandidates };
+}
+
+async function findStoredRecord(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;
+}
+
+// Cache provider probe results keyed by `provider:cwd` to avoid redundant
+// filesystem inspections and CLI process spawns when multiple agents share the same project/tool.
+const PROBE_CACHE_TTL_MS = 60_000; // 1 minute TTL
+const probeCache = new Map<string, { timestamp: number; result: { servers: McpServer[]; error: string | null } }>();
+
+async function getCachedProviderProbe(agentId: string, provider: string, cwd: string, bypassCache = false, labels: string[] = []) {
+  const cacheKey = `${provider}:${cwd}`;
+  const now = Date.now();
+  const cached = probeCache.get(cacheKey);
+
+  if (!bypassCache && cached && now - cached.timestamp < PROBE_CACHE_TTL_MS) {
+    return cached.result;
+  }
+
+  const probe = probeForProvider(provider, ...labels);
+  if (!probe) {
+    return { servers: [], error: null };
+  }
+
+  const res = await probe.probe({ agentId, provider, cwd });
+  const result = { servers: res.servers, error: res.error ?? null };
+  probeCache.set(cacheKey, { timestamp: now, result });
+  return result;
+}
+
+/**
+ * Live servers for THIS agent only.
+ * 1) Paseo-injected `mcpServers` from StoredAgentRecord (session-scoped custom servers)
+ * 2) Provider-specific live probe — cached by `provider:cwd` across concurrent agents
+ */
+export async function discoverLiveServers(
+  agentId: string,
+  context: PluginHandlerContext,
+  options: { bypassCache?: boolean } = {},
+): Promise<{ servers: McpServer[]; error: string | null }> {
+  const agent = await loadAgent(agentId, context);
+  const servers: McpServer[] = [];
+  let error: string | null = null;
+
+  try {
+    const paseoRes = await paseoProbe.probe({ agentId, provider: "paseo", cwd: agent.cwd });
+    for (const s of paseoRes.servers) {
+      if (!servers.some((existing) => existing.id === s.id || existing.name === s.name)) {
+        servers.push(s);
+      }
+    }
+
+    const record = await findStoredRecord(agentId);
+    const cfg = (record?.config ?? {}) as Record<string, unknown>;
+    const mcpServers = (cfg.mcpServers ?? {}) as Record<string, unknown>;
+    for (const [name, defRaw] of Object.entries(mcpServers)) {
+      if (!defRaw || typeof defRaw !== "object" || name === "paseo") continue;
+      const def = defRaw as Record<string, unknown>;
+      const url = typeof def.url === "string" ? def.url : null;
+      const command = typeof def.command === "string" ? def.command : null;
+      const defArgs = Array.isArray(def.args) ? def.args.filter((a) => typeof a === "string") : [];
+      servers.push({
+        id: `session:paseo:${name}`,
+        name,
+        transport: url ? "http" : command ? "stdio" : "unknown",
+        source: { kind: "session", label: `session · ${agent.provider}`, path: `agent:${agentId}` },
+        command,
+        args: defArgs.length > 0 ? defArgs : null,
+        url,
+        description: url ?? command ?? JSON.stringify(def).slice(0, 80),
+        hasSecrets: Boolean(def.env || def.headers),
+        configPreview: redactConfig(def),
+      });
+    }
+
+    const probeResult = await getCachedProviderProbe(agentId, agent.provider, agent.cwd, options.bypassCache, agent.labelCandidates);
+    for (const s of probeResult.servers) {
+      if (servers.some((existing) => existing.name === s.name)) continue;
+      servers.push(s);
+    }
+    if (probeResult.error) {
+      error = probeResult.error;
+      log.warn("Provider probe reported error", { provider: agent.provider, error });
+    }
+    log.info("Discovered live servers", { provider: agent.provider, count: servers.length });
+  } catch (e) {
+    error = e instanceof Error ? e.message : String(e);
+    log.error("Failed to discover live servers", { provider: agent.provider, error });
+  }
+
+  return { servers, error };
+}
+
+export function createListMcpHandler() {
+  return async (input: { agentId: string }, context: PluginHandlerContext) => {
+    const agent = await loadAgent(input.agentId, context);
+    const { servers, error } = await discoverLiveServers(input.agentId, context);
+    return { provider: agent.provider, cwd: agent.cwd, servers, paseoTools: PASEO_TOOLS, error };
+  };
+}
+
+export function createReadMcpHandler() {
+  return async (input: { agentId: string; serverId: string }, context: PluginHandlerContext) => {
+    const { servers } = await discoverLiveServers(input.agentId, context);
+    const entry = servers.find((s) => s.id === input.serverId);
+    if (!entry) throw new Error(`MCP server not found in this session: ${input.serverId}`);
+    return {
+      name: entry.name,
+      transport: entry.transport,
+      source: entry.source,
+      path: entry.source.path,
+      raw: entry.configPreview,
+      redacted: entry.configPreview,
+    };
+  };
+}
+
+export function createHealthHandler() {
+  return async (input: { agentId: string; serverId?: string }, context: PluginHandlerContext) => {
+    const { servers, error } = await discoverLiveServers(input.agentId, context);
+    const targets = input.serverId ? servers.filter((s) => s.id === input.serverId) : servers;
+    if (input.serverId && targets.length === 0) {
+      throw new Error(`MCP server not found in this session: ${input.serverId}`);
+    }
+    const results = await checkMany(targets, { timeoutMs: 7000, includeTools: true });
+    const snapshot: McpStatusSnapshot = {
+      updatedAt: new Date().toISOString(),
+      total: results.length,
+      healthy: results.filter((r) => r.status === "healthy").length,
+      degraded: results.filter((r) => r.status === "degraded").length,
+      down: results.filter((r) => r.status === "down").length,
+      servers: results.map((r) => ({ name: r.name, status: r.status, latencyMs: r.latencyMs })),
+    };
+    await statusStorage.writeAsync(snapshot).catch((e) => {
+      log.warn("Failed to persist status snapshot", { error: e instanceof Error ? e.message : String(e) });
+    });
+
+    if (healthDigestRowsEnabled()) {
+      await context.paseo.agents
+        .ref(input.agentId)
+        .timeline.append({
+          type: "plugin",
+          id: "mcp-health",
+          kind: "mcp-health-digest",
+          version: 1,
+          data: buildHealthDigest(snapshot),
+        })
+        .catch((e) => {
+          log.warn("Failed to append health digest row", { error: e instanceof Error ? e.message : String(e) });
+        });
+    }
+
+    return { results, error };
+  };
+}
+
+export function createCallMcpToolHandler() {
+  return async (
+    input: { agentId: string; serverId: string; toolName: string; arguments: Record<string, unknown> },
+    context: PluginHandlerContext,
+  ) => {
+    const { servers } = await discoverLiveServers(input.agentId, context);
+    const server = servers.find((s) => s.id === input.serverId);
+    if (!server) {
+      throw new Error(`MCP server not found in this session: ${input.serverId}`);
+    }
+    try {
+      const result = await (callMcpServerTool as (s: McpServer, t: string, a: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string; [key: string]: unknown }>; isError?: boolean }>)(
+        server,
+        input.toolName,
+        input.arguments,
+      );
+      return {
+        content: result.content ?? [],
+        isError: result.isError,
+        error: null,
+      };
+    } catch (e) {
+      return {
+        content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+        isError: true,
+        error: e instanceof Error ? e.message : String(e),
+      };
+    }
+  };
+}
+
+export function createDiagnoseMcpHandler() {
+  return async (input: { agentId: string }, context: PluginHandlerContext) => {
+    const agent = await loadAgent(input.agentId, context);
+    const steps: Array<{ target: string; status: "found" | "missing" | "error" | "skipped"; details: string; contentPreview: string | null }> = [];
+    const home = os.homedir();
+
+    // 1. Check Paseo stored agent record
+    try {
+      const record = await findStoredRecord(input.agentId);
+      if (record) {
+        const cfg = (record.config ?? {}) as Record<string, unknown>;
+        const mcpServers = (cfg.mcpServers ?? {}) as Record<string, unknown>;
+        const names = Object.keys(mcpServers);
+        steps.push({
+          target: `Paseo Agent Record (${input.agentId})`,
+          status: "found",
+          details: `Found record with ${names.length} MCP server(s): ${names.join(", ") || "none"}`,
+          contentPreview: redactConfig(cfg.mcpServers ?? {}),
+        });
+      } else {
+        steps.push({
+          target: `Paseo Agent Record (${input.agentId})`,
+          status: "missing",
+          details: "No stored record file found in ~/.paseo/agents",
+          contentPreview: null,
+        });
+      }
+    } catch (e) {
+      steps.push({
+        target: `Paseo Agent Record (${input.agentId})`,
+        status: "error",
+        details: e instanceof Error ? e.message : String(e),
+        contentPreview: null,
+      });
+    }
+
+    // 2. Run Provider Probe & Collect Diagnostic Steps Polymorphically
+    const probe = probeForProvider(agent.provider, ...agent.labelCandidates);
+    let discoveredServerCount = 0;
+    let probeError: string | null = null;
+
+    if (probe) {
+      try {
+        const result = await probe.probe({
+          agentId: input.agentId,
+          provider: agent.provider,
+          cwd: agent.cwd,
+          sessionId: (agent as Record<string, unknown>).sessionId as string | undefined,
+        });
+        discoveredServerCount = result.servers.length;
+        if (result.error) probeError = result.error;
+        if (result.steps && result.steps.length > 0) {
+          steps.push(...result.steps);
+        }
+      } catch (e) {
+        probeError = e instanceof Error ? e.message : String(e);
+        steps.push({
+          target: `Provider Probe (${probe.id})`,
+          status: "error",
+          details: probeError,
+          contentPreview: null,
+        });
+      }
+    } else {
+      steps.push({
+        target: `Provider Probe (${agent.provider})`,
+        status: "missing",
+        details: "No probe found matching this provider in registry",
+        contentPreview: null,
+      });
+    }
+
+    return {
+      report: "Paseo Provider MCP Probe Diagnostic",
+      version: PLUGIN_VERSION,
+      provider: agent.provider,
+      cwd: agent.cwd,
+      probeId: probe?.id ?? null,
+      probeLabel: probe?.label ?? null,
+      steps,
+      discoveredServerCount,
+      error: probeError,
+    };
+  };
+}