waypoi 0.0.0

package/src/mcp/client.ts

@@ -0,0 +1,305 @@
+import { McpServer, McpTool } from "../types";
+
+/**
+ * MCP Client
+ * 
+ * HTTP client for MCP servers using Streamable HTTP transport.
+ * Handles connection lifecycle, tool discovery, and tool execution.
+ */
+
+export interface McpClientOptions {
+  url: string;
+  timeout?: number;
+}
+
+export interface McpJsonRpcRequest {
+  jsonrpc: "2.0";
+  id: number | string;
+  method: string;
+  params?: unknown;
+}
+
+export interface McpJsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+export interface McpToolSchema {
+  name: string;
+  description?: string;
+  inputSchema: {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+export interface McpToolsListResult {
+  tools: McpToolSchema[];
+}
+
+export interface McpToolCallResult {
+  content: Array<{
+    type: "text" | "image" | "resource";
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  }>;
+  isError?: boolean;
+}
+
+export class McpError extends Error {
+  constructor(
+    public code: number,
+    message: string,
+    public data?: unknown
+  ) {
+    super(message);
+    this.name = "McpError";
+  }
+}
+
+export class McpClient {
+  private url: string;
+  private timeout: number;
+  private requestId = 0;
+  private sessionId: string | null = null;
+
+  constructor(options: McpClientOptions) {
+    this.url = options.url;
+    this.timeout = options.timeout ?? 30000;
+  }
+
+  /**
+   * Initialize the MCP connection.
+   */
+  async initialize(): Promise<void> {
+    const response = await this.sendRequest("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {
+        tools: {},
+      },
+      clientInfo: {
+        name: "waypoi",
+        version: "0.2.0",
+      },
+    });
+
+    // Store session ID if provided
+    const initResponse = response as { _meta?: { sessionId?: string } };
+    if (initResponse._meta?.sessionId) {
+      this.sessionId = initResponse._meta.sessionId;
+    }
+
+    // Send initialized notification
+    await this.sendNotification("notifications/initialized");
+  }
+
+  /**
+   * List available tools from the MCP server.
+   */
+  async listTools(): Promise<McpToolSchema[]> {
+    const result = await this.sendRequest("tools/list", {});
+    const toolsResult = result as McpToolsListResult;
+    return toolsResult.tools ?? [];
+  }
+
+  /**
+   * Call a tool on the MCP server.
+   */
+  async callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult> {
+    const result = await this.sendRequest("tools/call", {
+      name,
+      arguments: args,
+    });
+    return result as McpToolCallResult;
+  }
+
+  /**
+   * Close the MCP connection.
+   */
+  async close(): Promise<void> {
+    try {
+      await this.sendNotification("notifications/cancelled", {
+        requestId: "session",
+        reason: "Client closing",
+      });
+    } catch {
+      // Ignore errors during close
+    }
+    this.sessionId = null;
+  }
+
+  /**
+   * Send a JSON-RPC request and wait for response.
+   */
+  private async sendRequest(method: string, params?: unknown): Promise<unknown> {
+    const id = ++this.requestId;
+    const request: McpJsonRpcRequest = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      // MCP Streamable HTTP spec requires accepting both JSON and SSE
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+      };
+
+      if (this.sessionId) {
+        headers["Mcp-Session-Id"] = this.sessionId;
+      }
+
+      const response = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(request),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new McpError(
+          -32000,
+          `HTTP error: ${response.status} ${response.statusText}`
+        );
+      }
+
+      // Check for session ID in response headers
+      const newSessionId = response.headers.get("Mcp-Session-Id");
+      if (newSessionId) {
+        this.sessionId = newSessionId;
+      }
+
+      // Handle both JSON and SSE responses per MCP Streamable HTTP spec
+      const contentType = response.headers.get("Content-Type") ?? "";
+      
+      if (contentType.includes("text/event-stream")) {
+        // Parse SSE response - collect events and find our response
+        return await this.parseSSEResponse(response, id);
+      }
+
+      const jsonResponse = await response.json() as McpJsonRpcResponse;
+
+      if (jsonResponse.error) {
+        throw new McpError(
+          jsonResponse.error.code,
+          jsonResponse.error.message,
+          jsonResponse.error.data
+        );
+      }
+
+      return jsonResponse.result;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Parse Server-Sent Events response to extract JSON-RPC response.
+   * MCP Streamable HTTP can return SSE for streaming responses.
+   */
+  private async parseSSEResponse(response: Response, expectedId: number | string): Promise<unknown> {
+    const text = await response.text();
+    const lines = text.split("\n");
+    
+    let currentData = "";
+    
+    for (const line of lines) {
+      if (line.startsWith("data:")) {
+        currentData += line.slice(5).trim();
+      } else if (line === "" && currentData) {
+        // End of event, try to parse
+        try {
+          const jsonResponse = JSON.parse(currentData) as McpJsonRpcResponse;
+          
+          // Check if this is the response to our request
+          if (jsonResponse.id === expectedId) {
+            if (jsonResponse.error) {
+              throw new McpError(
+                jsonResponse.error.code,
+                jsonResponse.error.message,
+                jsonResponse.error.data
+              );
+            }
+            return jsonResponse.result;
+          }
+        } catch (e) {
+          if (e instanceof McpError) throw e;
+          // Ignore parsing errors, continue to next event
+        }
+        currentData = "";
+      }
+    }
+    
+    // Try parsing any remaining data
+    if (currentData) {
+      try {
+        const jsonResponse = JSON.parse(currentData) as McpJsonRpcResponse;
+        if (jsonResponse.id === expectedId) {
+          if (jsonResponse.error) {
+            throw new McpError(
+              jsonResponse.error.code,
+              jsonResponse.error.message,
+              jsonResponse.error.data
+            );
+          }
+          return jsonResponse.result;
+        }
+      } catch (e) {
+        if (e instanceof McpError) throw e;
+      }
+    }
+    
+    throw new McpError(-32000, "No response found in SSE stream");
+  }
+
+  /**
+   * Send a JSON-RPC notification (no response expected).
+   */
+  private async sendNotification(method: string, params?: unknown): Promise<void> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.sessionId) {
+      headers["Mcp-Session-Id"] = this.sessionId;
+    }
+
+    const notification = {
+      jsonrpc: "2.0",
+      method,
+      params,
+    };
+
+    await fetch(this.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(notification),
+    });
+  }
+
+  get serverUrl(): string {
+    return this.url;
+  }
+}
+
+/**
+ * Create and initialize an MCP client.
+ */
+export async function createMcpClient(url: string): Promise<McpClient> {
+  const client = new McpClient({ url });
+  await client.initialize();
+  return client;
+}

package/src/mcp/discovery.ts

@@ -0,0 +1,266 @@
+import { McpServer, McpTool } from "../types";
+import { StoragePaths } from "../storage/files";
+import { listMcpServers, updateMcpServerStatus } from "./registry";
+import { McpClient, createMcpClient, McpToolSchema, McpError } from "./client";
+
+/**
+ * MCP Tool Discovery
+ * 
+ * Connects to registered MCP servers and discovers available tools.
+ * Maintains an in-memory cache of tools and their source servers.
+ */
+
+interface DiscoveredTool extends McpTool {
+  serverId: string;
+  serverName: string;
+  serverUrl: string;
+}
+
+// In-memory cache of discovered tools
+const toolsCache: Map<string, DiscoveredTool[]> = new Map();
+
+// Active client connections
+const activeClients: Map<string, McpClient> = new Map();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Built-in server (the waypoi /mcp endpoint itself)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Reserved ID for the built-in waypoi MCP server. */
+export const BUILTIN_SERVER_ID = "builtin";
+
+/** URL of the built-in MCP server (set once after app.listen). */
+let builtinUrl: string | null = null;
+
+/**
+ * Connect to the built-in /mcp endpoint and cache its tools.
+ * Called once in src/index.ts after app.listen().
+ */
+export async function discoverBuiltinTools(
+  paths: StoragePaths,
+  serverUrl: string
+): Promise<DiscoveredTool[]> {
+  builtinUrl = serverUrl;
+  const now = new Date();
+  const server: McpServer = {
+    id: BUILTIN_SERVER_ID,
+    name: "waypoi",
+    url: serverUrl,
+    enabled: true,
+    status: "unknown",
+    createdAt: now,
+    updatedAt: now,
+  };
+  return discoverServerTools(paths, server);
+}
+
+/**
+ * Return virtual server metadata for the built-in server.
+ * Returns null if discoverBuiltinTools hasn't been called yet.
+ */
+export function getBuiltinVirtualServer(): (McpServer & { connected: boolean }) | null {
+  if (!builtinUrl) return null;
+  const now = new Date();
+  const connected = isServerConnected(BUILTIN_SERVER_ID);
+  return {
+    id: BUILTIN_SERVER_ID,
+    name: "waypoi",
+    url: builtinUrl,
+    enabled: true,
+    status: connected ? "connected" : "error",
+    toolCount: getCachedToolsForServer(BUILTIN_SERVER_ID).length,
+    createdAt: now,
+    updatedAt: now,
+    connected,
+  };
+}
+
+/**
+ * Connect to a single MCP server and discover its tools.
+ */
+export async function discoverServerTools(
+  paths: StoragePaths,
+  server: McpServer
+): Promise<DiscoveredTool[]> {
+  if (!server.enabled) {
+    return [];
+  }
+
+  try {
+    // Create client and connect
+    const client = await createMcpClient(server.url);
+    activeClients.set(server.id, client);
+
+    // Discover tools
+    const toolSchemas = await client.listTools();
+    const tools: DiscoveredTool[] = toolSchemas.map((schema) => ({
+      name: schema.name,
+      description: schema.description,
+      inputSchema: schema.inputSchema,
+      serverId: server.id,
+      serverName: server.name,
+      serverUrl: server.url,
+    }));
+
+    // Update server status
+    await updateMcpServerStatus(paths, server.id, "connected", tools.length);
+
+    // Cache tools
+    toolsCache.set(server.id, tools);
+
+    return tools;
+  } catch (error) {
+    const summary = summarizeMcpError(error);
+    console.error(`[waypoi] MCP discovery failed for ${server.name}: ${summary}`);
+    if (process.env.WAYPOI_DEBUG_ERRORS === "1") {
+      console.error(error);
+    }
+    await updateMcpServerStatus(paths, server.id, "error");
+    toolsCache.delete(server.id);
+    return [];
+  }
+}
+
+/**
+ * Discover tools from all enabled MCP servers.
+ */
+export async function discoverAllTools(paths: StoragePaths): Promise<DiscoveredTool[]> {
+  const servers = await listMcpServers(paths);
+  const enabledServers = servers.filter((s) => s.enabled);
+
+  // Discover tools from all servers in parallel
+  const results = await Promise.allSettled(
+    enabledServers.map((server) => discoverServerTools(paths, server))
+  );
+
+  // Collect all successful discoveries
+  const allTools: DiscoveredTool[] = [];
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      allTools.push(...result.value);
+    }
+  }
+
+  return allTools;
+}
+
+export function summarizeMcpError(error: unknown): string {
+  if (error instanceof McpError) {
+    return error.message;
+  }
+
+  const err = error as { message?: string; code?: string; cause?: unknown };
+  if (err?.code) {
+    return err.code;
+  }
+
+  const cause = err?.cause as { code?: string; message?: string } | undefined;
+  if (cause?.code) {
+    return cause.code;
+  }
+
+  const message = err?.message;
+  if (typeof message === "string" && message.trim().length > 0) {
+    return message;
+  }
+
+  return "unknown error";
+}
+
+/**
+ * Get all cached tools (does not re-discover).
+ */
+export function getCachedTools(): DiscoveredTool[] {
+  const allTools: DiscoveredTool[] = [];
+  for (const tools of toolsCache.values()) {
+    allTools.push(...tools);
+  }
+  return allTools;
+}
+
+/**
+ * Get tools for a specific server.
+ */
+export function getCachedToolsForServer(serverId: string): DiscoveredTool[] {
+  return toolsCache.get(serverId) ?? [];
+}
+
+/**
+ * Find a tool by name across all servers.
+ */
+export function findTool(name: string): DiscoveredTool | undefined {
+  for (const tools of toolsCache.values()) {
+    const tool = tools.find((t) => t.name === name);
+    if (tool) return tool;
+  }
+  return undefined;
+}
+
+/**
+ * Execute a tool on its source MCP server.
+ */
+export async function executeTool(
+  toolName: string,
+  args: Record<string, unknown>
+): Promise<{ content: string; isError?: boolean }> {
+  const tool = findTool(toolName);
+  if (!tool) {
+    return { content: `Tool not found: ${toolName}`, isError: true };
+  }
+
+  const client = activeClients.get(tool.serverId);
+  if (!client) {
+    return { content: `Server not connected: ${tool.serverName}`, isError: true };
+  }
+
+  try {
+    const result = await client.callTool(toolName, args);
+
+    // Extract text content from result
+    const textParts = result.content
+      .filter((c) => c.type === "text" && c.text)
+      .map((c) => c.text as string);
+
+    return {
+      content: textParts.join("\n") || "Tool executed successfully (no output)",
+      isError: result.isError,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof McpError 
+      ? error.message 
+      : (error as Error).message;
+    return { content: `Tool execution failed: ${errorMessage}`, isError: true };
+  }
+}
+
+/**
+ * Disconnect from a specific server.
+ */
+export async function disconnectServer(serverId: string): Promise<void> {
+  const client = activeClients.get(serverId);
+  if (client) {
+    await client.close();
+    activeClients.delete(serverId);
+  }
+  toolsCache.delete(serverId);
+}
+
+/**
+ * Disconnect from all servers.
+ */
+export async function disconnectAllServers(): Promise<void> {
+  const closePromises: Promise<void>[] = [];
+  for (const [serverId, client] of activeClients) {
+    closePromises.push(client.close());
+    activeClients.delete(serverId);
+    toolsCache.delete(serverId);
+  }
+  await Promise.allSettled(closePromises);
+}
+
+/**
+ * Check if a server is currently connected.
+ */
+export function isServerConnected(serverId: string): boolean {
+  return activeClients.has(serverId);
+}

package/src/mcp/policy.ts

@@ -0,0 +1,105 @@
+import path from "path";
+
+export type McpTypedError = Error & { type: string };
+
+export interface BinaryOutputPolicyInput {
+  include_data?: boolean;
+}
+
+export interface BinaryOutputPolicyResolved {
+  outputDir: string;
+  includeData: boolean;
+  outputBaseRoot: string;
+}
+
+interface ResolveBinaryOutputPolicyOptions {
+  env?: NodeJS.ProcessEnv;
+  defaultBaseDir?: string;
+}
+
+export function typedError(type: string, message: string): McpTypedError {
+  const error = new Error(message) as McpTypedError;
+  error.type = type;
+  return error;
+}
+
+export function resolveBinaryOutputPolicy(
+  input: BinaryOutputPolicyInput,
+  options: ResolveBinaryOutputPolicyOptions = {}
+): BinaryOutputPolicyResolved {
+  const env = options.env ?? process.env;
+  const defaultBaseDir = options.defaultBaseDir ?? process.cwd();
+  const strict = parseBooleanEnv(env.WAYPOI_MCP_STRICT_OUTPUT_ROOT);
+  const configuredRoot = env.WAYPOI_MCP_OUTPUT_ROOT?.trim();
+
+  if (strict && !configuredRoot) {
+    throw typedError(
+      "invalid_request",
+      "WAYPOI_MCP_STRICT_OUTPUT_ROOT=true requires WAYPOI_MCP_OUTPUT_ROOT to be set."
+    );
+  }
+
+  let baseRoot = defaultBaseDir;
+  if (configuredRoot) {
+    if (!path.isAbsolute(configuredRoot)) {
+      if (strict) {
+        throw typedError(
+          "invalid_request",
+          `WAYPOI_MCP_OUTPUT_ROOT must be an absolute path, got '${configuredRoot}'.`
+        );
+      }
+    } else {
+      baseRoot = path.resolve(configuredRoot);
+    }
+  }
+
+  const configuredSubdir = env.WAYPOI_MCP_OUTPUT_SUBDIR?.trim();
+  if (configuredSubdir && path.isAbsolute(configuredSubdir)) {
+    throw typedError(
+      "invalid_request",
+      `WAYPOI_MCP_OUTPUT_SUBDIR must be relative, got '${configuredSubdir}'.`
+    );
+  }
+  const outputDir = configuredSubdir
+    ? path.resolve(baseRoot, configuredSubdir)
+    : path.join(baseRoot, "generated-images");
+
+  return {
+    outputDir,
+    includeData: input.include_data ?? false,
+    outputBaseRoot: baseRoot,
+  };
+}
+
+function parseBooleanEnv(value: string | undefined): boolean {
+  if (!value) {
+    return false;
+  }
+  return value === "1" || value.toLowerCase() === "true";
+}
+
+export function validateSingleImageInput(input: {
+  image_path?: string;
+  image_url?: string;
+}): void {
+  const hasPath = Boolean(input.image_path);
+  const hasUrl = Boolean(input.image_url);
+  if ((hasPath && hasUrl) || (!hasPath && !hasUrl)) {
+    throw typedError(
+      "invalid_request",
+      "Exactly one image source is required: provide either image_path or image_url."
+    );
+  }
+}
+
+export function validateAtMostOneImageInput(input: {
+  image_path?: string;
+  image_url?: string;
+}): void {
+  if (input.image_path && input.image_url) {
+    throw typedError(
+      "invalid_request",
+      "Provide either image_path or image_url, not both."
+    );
+  }
+}