@xpufx/paseo-mcp-tools 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xpufx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# paseo-mcp-tools plugin
+
+> **⚠️ WIP — use at your own risk.** Not release-ready; APIs and behavior may change without notice.
+
+Provides an inline UI for checking MCP servers available to an agent session with additional functionality per MCP, such as listing and directly executing MCP tools with auto-generated input forms. Uses the most authoritative list per provider CLI and verifies actual session inclusion with live probes.
+
+(**Paseo** is an agent orchestrator: AI coding agents run on paseo daemons, each managing workspaces, tools, and permissions.)
+
+Built on [paseo-plugin-helper](https://github.com/xpufx/paseo/tree/main/packages/paseo-plugin-helper), the shared Paseo plugin runtime.
+
+## Screenshots
+
+| MCP Servers | Diagnostics | Settings |
+| :---: | :---: | :---: |
+| <img src="screenshots/mcp-servers.png" width="100%" alt="MCP Servers" /> | <img src="screenshots/mcp-diagnostic.png" width="100%" alt="Diagnostics" /> | <img src="screenshots/mcp-settings.png" width="100%" alt="Settings" /> |
+
+| Server Details | Tool Execution |
+| :---: | :---: |
+| <img src="screenshots/mcp-server-details.png" width="100%" alt="Server Details" /> | <img src="screenshots/mcp-execute.png" width="100%" alt="Tool Execution" /> |
+
+## What it does
+
+- **Pill** above the composer shows `MCP n` (live servers for that agent). Badge updates via `mcp.list`, shared between pill and modal.
+- **Live discovery** per-CLI via isolated `providers/<id>.ts` (`opencode` → `opencode mcp list`, `claude` → `~/.claude.json` live, `antigravity` → `~/.gemini/config/mcp_config.json`, etc.) + Paseo-injected `StoredAgentRecord.mcpServers`. Groups by `source.label`, dedupes by name.
+- **Paseo Built-in Host MCP**: Automatically discovers Paseo's host daemon control plane (`/mcp/agents?callerAgentId=...`) as a first-class MCP server (`Paseo (Builtin)`), exposing all 60+ live tools (workspaces, browser automation, schedules, terminals, agent orchestration).
+- **Detail & Live Health**: Server tap reveals real-time status dots, latency, server instructions, and full tool declarations.
+- **Interactive Tool Runner (User Execution)**: Users can execute any discovered MCP tool directly from the UI without prompting the agent. Features a dynamic schema-driven form with `*REQUIRED` validation, type coercion (boolean, number, object, array, union/nullable types), live tool execution via host RPC (`mcp.call_tool`), and output inspection with 1-tap clipboard copying.
+- **Real-Time Tool Search**: Server Detail view features a real-time search input filtering across tool names and descriptions, making servers with large command sets (like Paseo, Forgejo, Chrome DevTools) fast and easy to navigate.
+- **Diagnostics**: Full polymorphic probe checklist verifying paths, permissions, and agent records across hosts.
+
+## Supported Providers
+
+| Provider | Probe Mechanism | Status |
+|---|---|---|
+| **Paseo** (`paseo`) | Built-in host daemon MCP control plane (`~/.paseo/config.json` + live daemon HTTP session) | **Fully tested & verified (60+ tools)** |
+| **Antigravity** (`antigravity`, `antigravity-acp`) | Global `~/.gemini/config/mcp_config.json` + `~/.antigravity/mcp_config.json` | **Fully tested & verified** |
+| **OpenCode** (`opencode`) | Live `opencode mcp list` daemon CLI command + config | **Fully tested & verified** |
+| **Pi** (`pi`) | User canonical `~/.pi/.mcp.json` / project overrides + heuristics | **Fully tested & verified** |
+| **Claude** (`claude`) | User `~/.claude.json` / project `.claude.json` heuristics | **Tested against real active configs** *(without live subscription session)* |
+| **CodeX** (`codex`) | Global `~/.codex/config.toml` / project `.codex/config.toml` | **Provided as-is** *(without guarantees)* |
+
+## Dropping in New Providers
+
+Adding a new tool/CLI probe (e.g. Cursor, Windsurf, Zed, Roo, Cline) is black-box and takes 2 simple steps:
+1. Create `providers/<id>.ts` declaring candidate config paths using `discoverFromCandidates()` (or live CLI RPC) with `export default <id>Probe`.
+2. Add a 1-line re-export to `providers/catalog.ts`: `export { default as <id> } from "./<id>";`.
+
+See the complete step-by-step guide in the [write-mcp-provider skill](.agents/skills/write-mcp-provider/SKILL.md) (`.agents/skills/write-mcp-provider/SKILL.md`). Run `npm test` to automatically verify the probe satisfies the contract.
+
+## Layout
+
+| File | Owns |
+|---|---|
+| [`index.ts`](index.ts) | Wiring only: `handle(mcp.list)`, `handle(mcp.read)`, `handle(mcp.health)`, `handle(mcp.call_tool)`, `handle(mcp.diagnose)`, `addClientSide` |
+| [`mcp.shared.ts`](mcp.shared.ts) | zod RPC contracts & shared types (`ToolInfoSchema`, `callMcpTool`, etc.) |
+| [`mcp.server.ts`](mcp.server.ts) | `discoverLiveServers()`, tool runner execution bridge, and polymorphic diagnostic handlers |
+| [`discovery/extract.ts`](discovery/extract.ts) | Universal heuristic MCP parser (JSON/JSONC, comments, trailing commas, URL safe) & candidate discovery |
+| [`discovery/types.ts`](discovery/types.ts) | Core contracts (`McpProbe`, `ProbeContext`, `ProbeResult`) |
+| [`providers/<id>.ts`](providers/) | Per-CLI live probe (isolated, contract `McpProbe`: `antigravity.ts`, `claude.ts`, etc.) |
+| [`providers/paseo.ts`](providers/paseo.ts) | Dedicated host daemon probe discovering Paseo control plane & tools |
+| [`providers/catalog.ts`](providers/catalog.ts) | 1-line re-export catalog for zero-boilerplate probe registration |
+| [`health/health.server.ts`](health/health.server.ts) | Generic MCP SDK client (`instructions`, schema-aware `tools`, and `callMcpServerTool`) |
+| [`mcp-query.client.tsx`](mcp-query.client.tsx) | `useMcpQuery` shared pill/modal, 30m timer + manual Refresh |
+| [`pill.client.tsx`](pill.client.tsx) | Pill, modal, server details, diagnostics, real-time search, and interactive Tool Runner UI |
+| [`scripts/version.mjs`](scripts/version.mjs) | Offline build-time version stamper (tag / beta-[hash]) |
+| [`docs/TEST_METHODOLOGY.md`](docs/TEST_METHODOLOGY.md) | Test procedures, adapter verification, and QA methodology |
+
+## Install & Updates
+
+```bash
+# from git (recommended)
+paseo plugin add xpufx/paseo-mcp-tools
+
+# update to latest release
+paseo plugin update mcp-tools
+
+# or from a local checkout (path-linked for development)
+paseo plugin install "$PWD"
+
+# reload daemon process after local edits
+paseo plugin reload mcp-tools
+```
+
+`pluginsEnabled: true` required. Use `paseo plugin logs mcp-tools` for diagnostics and runtime logs. Failed reload stays failed (Paseo doesn't restore).

package/client/__snapshots__/attribution.test.tsx.snap

@@ -0,0 +1,170 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`attribution labels on shared surfaces > labels the MCP tool call card 1`] = `
+<View
+  style={
+    {
+      "alignItems": "center",
+      "flexDirection": "row",
+      "gap": 8,
+    }
+  }
+>
+  <Text
+    style={
+      {
+        "color": "#00aa00",
+        "fontSize": 13,
+      }
+    }
+  >
+    ●
+  </Text>
+  <View
+    style={
+      {
+        "flex": 1,
+        "minWidth": 0,
+      }
+    }
+  >
+    <Text
+      numberOfLines={1}
+      style={
+        {
+          "color": "#000000",
+          "fontFamily": "monospace",
+          "fontSize": 13,
+          "fontWeight": "600",
+        }
+      }
+    >
+      forgejo
+      __
+      list_branches
+    </Text>
+    <Text
+      style={
+        {
+          "color": "#666666",
+          "fontSize": 11,
+        }
+      }
+    >
+      MCP tool call 
+      completed
+    </Text>
+    <ViaMcpTools
+      colors={
+        {
+          "foreground": "#000000",
+          "foregroundMuted": "#666666",
+          "statusDanger": "#ff0000",
+          "statusSuccess": "#00aa00",
+        }
+      }
+    />
+  </View>
+</View>
+`;
+
+exports[`attribution labels on shared surfaces > labels the health digest card 1`] = `
+<View
+  style={
+    {
+      "gap": 2,
+    }
+  }
+>
+  <Text
+    style={
+      {
+        "color": "#000000",
+        "fontSize": 13,
+        "fontWeight": "600",
+      }
+    }
+  >
+    MCP fleet health: 
+    3 healthy / 0 degraded / 1 down of 4
+  </Text>
+  <Text
+    style={
+      {
+        "color": "#666666",
+        "fontSize": 11,
+      }
+    }
+  >
+    Checked 
+    2026-09-06T00:00:00.000Z
+  </Text>
+  <ViaMcpTools
+    colors={
+      {
+        "foreground": "#000000",
+        "foregroundMuted": "#666666",
+        "statusDanger": "#ff0000",
+        "statusSuccess": "#00aa00",
+      }
+    }
+  />
+</View>
+`;
+
+exports[`attribution labels on shared surfaces > labels the slash result card 1`] = `
+<View
+  style={
+    {
+      "gap": 4,
+    }
+  }
+>
+  <Text
+    style={
+      {
+        "color": "#000000",
+        "fontSize": 13,
+        "fontWeight": "600",
+      }
+    }
+  >
+    MCP probe
+  </Text>
+  <Text
+    selectable={true}
+    style={
+      {
+        "color": "#000000",
+        "fontFamily": "monospace",
+        "fontSize": 12,
+      }
+    }
+  >
+    4 servers
+  </Text>
+  <ViaMcpTools
+    colors={
+      {
+        "foreground": "#000000",
+        "foregroundMuted": "#666666",
+        "statusDanger": "#ff0000",
+        "statusSuccess": "#00aa00",
+      }
+    }
+  />
+</View>
+`;
+
+exports[`attribution labels on shared surfaces > labels the via footer 1`] = `
+<Text
+  style={
+    {
+      "color": "#666666",
+      "fontSize": 10,
+    }
+  }
+>
+  via mcp-tools
+</Text>
+`;

package/client/commands.ts

@@ -0,0 +1,113 @@
+import type { PluginAgentCommandContext, PluginClientContext } from "@getpaseo/plugin/client";
+import { buildHealthDigest } from "../shared/mcp";
+import { callMcpTool, checkMcpHealth, listMcp } from "../shared/mcp";
+
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength)}... (truncated)`;
+}
+
+async function appendSlashResult(
+  ctx: PluginAgentCommandContext,
+  title: string,
+  body: string,
+): Promise<void> {
+  await ctx.paseo.agents.ref(ctx.agent.id).timeline.append({
+    type: "plugin",
+    id: "mcp-slash",
+    kind: "mcp-slash-result",
+    version: 1,
+    data: { title, body: truncate(body, 4000) },
+  });
+}
+
+export function registerMcpCommands(client: PluginClientContext): () => void {
+  const removers = [
+    client.addSlashCommand({
+      name: "mcp",
+      description: "Probe servers, check health, or run an MCP tool",
+      argumentHint: "[probe|health [server]|run server tool [json-args]]",
+      context: "agent",
+      async onSubmit(ctx) {
+        const { args, agent, paseo, rpc } = ctx;
+        const agentId = agent.id;
+        const [sub, ...rest] = args.trim().split(/\s+/);
+        try {
+          if (!sub || sub === "probe") {
+            const res = await rpc(listMcp, { agentId });
+            await appendSlashResult(
+              ctx,
+              "MCP probe",
+              `${res.servers.length} server(s) via ${res.provider}: ${res.servers.map((s) => s.name).join(", ") || "none"}`,
+            );
+            return;
+          }
+          if (sub === "health") {
+            const filter = rest[0]?.toLowerCase();
+            const res = await rpc(checkMcpHealth, { agentId });
+            const rows = filter
+              ? res.results.filter((r) => r.name.toLowerCase().includes(filter))
+              : res.results;
+            const counts = {
+              healthy: rows.filter((r) => r.status === "healthy").length,
+              degraded: rows.filter((r) => r.status === "degraded").length,
+              down: rows.filter((r) => r.status === "down").length,
+              total: rows.length,
+            };
+            await paseo.agents.ref(agentId).timeline.append({
+              type: "plugin",
+              id: "mcp-health",
+              kind: "mcp-health-digest",
+              version: 1,
+              data: buildHealthDigest(counts),
+            });
+            return;
+          }
+          if (sub === "run") {
+            const [serverRef, toolName, ...argParts] = rest;
+            const list = await rpc(listMcp, { agentId });
+            const server = list.servers.find((s) => s.id === serverRef || s.name === serverRef);
+            if (!server || !toolName) {
+              await appendSlashResult(ctx, "MCP run", "Usage: /mcp run <server> <tool> [json-args]");
+              return;
+            }
+            let parsed: Record<string, unknown> = {};
+            if (argParts.length > 0) {
+              try {
+                parsed = JSON.parse(argParts.join(" ")) as Record<string, unknown>;
+              } catch {
+                await appendSlashResult(ctx, "MCP run", "Arguments must be a JSON object.");
+                return;
+              }
+            }
+            const out = await rpc(callMcpTool, {
+              agentId,
+              serverId: server.id,
+              toolName,
+              arguments: parsed,
+            });
+            const text = out.content.map((c) => String((c as { text?: unknown }).text ?? JSON.stringify(c))).join("\n\n");
+            await appendSlashResult(ctx, `MCP run ${toolName}`, out.isError ? `Error:\n${text}` : text || "(empty result)");
+            return;
+          }
+          await appendSlashResult(ctx, "MCP", "Usage: /mcp [probe|health [server]|run server tool [json-args]]");
+        } catch (e) {
+          await appendSlashResult(ctx, "MCP error", e instanceof Error ? e.message : String(e));
+        }
+      },
+    }),
+    client.addCommandCenterItem({
+      id: "reprobe-mcp",
+      title: "Re-probe MCP servers",
+      icon: "Plug",
+      keywords: ["mcp", "refresh", "health"],
+      context: "agent",
+      async onSelect({ agent, rpc }) {
+        await rpc(listMcp, { agentId: agent.id });
+      },
+    }),
+  ];
+  return () => {
+    removers.forEach((remove) => remove());
+  };
+}

package/client/mcp-query.tsx

@@ -0,0 +1,39 @@
+import { REFRESH_INTERVALS, useRpcQuery, type RefreshRate } from "paseo-plugin-helper/client";
+import { checkMcpHealth, listMcp } from "../shared/mcp";
+
+export function useMcpQuery(agentId: string) {
+  return useRpcQuery(listMcp, { agentId }, {
+    staleTime: 0,
+    gcTime: 5 * 60_000,
+    refetchOnMount: "always",
+    refetchOnWindowFocus: false,
+    enabled: Boolean(agentId),
+  });
+}
+
+export function useMcpHealthQuery(
+  agentId: string,
+  serverId: string | undefined,
+  opts: { isOpen?: boolean; rate?: RefreshRate } = {},
+) {
+  const { isOpen = true, rate = "30s" } = opts;
+  const interval = !isOpen ? false : (REFRESH_INTERVALS[rate] ?? false);
+  return useRpcQuery(checkMcpHealth, { agentId, serverId }, {
+    staleTime: 0,
+    gcTime: 5 * 60_000,
+    refetchOnMount: "always",
+    refetchOnWindowFocus: false,
+    refetchInterval: interval,
+    enabled: isOpen && Boolean(agentId),
+  });
+}
+
+export function countServers(data: { servers: Array<unknown>; paseoTools: Array<unknown> } | undefined): number {
+  if (!data) return 0;
+  return data.servers.length + data.paseoTools.length;
+}
+
+export function countMcpOnly(data: { servers: Array<unknown> } | undefined): number {
+  if (!data) return 0;
+  return data.servers.length;
+}