surgent 0.7.0-alpha.0

package/src/mcp-client/command.ts

@@ -0,0 +1,257 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+import {
+  loadMcpConfigSet,
+  normalizeServerConfig,
+  readConfigFile,
+  updateServerConfig,
+} from "./storage.js";
+import type { McpServer, McpTransport, ResolvedMcpServer } from "./types.js";
+import { ExtendedSelectList, type SelectEntry } from "../ui/components/extended-select-list.js";
+import { ScopedInput } from "../ui/components/scoped-input.js";
+import { Form } from "../ui/components/form.js";
+import { McpClientManager } from "./client.js";
+import { parseEditConfigValues } from "./validation.js";
+import { getEditFields, saveEditedServer } from "./helpers.js";
+
+export async function mcpCommandHandler(_args: string, ctx: ExtensionCommandContext) {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("/mcp requires an interactive UI.", "error");
+    return;
+  }
+
+  while (true) {
+    const action = await showMcpOptions(ctx);
+    if (!action) return;
+
+    if (action.addMcp) {
+      await handleSaveFlow(ctx);
+      continue;
+    }
+
+    if (action.selectedServer) {
+      await handleEditFlow(ctx, action.selectedServer);
+    }
+  }
+}
+
+async function showMcpOptions(
+  ctx: ExtensionCommandContext,
+): Promise<{ addMcp: boolean; selectedServer?: ResolvedMcpServer } | null> {
+  const configuredServers = await loadMcpConfigSet(ctx.cwd);
+  const items = configuredServers.map((server) => ({
+    value: server.name,
+    label: `${server.name} [${server.scope}]`,
+    description: server.enabled ? "enabled" : "disabled",
+    data: server,
+  }));
+
+  return ctx.ui.custom<{ addMcp: boolean; selectedServer?: ResolvedMcpServer } | null>(
+    (tui, theme, _keybindings, done) => {
+      let isPending = false;
+      const selectList = new ExtendedSelectList<ResolvedMcpServer>(theme, {
+        title: "MCP servers",
+        addLabel: "Add MCP server",
+        items,
+        maxVisibleRows: 12,
+      });
+
+      const refresh = (pending = false) => {
+        isPending = pending;
+        selectList.invalidate();
+        tui.requestRender();
+      };
+
+      const handleServer = (item: SelectEntry<ResolvedMcpServer>, isDelete: boolean) => {
+        if (!item.data || isPending) return;
+        isPending = true;
+
+        if (isDelete) {
+          deleteMcpServer(ctx, item).finally(refresh);
+        } else {
+          toggleMcpServer(ctx, item, refresh).finally(refresh);
+        }
+      };
+
+      selectList.onAdd = () => done({ addMcp: true });
+      selectList.onCancel = () => done(null);
+      selectList.onSelect = (item) => done({ addMcp: false, selectedServer: item.data });
+      selectList.onDelete = (item) => handleServer(item, true);
+      selectList.extendKb(Key.tab, (item) => handleServer(item, false), "enable/disable");
+
+      return selectList;
+    },
+  );
+}
+
+async function toggleMcpServer(
+  ctx: ExtensionCommandContext,
+  item: SelectEntry<ResolvedMcpServer>,
+  refresh: (pending: boolean) => void,
+) {
+  const server = item.data;
+  if (!server) return;
+
+  const nextEnabledState = !server.enabled;
+  if (nextEnabledState) {
+    item.description = "checking";
+    const client = new McpClientManager();
+    refresh(true);
+
+    try {
+      await client.listTools({ ...server, enabled: true });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Failed to check MCP server";
+      ctx.ui.notify(errorMessage, "error");
+      item.description = "disabled";
+      return;
+    } finally {
+      await client.disposeAll();
+    }
+  }
+
+  const { name, ...config } = server;
+  const updatedConfig: McpServer = { ...config, enabled: nextEnabledState };
+
+  try {
+    await updateServerConfig(server.scope, ctx.cwd, name, {
+      config: updatedConfig,
+      kind: "upsert",
+    });
+    const updated = { ...server, enabled: nextEnabledState };
+    item.data = updated;
+    item.description = updated.enabled ? "enabled" : "disabled";
+  } catch (error) {
+    item.description = server.enabled ? "enabled" : "disabled";
+    const errorMessage = error instanceof Error ? error.message : "Failed to update MCP server";
+    ctx.ui.notify(errorMessage, "error");
+  }
+}
+
+async function deleteMcpServer(ctx: ExtensionCommandContext, item: SelectEntry<ResolvedMcpServer>) {
+  const server = item.data;
+  if (!server) return;
+
+  try {
+    const result = await updateServerConfig(server.scope, ctx.cwd, server.name, {
+      kind: "delete",
+    });
+    if (!result.updated) {
+      ctx.ui.notify(`MCP server ${server.name} no longer exists in ${result.path}.`, "warning");
+      return;
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Failed to delete MCP server";
+    ctx.ui.notify(errorMessage, "error");
+  }
+}
+
+async function handleEditFlow(ctx: ExtensionCommandContext, server: ResolvedMcpServer) {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("mcp edit requires an interactive UI.", "error");
+    return;
+  }
+
+  await ctx.ui.custom<void>((tui, theme, keybindings, done) => {
+    const editor = new Form<ResolvedMcpServer>(tui, keybindings, theme, {
+      title: `Edit MCP server: ${server.name}`,
+      fields: getEditFields(server),
+      emptyMessage: "No fields available for editing.",
+      parseOnSave: parseEditConfigValues,
+    });
+
+    editor.onCancel = () => done();
+    editor.onSave = async (updatedServer) => {
+      await saveEditedServer(ctx, server, updatedServer);
+      done();
+    };
+    editor.onSaveError = (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Failed to update MCP server: ${message}`, "error");
+    };
+
+    return editor;
+  });
+}
+
+async function handleSaveFlow(ctx: ExtensionCommandContext) {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("mcp save requires an interactive UI.", "error");
+    return;
+  }
+
+  const result = await ctx.ui.custom<{ name: string; scope: string } | null>(
+    (_tui, theme, _kb, done) => {
+      const scopedInput = new ScopedInput(theme, "MCP server name");
+      scopedInput.onSubmit = ({ scope, value: name }) => done({ name, scope });
+      scopedInput.onCancel = () => done(null);
+      return scopedInput;
+    },
+  );
+
+  if (!result) return;
+  const { name, scope } = result;
+  if (scope !== "project" && scope !== "global") {
+    ctx.ui.notify(`Invalid scope: ${scope}`, "error");
+    return;
+  }
+
+  const configuredServers = await readConfigFile(scope, ctx.cwd);
+  const hasExisting = Object.hasOwn(configuredServers, name);
+
+  if (hasExisting) {
+    const confirmed = await ctx.ui.confirm(
+      `Replace ${name} MCP`,
+      `${name} MCP already exists ${scope}ly. Do you want to replace it?`,
+    );
+    if (!confirmed) return;
+  }
+
+  const transportType = await ctx.ui.select("Server type", ["Remote", "Local"]);
+  const transport = transportType === "Remote" ? "http" : "stdio";
+
+  const config = await promptServerConfig(ctx, transport, name, scope, configuredServers[name]);
+  if (!config) return;
+
+  const upsertResult = await updateServerConfig(scope, ctx.cwd, name, {
+    config,
+    kind: "upsert",
+  });
+  ctx.ui.notify(
+    `${upsertResult.updated ? "Updated" : "Saved"} MCP server ${name} ${scope}ly (${upsertResult.path}).`,
+    "info",
+  );
+}
+
+async function promptServerConfig(
+  ctx: ExtensionCommandContext,
+  transport: McpTransport,
+  name: string,
+  scope: "project" | "global",
+  existingConfig?: McpServer,
+): Promise<McpServer | undefined> {
+  const defaults =
+    transport === "http"
+      ? { name, scope, transport, url: "" }
+      : { name, scope, transport, command: "" };
+  const server: ResolvedMcpServer = existingConfig ? { name, scope, ...existingConfig } : defaults;
+
+  return ctx.ui.custom<McpServer | undefined>((tui, theme, keybindings, done) => {
+    const editor = new Form<McpServer>(tui, keybindings, theme, {
+      title: `Configure ${name} MCP server`,
+      fields: getEditFields(server).filter(
+        (field) => !["name", "scope", "transport"].includes(field.key),
+      ),
+      parseOnSave: (values) =>
+        normalizeServerConfig(name, parseEditConfigValues({ ...values, name, scope, transport })),
+    });
+
+    editor.onCancel = () => done(undefined);
+    editor.onSave = (serverConfig) => done(serverConfig);
+    editor.onSaveError = (error) => {
+      ctx.ui.notify(error instanceof Error ? error.message : "Invalid MCP server config", "error");
+    };
+
+    return editor;
+  });
+}

package/src/mcp-client/helpers.ts

@@ -0,0 +1,153 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { normalizeServerConfig, readConfigFile, updateServerConfig } from "./storage.js";
+import type { ResolvedMcpServer } from "./types.js";
+import type { Field } from "../ui/components/form-field.js";
+
+export async function saveEditedServer(
+  ctx: ExtensionCommandContext,
+  previous: ResolvedMcpServer,
+  updated: ResolvedMcpServer,
+) {
+  if (
+    (updated.scope !== previous.scope || updated.name !== previous.name) &&
+    Object.hasOwn(await readConfigFile(updated.scope, ctx.cwd), updated.name)
+  ) {
+    throw new Error(`MCP server ${updated.name} already exists in ${updated.scope} scope.`);
+  }
+
+  const updatedConfig = normalizeServerConfig(updated.name, updated);
+
+  await updateServerConfig(updated.scope, ctx.cwd, updated.name, {
+    config: updatedConfig,
+    kind: "upsert",
+  });
+
+  if (updated.scope !== previous.scope || updated.name !== previous.name) {
+    await updateServerConfig(previous.scope, ctx.cwd, previous.name, { kind: "delete" });
+  }
+
+  ctx.ui.notify(`Updated MCP server ${previous.name}.`, "info");
+}
+
+export function getEditFields(server: ResolvedMcpServer): Field<string | number | boolean>[] {
+  const base: Field<string | number | boolean>[] = [
+    {
+      key: "name",
+      label: "name",
+      labelWidth: 18,
+      mode: {
+        type: "input",
+        placeholder: "MCP server name",
+        text: server.name,
+      },
+    },
+    {
+      key: "scope",
+      label: "scope",
+      labelWidth: 18,
+      mode: {
+        type: "toggle",
+        values: ["project", "global"],
+        initialIndex: server.scope === "project" ? 0 : 1,
+      },
+    },
+    {
+      key: "transport",
+      label: "transport",
+      labelWidth: 18,
+      mode: {
+        type: "toggle",
+        values: ["stdio", "http"],
+        initialIndex: server.transport === "stdio" ? 0 : 1,
+      },
+    },
+    {
+      key: "enabled",
+      label: "enabled",
+      labelWidth: 18,
+      mode: {
+        type: "toggle",
+        values: ["true", "false"],
+        initialIndex: server.enabled ? 0 : 1,
+      },
+    },
+    {
+      key: "description",
+      label: "description",
+      labelWidth: 18,
+      mode: {
+        type: "input",
+        placeholder: "Optional description",
+        text: server.description ?? "",
+      },
+    },
+  ];
+
+  if (server.transport === "stdio") {
+    return base.concat([
+      {
+        key: "command",
+        label: "command",
+        labelWidth: 18,
+        mode: {
+          type: "input",
+          placeholder: "Required when transport=stdio",
+          text: server.command,
+        },
+      },
+      {
+        key: "args",
+        label: "args",
+        labelWidth: 18,
+        mode: {
+          type: "input",
+          placeholder: "Optional JSON string array",
+          text: server.args ? JSON.stringify(server.args) : "",
+        },
+      },
+      {
+        key: "cwd",
+        label: "cwd",
+        labelWidth: 18,
+        mode: {
+          type: "input",
+          placeholder: "Optional working directory",
+          text: server.cwd ?? "",
+        },
+      },
+      {
+        key: "env",
+        label: "env",
+        labelWidth: 18,
+        mode: {
+          type: "input",
+          placeholder: "Optional JSON object of env vars",
+          text: server.env ? JSON.stringify(server.env) : "",
+        },
+      },
+    ]);
+  }
+
+  return base.concat([
+    {
+      key: "url",
+      label: "url",
+      labelWidth: 18,
+      mode: {
+        type: "input",
+        placeholder: "Required when transport=http",
+        text: server.url,
+      },
+    },
+    {
+      key: "headers",
+      label: "headers",
+      labelWidth: 18,
+      mode: {
+        type: "input",
+        placeholder: "Optional JSON object of headers",
+        text: server.headers ? JSON.stringify(server.headers) : "",
+      },
+    },
+  ]);
+}

package/src/mcp-client/index.ts

@@ -0,0 +1,21 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { mcpCommandHandler } from "./command.js";
+import { McpClientManager } from "./client.js";
+import { createMcpCallTool } from "./call-tool.js";
+import { createMcpListToolsTool } from "./list-tools.js";
+
+export default function mcpClientExtension(pi: ExtensionAPI) {
+  const clientManager = new McpClientManager();
+
+  pi.registerCommand("mcp", {
+    description: "Manage MCP servers: add new server and toggle enabled state",
+    handler: mcpCommandHandler,
+  });
+
+  pi.registerTool(createMcpCallTool(clientManager));
+  pi.registerTool(createMcpListToolsTool(clientManager));
+
+  pi.on("session_shutdown", async () => {
+    await clientManager.disposeAll();
+  });
+}

package/src/mcp-client/list-tools.ts

@@ -0,0 +1,84 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { resolveServerConfig } from "./storage.js";
+import { McpClientManager } from "./client.js";
+import { renderCallText } from "../utils.js";
+
+export function createMcpListToolsTool(clientManager: McpClientManager) {
+  return defineTool({
+    name: "list_mcp_tools",
+    label: "MCP List Tools",
+    description: "List available tools from one or more configured MCP servers.",
+    promptSnippet: "List available tools from one or more MCP servers with optional regex filter.",
+    promptGuidelines: [
+      "Use list_mcp_tools to discover available tool names before calling call_mcp_tool.",
+      "Provide searchRegex to filter tools relevant to the task and avoid bloating context, especially for large MCP servers.",
+    ],
+    parameters: Type.Object({
+      servers: Type.Array(Type.String({ description: "Configured server name" }), {
+        description: "Server names to query",
+      }),
+      searchRegex: Type.Optional(
+        Type.String({ description: "Regex pattern to filter tool names or descriptions" }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (signal?.aborted) {
+        throw new Error("list_mcp_tools was cancelled.");
+      }
+
+      const filter = params.searchRegex ? new RegExp(params.searchRegex, "i") : null;
+      const sections: string[] = [];
+
+      for (const serverName of params.servers) {
+        const serverConfig = await resolveServerConfig(ctx.cwd, serverName.trim());
+
+        if (!serverConfig) {
+          sections.push(`### ${serverName}\nError: Unknown MCP server. Configure it with /mcp.`);
+          continue;
+        }
+        if (serverConfig.enabled === false) {
+          sections.push(`### ${serverName}\nError: MCP server is disabled.`);
+          continue;
+        }
+        if (signal?.aborted) {
+          throw new Error("list_mcp_tools was cancelled.");
+        }
+
+        const toolsResult = await clientManager.listTools(serverConfig);
+        const matched = filter
+          ? toolsResult.tools.filter(
+              (tool) => filter.test(tool.name) || filter.test(tool.description ?? ""),
+            )
+          : toolsResult.tools;
+
+        if (matched.length === 0) {
+          sections.push(
+            `### ${serverName}\n${filter ? "No tools match the filter." : "No tools available."}`,
+          );
+          continue;
+        }
+
+        const lines = matched.map((tool) => {
+          const description = tool.description ? `: ${tool.description}` : "";
+          const inputSchema = JSON.stringify(tool.inputSchema, null, 2);
+          return `- **${tool.name}**${description}\nInput schema:\n\`\`\`json\n${inputSchema}\n\`\`\``;
+        });
+        sections.push(`### ${serverName}\n${lines.join("\n\n")}`);
+      }
+
+      return {
+        content: [{ type: "text", text: sections.join("\n\n") }],
+        details: { servers: params.servers, filter: params.searchRegex ?? null },
+      };
+    },
+    renderCall(args, theme, { isPartial }) {
+      const serverList = Array.isArray(args.servers) ? args.servers.join(", ") : "";
+      const filterPart = args.searchRegex ? theme.fg("dim", `/${args.searchRegex}/`) : "";
+      return renderCallText(
+        `${theme.fg("toolTitle", "list_mcp_tools")} ${theme.fg("accent", serverList)} ${filterPart}`,
+        isPartial,
+      );
+    },
+  });
+}

package/src/mcp-client/storage.ts

@@ -0,0 +1,190 @@
+import { writeFile } from "node:fs/promises";
+import { getPiPath, readJson } from "../utils.js";
+import type { HttpMcpServer, McpServer, ResolvedMcpServer, StdioMcpServer } from "./types.js";
+
+type Action = { kind: "delete" } | { kind: "upsert"; config: McpServer };
+
+export async function updateServerConfig(
+  scope: "project" | "global",
+  cwd: string,
+  name: string,
+  action: Action,
+): Promise<{ path: string; updated: boolean }> {
+  const path = getPiPath("mcp", scope === "project" ? cwd : scope);
+  const mcpServers = await readConfigFile(scope, cwd);
+  const updated = Object.hasOwn(mcpServers, name);
+
+  if (action.kind === "upsert") {
+    mcpServers[name] = action.config;
+  } else {
+    delete mcpServers[name];
+  }
+  await writeFile(path, `${JSON.stringify(mcpServers, null, 2)}\n`, "utf8");
+
+  return { path, updated };
+}
+
+export async function loadMcpConfigSet(cwd: string): Promise<ResolvedMcpServer[]> {
+  const merged = new Map<string, ResolvedMcpServer>();
+  const [localServers, globalServers] = await Promise.all([
+    readConfigFile("project", cwd),
+    readConfigFile("global", cwd),
+  ]);
+
+  for (const [name, serverConfig] of Object.entries(localServers)) {
+    merged.set(name, { ...serverConfig, name, scope: "project" });
+  }
+  for (const [name, serverConfig] of Object.entries(globalServers)) {
+    merged.set(name, { ...serverConfig, name, scope: "global" });
+  }
+
+  return Array.from(merged.values());
+}
+
+export async function resolveServerConfig(
+  cwd: string,
+  serverName: string,
+): Promise<ResolvedMcpServer | undefined> {
+  const mcpServers = await loadMcpConfigSet(cwd);
+  return mcpServers.find((server) => server.name === serverName);
+}
+
+export async function readConfigFile(
+  scope: "project" | "global",
+  cwd: string,
+): Promise<Record<string, McpServer>> {
+  const path = getPiPath("mcp", scope === "project" ? cwd : scope);
+  return readJson<Record<string, McpServer>>(path, {});
+}
+
+export function normalizeServerConfig(name: string, raw: unknown): McpServer {
+  if (!isPlainObject(raw)) {
+    throw new Error(`Invalid MCP server config for ${name}: expected an object.`);
+  }
+
+  const transport = getTransport(raw, name);
+  const enabled = raw.enabled === undefined ? false : expectBoolean(raw.enabled, name, "enabled");
+  const description =
+    raw.description === undefined ? undefined : expectString(raw.description, name, "description");
+
+  if (transport === "stdio") {
+    const config: StdioMcpServer = {
+      transport: "stdio",
+      command: expectString(raw.command, name, "command"),
+      enabled,
+    };
+
+    if (description) {
+      config.description = description;
+    }
+    if (raw.args !== undefined) {
+      config.args = expectStringArray(raw.args, name, "args");
+    }
+    if (raw.cwd !== undefined) {
+      config.cwd = expectString(raw.cwd, name, "cwd");
+    }
+    if (raw.env !== undefined) {
+      config.env = expectStringRecord(raw.env, name, "env");
+    }
+
+    return config;
+  }
+
+  if (transport === "http") {
+    const config: HttpMcpServer = {
+      transport: "http",
+      url: expectString(raw.url, name, "url"),
+      enabled,
+    };
+
+    if (description) {
+      config.description = description;
+    }
+    if (raw.headers !== undefined) {
+      config.headers = expectStringRecord(raw.headers, name, "headers");
+    }
+
+    return config;
+  }
+
+  throw new Error(`Invalid MCP server config for ${name}: transport must be "stdio" or "http".`);
+}
+
+function getTransport(raw: Record<string, unknown>, serverName: string): "stdio" | "http" {
+  const declared = raw.transport ?? raw.type;
+
+  if (declared === "stdio") {
+    return "stdio";
+  }
+  if (declared === "http" || declared === "https") {
+    return "http";
+  }
+  if (declared !== undefined) {
+    throw new Error(
+      `Invalid MCP server config for ${serverName}: transport/type must be "stdio", "http", or "https".`,
+    );
+  }
+  if (typeof raw.command === "string") {
+    return "stdio";
+  }
+  if (typeof raw.url === "string") {
+    return "http";
+  }
+
+  throw new Error(
+    `Invalid MCP server config for ${serverName}: include either command for stdio or url for http, or set transport explicitly.`,
+  );
+}
+
+function expectBoolean(value: unknown, serverName: string, field: string): boolean {
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid MCP server config for ${serverName}: ${field} must be a boolean.`);
+  }
+  return value;
+}
+
+function expectString(value: unknown, serverName: string, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(
+      `Invalid MCP server config for ${serverName}: ${field} must be a non-empty string.`,
+    );
+  }
+  return value.trim();
+}
+
+function expectStringArray(value: unknown, serverName: string, field: string): string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(
+      `Invalid MCP server config for ${serverName}: ${field} must be an array of strings.`,
+    );
+  }
+  return value;
+}
+
+function expectStringRecord(
+  value: unknown,
+  serverName: string,
+  field: string,
+): Record<string, string> {
+  if (!isPlainObject(value)) {
+    throw new Error(
+      `Invalid MCP server config for ${serverName}: ${field} must be an object of string values.`,
+    );
+  }
+
+  const record: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== "string") {
+      throw new Error(
+        `Invalid MCP server config for ${serverName}: ${field}.${key} must be a string.`,
+      );
+    }
+    record[key] = item;
+  }
+
+  return record;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}