@bastani/atomic 0.7.17-1 → 0.8.0-0

package/dist/builtin/mcp/tool-metadata.ts

@@ -0,0 +1,152 @@
+import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type { McpExtensionState } from "./state.ts";
+import type { ToolMetadata, McpTool, McpResource, ServerEntry } from "./types.ts";
+import { formatToolName, isToolExcluded } from "./types.ts";
+import { resourceNameToToolName } from "./resource-tools.ts";
+import { extractToolUiStreamMode } from "./utils.ts";
+
+export function buildToolMetadata(
+  tools: McpTool[],
+  resources: McpResource[],
+  definition: ServerEntry,
+  serverName: string,
+  prefix: "server" | "none" | "short"
+): { metadata: ToolMetadata[]; failedTools: string[] } {
+  const metadata: ToolMetadata[] = [];
+  const failedTools: string[] = [];
+
+  for (const tool of tools) {
+    if (!tool?.name) {
+      failedTools.push("(unnamed)");
+      continue;
+    }
+    if (isToolExcluded(tool.name, serverName, prefix, definition.excludeTools)) {
+      continue;
+    }
+
+    let uiResourceUri: string | undefined;
+    try {
+      uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
+    } catch {
+      failedTools.push(tool.name);
+    }
+    metadata.push({
+      name: formatToolName(tool.name, serverName, prefix),
+      originalName: tool.name,
+      description: tool.description ?? "",
+      inputSchema: tool.inputSchema,
+      uiResourceUri,
+      uiStreamMode: extractToolUiStreamMode(tool._meta),
+    });
+  }
+
+  if (definition.exposeResources !== false) {
+    for (const resource of resources) {
+      const baseName = `get_${resourceNameToToolName(resource.name)}`;
+      if (isToolExcluded(baseName, serverName, prefix, definition.excludeTools)) {
+        continue;
+      }
+
+      metadata.push({
+        name: formatToolName(baseName, serverName, prefix),
+        originalName: baseName,
+        description: resource.description ?? `Read resource: ${resource.uri}`,
+        resourceUri: resource.uri,
+      });
+    }
+  }
+
+  return { metadata, failedTools };
+}
+
+export function getToolNames(state: McpExtensionState, serverName: string): string[] {
+  return state.toolMetadata.get(serverName)?.map(m => m.name) ?? [];
+}
+
+export function totalToolCount(state: McpExtensionState): number {
+  let count = 0;
+  for (const metadata of state.toolMetadata.values()) {
+    count += metadata.length;
+  }
+  return count;
+}
+
+export function findToolByName(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | undefined {
+  if (!metadata) return undefined;
+  const exact = metadata.find(m => m.name === toolName);
+  if (exact) return exact;
+  const normalized = toolName.replace(/-/g, "_");
+  return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
+}
+
+export function formatSchema(schema: unknown, indent = "  "): string {
+  if (!schema || typeof schema !== "object") {
+    return `${indent}(no schema)`;
+  }
+
+  const s = schema as Record<string, unknown>;
+
+  if (s.type === "object" && s.properties && typeof s.properties === "object") {
+    const props = s.properties as Record<string, unknown>;
+    const required = Array.isArray(s.required) ? s.required as string[] : [];
+
+    if (Object.keys(props).length === 0) {
+      return `${indent}(no parameters)`;
+    }
+
+    const lines: string[] = [];
+    for (const [name, propSchema] of Object.entries(props)) {
+      const isRequired = required.includes(name);
+      const propLine = formatProperty(name, propSchema, isRequired, indent);
+      lines.push(propLine);
+    }
+    return lines.join("\n");
+  }
+
+  if (s.type) {
+    return `${indent}(${s.type})`;
+  }
+
+  return `${indent}(complex schema)`;
+}
+
+function formatProperty(name: string, schema: unknown, required: boolean, indent: string): string {
+  if (!schema || typeof schema !== "object") {
+    return `${indent}${name}${required ? " *required*" : ""}`;
+  }
+
+  const s = schema as Record<string, unknown>;
+  const parts: string[] = [];
+
+  let typeStr = "";
+  if (s.type) {
+    if (Array.isArray(s.type)) {
+      typeStr = s.type.join(" | ");
+    } else {
+      typeStr = String(s.type);
+    }
+  } else if (s.enum) {
+    typeStr = "enum";
+  } else if (s.anyOf || s.oneOf) {
+    typeStr = "union";
+  }
+
+  if (Array.isArray(s.enum)) {
+    const enumVals = s.enum.map(v => JSON.stringify(v)).join(", ");
+    typeStr = `enum: ${enumVals}`;
+  }
+
+  parts.push(`${indent}${name}`);
+  if (typeStr) parts.push(`(${typeStr})`);
+  if (required) parts.push("*required*");
+
+  if (s.description && typeof s.description === "string") {
+    parts.push(`- ${s.description}`);
+  }
+
+  if (s.default !== undefined) {
+    parts.push(`[default: ${JSON.stringify(s.default)}]`);
+  }
+
+  return parts.join(" ");
+}

package/dist/builtin/mcp/tool-registrar.ts

@@ -0,0 +1,46 @@
+// tool-registrar.ts - MCP content transformation
+// NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
+// This keeps the LLM context small (1 tool instead of 100s).
+
+import type { McpContent, ContentBlock } from "./types.ts";
+
+/**
+ * Transform MCP content types to Pi content blocks.
+ */
+export function transformMcpContent(content: McpContent[]): ContentBlock[] {
+  return content.map(c => {
+    if (c.type === "text") {
+      return { type: "text" as const, text: c.text ?? "" };
+    }
+    if (c.type === "image") {
+      return {
+        type: "image" as const,
+        data: c.data ?? "",
+        mimeType: c.mimeType ?? "image/png",
+      };
+    }
+    if (c.type === "resource") {
+      const resourceUri = c.resource?.uri ?? "(no URI)";
+      const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
+      return {
+        type: "text" as const,
+        text: `[Resource: ${resourceUri}]\n${resourceContent}`,
+      };
+    }
+    if (c.type === "resource_link") {
+      const linkName = c.name ?? c.uri ?? "unknown";
+      const linkUri = c.uri ?? "(no URI)";
+      return {
+        type: "text" as const,
+        text: `[Resource Link: ${linkName}]\nURI: ${linkUri}`,
+      };
+    }
+    if (c.type === "audio") {
+      return {
+        type: "text" as const,
+        text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
+      };
+    }
+    return { type: "text" as const, text: JSON.stringify(c) };
+  });
+}

package/dist/builtin/mcp/tool-result-renderer.ts

@@ -0,0 +1,65 @@
+import type { AgentToolResult, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+type McpToolResultDetails = Record<string, unknown> & { error?: unknown };
+type McpToolContentBlock = AgentToolResult<McpToolResultDetails>["content"][number];
+
+interface RenderTheme {
+  fg: (name: string, text: string) => string;
+}
+
+interface McpToolRenderContext {
+  isError: boolean;
+}
+
+export interface McpToolResultDisplay {
+  lines: string[];
+  truncated: boolean;
+}
+
+function blockToLines(block: McpToolContentBlock): string[] {
+  if (block.type === "text") {
+    return block.text.split("\n");
+  }
+  return [`[image: ${block.mimeType}]`];
+}
+
+export function formatMcpToolResultLines(
+  result: Pick<AgentToolResult<McpToolResultDetails>, "content">,
+  expanded: boolean,
+  maxCollapsedLines = 3,
+): McpToolResultDisplay {
+  const allLines = result.content.flatMap(blockToLines);
+  const lines = allLines.length > 0 ? allLines : ["(empty result)"];
+
+  if (expanded || lines.length <= maxCollapsedLines) {
+    return { lines, truncated: false };
+  }
+
+  return {
+    lines: [...lines.slice(0, maxCollapsedLines), "…"],
+    truncated: true,
+  };
+}
+
+export function renderMcpToolResult(
+  result: AgentToolResult<McpToolResultDetails>,
+  options: ToolRenderResultOptions,
+  theme: RenderTheme,
+  context?: McpToolRenderContext,
+) {
+  if (options.isPartial) {
+    return new Text(theme.fg("warning", "Running MCP tool..."), 0, 0);
+  }
+
+  const hasErrorDetails = Boolean(result.details.error);
+  const display = formatMcpToolResultLines(result, options.expanded || context?.isError === true || hasErrorDetails);
+  const output = display.lines
+    .map((line) => line === "…" ? theme.fg("muted", line) : theme.fg("toolOutput", line))
+    .join("\n");
+  const hint = display.truncated && !options.expanded
+    ? `\n${theme.fg("muted", "(Ctrl+O to expand)")}`
+    : "";
+
+  return new Text(`${output}${hint}`, 0, 0);
+}

package/dist/builtin/mcp/types.ts

@@ -0,0 +1,441 @@
+// types.ts - Core type definitions
+import type { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { TextContent, ImageContent } from "@earendil-works/pi-ai";
+import type { UiStreamMode } from "./ui-stream-types.ts";
+
+// Transport type (stdio + HTTP)
+export type Transport = 
+  | StdioClientTransport 
+  | SSEClientTransport 
+  | StreamableHTTPClientTransport;
+
+// Import sources for config
+export type ImportKind = 
+  | "cursor" 
+  | "claude-code" 
+  | "claude-desktop" 
+  | "codex" 
+  | "windsurf" 
+  | "vscode";
+
+// Tool definition from MCP server
+export interface McpTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown; // JSON Schema
+  _meta?: Record<string, unknown>;
+}
+
+// Resource definition from MCP server
+export interface McpResource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+  _meta?: Record<string, unknown>;
+}
+
+export interface UiResourceMeta {
+  csp?: UiResourceCsp;
+  permissions?: UiResourcePermissions;
+  domain?: string;
+  prefersBorder?: boolean;
+}
+
+export interface UiResourceContent {
+  uri: string;
+  html: string;
+  mimeType?: string;
+  meta: UiResourceMeta;
+}
+
+export interface UiProxyRequestBody<TParams> {
+  token: string;
+  params: TParams;
+}
+
+export interface UiProxyResult<T = Record<string, unknown>> {
+  ok: boolean;
+  result?: T;
+  error?: string;
+}
+
+export interface UiResourceCsp {
+  connectDomains?: string[];
+  scriptDomains?: string[];
+  styleDomains?: string[];
+  fontDomains?: string[];
+  imgDomains?: string[];
+  mediaDomains?: string[];
+  frameDomains?: string[];
+  workerDomains?: string[];
+  baseUriDomains?: string[];
+}
+
+export interface UiResourcePermissions {
+  camera?: {};
+  microphone?: {};
+  geolocation?: {};
+  clipboardWrite?: {};
+}
+
+export interface UiToolInfo {
+  id?: string | number;
+  tool: {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+  };
+}
+
+export interface UiHostContext {
+  toolInfo?: UiToolInfo;
+  theme?: "light" | "dark";
+  styles?: Record<string, unknown>;
+  displayMode?: UiDisplayMode;
+  availableDisplayModes?: UiDisplayMode[];
+  containerDimensions?: {
+    width?: number;
+    maxWidth?: number;
+    height?: number;
+    maxHeight?: number;
+  };
+  [key: string]: unknown;
+}
+
+export type UiDisplayMode = "inline" | "fullscreen" | "pip";
+
+// Re-export stream types from the shared lightweight module.
+// This allows the example package to import stream schemas without pulling the full types.ts dependency graph.
+export {
+  UI_STREAM_HOST_CONTEXT_KEY,
+  UI_STREAM_REQUEST_META_KEY,
+  UI_STREAM_RESULT_PATCH_METHOD,
+  SERVER_STREAM_RESULT_PATCH_METHOD,
+  UI_STREAM_STRUCTURED_CONTENT_KEY,
+  uiStreamModeSchema,
+  visualizationStreamPhaseSchema,
+  visualizationStreamFrameTypeSchema,
+  visualizationStreamStatusSchema,
+  uiStreamHostContextSchema,
+  visualizationStreamEnvelopeSchema,
+  uiStreamCallToolResultSchema,
+  uiStreamResultPatchNotificationSchema,
+  serverStreamResultPatchNotificationSchema,
+  getUiStreamHostContext,
+  getVisualizationStreamEnvelope,
+  type UiStreamMode,
+  type VisualizationStreamPhase,
+  type VisualizationStreamFrameType,
+  type VisualizationStreamStatus,
+  type UiStreamHostContext,
+  type VisualizationStreamEnvelope,
+  type UiStreamCallToolResult,
+  type UiStreamResultPatchNotification,
+  type ServerStreamResultPatchNotification,
+  type UiStreamSummary,
+} from "./ui-stream-types.ts";
+
+export interface UiMessageParams {
+  role?: string;
+  content?: unknown[];
+  type?: "prompt" | "notify" | "intent" | "message";
+  message?: string;
+  prompt?: string;
+  intent?: string;
+  params?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Extract prompt text from either legacy MCP UI message shapes or native AppBridge user messages.
+ */
+export function extractUiPromptText(params: UiMessageParams): string | undefined {
+  if (params.type === "prompt" || params.prompt) {
+    const prompt = params.prompt ?? String(params.message ?? "");
+    return prompt || undefined;
+  }
+
+  if (params.role === "user" && Array.isArray(params.content)) {
+    const text = params.content
+      .map((block) => (block && typeof block === "object" && "text" in block ? String((block as { text?: unknown }).text ?? "") : ""))
+      .filter(Boolean)
+      .join("\n\n");
+    return text || undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ * Structured UI handoff recovered from a canonical prompt envelope.
+ */
+export interface UiPromptHandoff {
+  intent: string;
+  params: Record<string, unknown>;
+  raw: string;
+}
+
+/**
+ * Parse a canonical named UI handoff encoded as `intent\n{json}`.
+ */
+export function parseUiPromptHandoff(prompt: string): UiPromptHandoff | undefined {
+  const newlineIndex = prompt.indexOf("\n");
+  if (newlineIndex <= 0) {
+    return undefined;
+  }
+
+  const intent = prompt.slice(0, newlineIndex).trim();
+  const payloadText = prompt.slice(newlineIndex + 1).trim();
+  if (!intent || !payloadText) {
+    return undefined;
+  }
+
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(intent)) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(payloadText);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return undefined;
+    }
+    return {
+      intent,
+      params: parsed as Record<string, unknown>,
+      raw: prompt,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Accumulated messages from a UI session.
+ * Collected during the session and available when it ends.
+ */
+export interface UiSessionMessages {
+  prompts: string[];
+  notifications: string[];
+  intents: Array<{ intent: string; params?: Record<string, unknown> }>;
+}
+
+export interface UiModelContextParams {
+  content?: unknown[];
+  structuredContent?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface UiOpenLinkResult {
+  isError?: boolean;
+  [key: string]: unknown;
+}
+
+export interface UiDisplayModeRequest {
+  mode?: UiDisplayMode;
+}
+
+export interface UiDisplayModeResult {
+  mode: UiDisplayMode;
+  [key: string]: unknown;
+}
+
+// Content types from MCP
+export interface McpContent {
+  type: "text" | "image" | "audio" | "resource" | "resource_link";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  resource?: {
+    uri: string;
+    text?: string;
+    blob?: string;
+  };
+  uri?: string;
+  name?: string;
+  description?: string;
+}
+
+// Pi content block type
+export type ContentBlock = TextContent | ImageContent;
+
+// OAuth configuration (SDK handles auto-discovery and dynamic registration)
+export interface OAuthConfig {
+  /** OAuth grant type (defaults to authorization_code) */
+  grantType?: "authorization_code" | "client_credentials";
+  /** Pre-registered client ID (optional, dynamic registration used if not provided) */
+  clientId?: string;
+  /** Client secret for confidential clients */
+  clientSecret?: string;
+  /** Requested OAuth scopes */
+  scope?: string;
+}
+
+// Server configuration
+export interface ServerEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  // HTTP fields
+  url?: string;
+  headers?: Record<string, string>;
+  /** 
+   * Authentication type:
+   * - 'oauth' - Use OAuth 2.1 (auto-discovers endpoints, supports dynamic client registration)
+   * - 'bearer' - Use static Bearer token
+   * - false - Disable authentication
+   * If not specified and url is present, OAuth will be auto-detected
+   */
+  auth?: "oauth" | "bearer" | false;
+  bearerToken?: string;
+  bearerTokenEnv?: string;
+  /** 
+   * OAuth configuration (optional).
+   * If not provided, the SDK will attempt dynamic client registration.
+   * Set to false to explicitly disable OAuth for this server.
+   */
+  oauth?: OAuthConfig | false;
+  lifecycle?: "keep-alive" | "lazy" | "eager";
+  idleTimeout?: number; // minutes, overrides global setting
+  // Resource handling
+  exposeResources?: boolean;
+  // Direct tool registration
+  directTools?: boolean | string[];
+  // Exclude specific MCP tools/resources by original or prefixed name
+  excludeTools?: string[];
+  // Debug
+  debug?: boolean;  // Show server stderr (default: false)
+}
+
+// Settings
+export interface McpSettings {
+  toolPrefix?: "server" | "none" | "short";
+  idleTimeout?: number; // minutes, default 10, 0 to disable
+  directTools?: boolean;
+  disableProxyTool?: boolean;
+  autoAuth?: boolean;
+  sampling?: boolean;
+  samplingAutoApprove?: boolean;
+  /**
+   * Message returned in tool results when a server needs (re-)authentication.
+   * "${server}" is substituted with the server name. Defaults to a TUI
+   * instruction when unset.
+   */
+  authRequiredMessage?: string;
+}
+
+// Root config
+export interface McpConfig {
+  mcpServers: Record<string, ServerEntry>;
+  imports?: ImportKind[];
+  settings?: McpSettings;
+}
+
+// Alias for clarity
+export type ServerDefinition = ServerEntry;
+
+export interface ToolMetadata {
+  name: string;           // Prefixed tool name (e.g., "xcodebuild_list_sims")
+  originalName: string;   // Original MCP tool name (e.g., "list_sims")
+  description: string;
+  resourceUri?: string;   // For resource tools: the URI to read
+  uiResourceUri?: string; // For app-enabled tools: the UI resource URI
+  inputSchema?: unknown;  // JSON Schema for parameters (stored for describe/errors)
+  uiStreamMode?: UiStreamMode;
+}
+
+export interface DirectToolSpec {
+  serverName: string;
+  originalName: string;
+  prefixedName: string;
+  description: string;
+  inputSchema?: unknown;
+  resourceUri?: string;
+  uiResourceUri?: string;
+  uiStreamMode?: UiStreamMode;
+}
+
+export interface ServerProvenance {
+  path: string;
+  kind: "user" | "project" | "import";
+  importKind?: string;
+}
+
+export interface McpAuthResult {
+  ok: boolean;
+  message?: string;
+}
+
+export interface McpPanelCallbacks {
+  reconnect: (serverName: string) => Promise<boolean>;
+  canAuthenticate: (serverName: string) => boolean;
+  authenticate: (serverName: string) => Promise<McpAuthResult>;
+  getConnectionStatus: (serverName: string) => "connected" | "idle" | "failed" | "needs-auth";
+  refreshCacheAfterReconnect: (serverName: string) => import("./metadata-cache.ts").ServerCacheEntry | null;
+}
+
+export interface McpPanelResult {
+  changes: Map<string, true | string[] | false>;
+  cancelled: boolean;
+}
+
+/**
+ * Get server prefix based on tool prefix mode.
+ */
+export function getServerPrefix(
+  serverName: string,
+  mode: "server" | "none" | "short"
+): string {
+  if (mode === "none") return "";
+  if (mode === "short") {
+    let short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+    if (!short) short = "mcp";
+    return short;
+  }
+  return serverName.replace(/-/g, "_");
+}
+
+/**
+ * Format a tool name with server prefix.
+ */
+export function formatToolName(
+  toolName: string,
+  serverName: string,
+  prefix: "server" | "none" | "short"
+): string {
+  const p = getServerPrefix(serverName, prefix);
+  return p ? `${p}_${toolName}` : toolName;
+}
+
+function normalizeToolName(value: string): string {
+  return value.replace(/-/g, "_");
+}
+
+export function isToolExcluded(
+  toolName: string,
+  serverName: string,
+  prefix: "server" | "none" | "short",
+  excludeTools?: unknown
+): boolean {
+  if (!Array.isArray(excludeTools) || excludeTools.length === 0) return false;
+
+  const candidates = new Set<string>([
+    normalizeToolName(toolName),
+    normalizeToolName(formatToolName(toolName, serverName, prefix)),
+    normalizeToolName(formatToolName(toolName, serverName, "server")),
+    normalizeToolName(formatToolName(toolName, serverName, "short")),
+  ]);
+
+  for (const excluded of excludeTools) {
+    if (typeof excluded !== "string") continue;
+    if (candidates.has(normalizeToolName(excluded))) {
+      return true;
+    }
+  }
+
+  return false;
+}