@inkeep/agents-manage-ui 0.1.0

package/src/lib/utils/graph-error-parser.ts

@@ -0,0 +1,262 @@
+/**
+ * Graph Error Parser Utilities
+ *
+ * Transforms Zod validation errors from graph save operations into user-friendly
+ * error messages with node/edge mapping for visual feedback.
+ */
+
+export interface ValidationErrorDetail {
+  code: string;
+  message: string;
+  path: string[];
+  expected?: string;
+}
+
+export interface ProcessedGraphError {
+  type: 'node' | 'edge' | 'graph';
+  nodeId?: string;
+  edgeId?: string;
+  field: string;
+  message: string;
+  fullPath: string[];
+  originalError: ValidationErrorDetail;
+}
+
+export interface GraphErrorSummary {
+  totalErrors: number;
+  nodeErrors: Record<string, ProcessedGraphError[]>;
+  edgeErrors: Record<string, ProcessedGraphError[]>;
+  graphErrors: ProcessedGraphError[];
+  allErrors: ProcessedGraphError[];
+}
+
+/**
+ * Parse Zod validation errors from the API response into structured format
+ */
+export function parseGraphValidationErrors(apiError: string): GraphErrorSummary {
+  try {
+    const errors = JSON.parse(apiError) as any[];
+    const processedErrors: ProcessedGraphError[] = [];
+
+    for (const error of errors) {
+      if (error.code === 'invalid_union' && error.errors && error.path) {
+        // Handle union type errors (like agent types with multiple validation paths)
+        for (const unionErrorGroup of error.errors) {
+          for (const unionError of unionErrorGroup) {
+            const processedError = processValidationError(unionError, error.path);
+            if (processedError) {
+              processedErrors.push(processedError);
+            }
+          }
+        }
+      } else if (error.path) {
+        // Handle direct validation errors
+        const processedError = processValidationError(error, error.path);
+        if (processedError) {
+          processedErrors.push(processedError);
+        }
+      }
+    }
+
+    return categorizeErrors(processedErrors);
+  } catch {
+    // Fallback for unparseable errors
+    return {
+      totalErrors: 1,
+      nodeErrors: {},
+      edgeErrors: {},
+      graphErrors: [
+        {
+          type: 'graph',
+          field: 'unknown',
+          message: 'An unknown validation error occurred',
+          fullPath: [],
+          originalError: {
+            code: 'unknown',
+            message: apiError,
+            path: [],
+          },
+        },
+      ],
+      allErrors: [],
+    };
+  }
+}
+
+/**
+ * Process a single validation error into our structured format
+ */
+function processValidationError(
+  error: ValidationErrorDetail,
+  basePath: string[]
+): ProcessedGraphError | null {
+  const fullPath = [...basePath, ...error.path];
+
+  // Determine error type and extract IDs
+  let type: 'node' | 'edge' | 'graph' = 'graph';
+  let nodeId: string | undefined;
+  let edgeId: string | undefined;
+  let field: string;
+
+  if (fullPath[0] === 'agents' && fullPath[1]) {
+    type = 'node';
+    nodeId = fullPath[1];
+    field = error.path.join('.') || 'configuration';
+  } else if (fullPath[0] === 'edges' && fullPath[1]) {
+    type = 'edge';
+    edgeId = fullPath[1];
+    field = error.path.join('.') || 'configuration';
+  } else {
+    field = error.path.join('.') || 'configuration';
+  }
+
+  // Create user-friendly message
+  const message = createUserFriendlyMessage(error, field, type);
+
+  return {
+    type,
+    nodeId,
+    edgeId,
+    field,
+    message,
+    fullPath,
+    originalError: error,
+  };
+}
+
+/**
+ * Create user-friendly error messages
+ */
+function createUserFriendlyMessage(
+  error: ValidationErrorDetail,
+  field: string,
+  type: 'node' | 'edge' | 'graph'
+): string {
+  const entityType = type === 'node' ? 'Agent' : type === 'edge' ? 'Connection' : 'Graph';
+  const fieldName = getFieldDisplayName(field);
+
+  switch (error.code) {
+    case 'invalid_type':
+      if (error.expected === 'string' && error.message.includes('undefined')) {
+        return `${entityType} is missing required field: ${fieldName}`;
+      }
+      return `${entityType} ${fieldName} has invalid type. Expected ${error.expected}`;
+
+    case 'too_small':
+      return `${entityType} ${fieldName} is too short. Please provide a valid value`;
+
+    case 'invalid_enum_value':
+      return `${entityType} ${fieldName} has an invalid value. Please select a valid option`;
+
+    case 'invalid_union':
+      // Check if this is an agent type discrimination error
+      if (field.includes('type') || error.message.includes('discriminator')) {
+        return `${entityType} type must be specified as either 'internal' or 'external'`;
+      }
+      return `${entityType} configuration is incomplete. Please check all required fields`;
+
+    default:
+      return `${entityType} ${fieldName}: ${error.message}`;
+  }
+}
+
+/**
+ * Convert technical field names to user-friendly display names
+ */
+function getFieldDisplayName(field: string): string {
+  const fieldMap: Record<string, string> = {
+    instructions: 'Instructions',
+    projectId: 'Project ID',
+    baseUrl: 'Host URL',
+    name: 'Name',
+    description: 'Description',
+    model: 'Model',
+    temperature: 'Temperature',
+    maxTokens: 'Max Tokens',
+    systemPrompt: 'System Prompt',
+    tools: 'Tools',
+    dataComponents: 'Data Components',
+    artifactComponents: 'Artifact Components',
+    relationships: 'Relationships',
+    transferTargetToSource: 'Transfer (Target to Source)',
+    transferSourceToTarget: 'Transfer (Source to Target)',
+    delegateTargetToSource: 'Delegate (Target to Source)',
+    delegateSourceToTarget: 'Delegate (Source to Target)',
+    contextConfig: 'Context Configuration',
+    contextVariables: 'Context Variables',
+    requestContextSchema: 'Request Context Schema',
+  };
+
+  return (
+    fieldMap[field] || field.replace(/([A-Z])/g, ' $1').replace(/^./, (str) => str.toUpperCase())
+  );
+}
+
+/**
+ * Categorize processed errors by type and entity ID
+ */
+function categorizeErrors(errors: ProcessedGraphError[]): GraphErrorSummary {
+  const nodeErrors: Record<string, ProcessedGraphError[]> = {};
+  const edgeErrors: Record<string, ProcessedGraphError[]> = {};
+  const graphErrors: ProcessedGraphError[] = [];
+
+  for (const error of errors) {
+    switch (error.type) {
+      case 'node':
+        if (error.nodeId) {
+          if (!nodeErrors[error.nodeId]) {
+            nodeErrors[error.nodeId] = [];
+          }
+          nodeErrors[error.nodeId].push(error);
+        }
+        break;
+      case 'edge':
+        if (error.edgeId) {
+          if (!edgeErrors[error.edgeId]) {
+            edgeErrors[error.edgeId] = [];
+          }
+          edgeErrors[error.edgeId].push(error);
+        }
+        break;
+      case 'graph':
+        graphErrors.push(error);
+        break;
+    }
+  }
+
+  return {
+    totalErrors: errors.length,
+    nodeErrors,
+    edgeErrors,
+    graphErrors,
+    allErrors: errors,
+  };
+}
+
+/**
+ * Generate a concise summary message for the error toast
+ */
+export function getErrorSummaryMessage(errorSummary: GraphErrorSummary): string {
+  const { totalErrors, nodeErrors, edgeErrors, graphErrors } = errorSummary;
+
+  if (totalErrors === 0) return '';
+
+  const parts: string[] = [];
+
+  const nodeErrorCount = Object.keys(nodeErrors).length;
+  const edgeErrorCount = Object.keys(edgeErrors).length;
+  const graphErrorCount = graphErrors.length;
+
+  if (nodeErrorCount > 0) {
+    parts.push(`${nodeErrorCount} agent${nodeErrorCount > 1 ? 's' : ''}`);
+  }
+  if (edgeErrorCount > 0) {
+    parts.push(`${edgeErrorCount} connection${edgeErrorCount > 1 ? 's' : ''}`);
+  }
+  if (graphErrorCount > 0) {
+    parts.push(`${graphErrorCount} graph setting${graphErrorCount > 1 ? 's' : ''}`);
+  }
+
+  const summary = parts.join(', ');
+  return `Validation failed for ${summary}. Check the highlighted items for details.`;
+}

package/src/lib/utils/mcp-schema-parser.ts

@@ -0,0 +1,202 @@
+/**
+ * Utility functions for parsing MCP tool input schemas
+ */
+
+interface SchemaProperty {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+  enum?: string[];
+}
+
+interface ParsedSchema {
+  properties: SchemaProperty[];
+  hasProperties: boolean;
+}
+
+/**
+ * Parse MCP input schema into a more readable format
+ * Handles multiple schema formats:
+ * - Zod-based schemas (with def.shape structure)
+ * - Standard JSON Schema (with properties object)
+ * - Direct property objects
+ */
+export function parseMCPInputSchema(inputSchema: any): ParsedSchema {
+  if (!inputSchema || typeof inputSchema !== 'object') {
+    return { properties: [], hasProperties: false };
+  }
+
+  const properties: SchemaProperty[] = [];
+
+  // Handle Zod-based schema format (like Notion MCP)
+  if (inputSchema.def?.shape) {
+    const shape = inputSchema.def.shape;
+    for (const [propertyName, propertyDef] of Object.entries(shape)) {
+      const property = parseZodProperty(propertyName, propertyDef as any);
+      if (property) {
+        properties.push(property);
+      }
+    }
+  }
+  // Handle standard JSON Schema format
+  else if (inputSchema.properties) {
+    for (const [propertyName, propertyDef] of Object.entries(inputSchema.properties)) {
+      const property = parseJsonSchemaProperty(
+        propertyName,
+        propertyDef as any,
+        inputSchema.required
+      );
+      if (property) {
+        properties.push(property);
+      }
+    }
+  }
+  // Handle direct properties format
+  else {
+    for (const [propertyName, propertyDef] of Object.entries(inputSchema)) {
+      const property = parseGenericProperty(propertyName, propertyDef as any);
+      if (property) {
+        properties.push(property);
+      }
+    }
+  }
+
+  return {
+    properties: properties.sort((a, b) => {
+      // Sort required properties first, then by name
+      if (a.required !== b.required) {
+        return a.required ? -1 : 1;
+      }
+      return a.name.localeCompare(b.name);
+    }),
+    hasProperties: properties.length > 0,
+  };
+}
+
+// Parse Zod-based property definition (e.g., Notion MCP)
+function parseZodProperty(name: string, propertyDef: any): SchemaProperty | null {
+  if (!propertyDef?.def) {
+    return null;
+  }
+
+  const def = propertyDef.def;
+  let type: string;
+  let required = true;
+
+  // Handle optional properties
+  if (def.type === 'optional') {
+    required = false;
+    if (def.innerType?.def) {
+      type = parseTypeFromDef(def.innerType.def);
+    } else {
+      type = 'any';
+    }
+  } else {
+    type = parseTypeFromDef(def);
+  }
+
+  return {
+    name,
+    type,
+    required,
+  };
+}
+
+// Parse standard JSON Schema property definition
+function parseJsonSchemaProperty(
+  name: string,
+  propertyDef: any,
+  requiredFields?: string[]
+): SchemaProperty | null {
+  if (!propertyDef || typeof propertyDef !== 'object') {
+    return null;
+  }
+
+  const type = propertyDef.type || 'any';
+  const required = requiredFields ? requiredFields.includes(name) : false;
+
+  return {
+    name,
+    type: formatJsonSchemaType(type, propertyDef),
+    required,
+    description: propertyDef.description,
+    enum: propertyDef.enum,
+  };
+}
+
+// Parse generic property definition (fallback)
+function parseGenericProperty(name: string, propertyDef: any): SchemaProperty | null {
+  if (typeof propertyDef !== 'object' || propertyDef === null) {
+    return {
+      name,
+      type: typeof propertyDef,
+      required: false,
+    };
+  }
+
+  // Try to infer type from the property definition
+  let type = 'object';
+  if (propertyDef.type) {
+    type = propertyDef.type;
+  } else if (Array.isArray(propertyDef)) {
+    type = 'array';
+  }
+
+  return {
+    name,
+    type,
+    required: false,
+    description: propertyDef.description,
+  };
+}
+
+// Format JSON Schema type with additional info
+function formatJsonSchemaType(type: string, propertyDef: any): string {
+  if (type === 'array' && propertyDef.items?.type) {
+    return `${propertyDef.items.type}[]`;
+  }
+  return type;
+}
+
+function parseTypeFromDef(def: any): string {
+  switch (def.type) {
+    case 'string':
+      return 'string';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      if (def.element?.def) {
+        const elementType = parseTypeFromDef(def.element.def);
+        return `${elementType}[]`;
+      }
+      return 'array';
+    case 'object':
+      return 'object';
+    case 'any':
+      return 'any';
+    case 'union':
+      // Handle union types if needed
+      return 'union';
+    case 'literal':
+      return `"${def.value}"`;
+    default:
+      return def.type || 'unknown';
+  }
+}
+
+/**
+ * Get a user-friendly type badge color based on the type
+ */
+export function getTypeBadgeVariant(
+  type: string
+): 'default' | 'secondary' | 'destructive' | 'outline' {
+  if (type.includes('string')) return 'default';
+  if (type.includes('number')) return 'secondary';
+  if (type.includes('boolean')) return 'outline';
+  if (type.includes('array')) return 'secondary';
+  if (type.includes('object')) return 'destructive';
+  return 'outline';
+}

package/src/lib/utils/mcp-urls.ts

@@ -0,0 +1,63 @@
+// Client-side utility for building MCP-related URLs
+// This file does NOT have 'use server' so functions can be synchronous
+
+// Default configuration (same as in api/tools.ts)
+import { MANAGEMENT_API_BASE_URL } from '../api/api-config';
+
+/**
+ * Get OAuth login URL for an MCP tool that requires authentication
+ * This returns the URL that should be used for redirect on the client side
+ */
+export function getOAuthLoginUrl({
+  tenantId,
+  projectId,
+  id,
+}: {
+  tenantId: string;
+  projectId: string;
+  id: string;
+}): string {
+  // Validate input parameters
+  if (!tenantId || typeof tenantId !== 'string') {
+    throw new Error('Invalid tenantId: must be a non-empty string');
+  }
+
+  if (!id || typeof id !== 'string') {
+    throw new Error('Invalid tool id: must be a non-empty string');
+  }
+
+  if (!projectId || typeof projectId !== 'string') {
+    throw new Error('Invalid projectId: must be a non-empty string');
+  }
+
+  // Validate format - only allow alphanumeric, hyphens, and underscores
+  const validFormat = /^[a-zA-Z0-9-_]+$/;
+
+  if (!validFormat.test(tenantId)) {
+    throw new Error(
+      'Invalid tenantId format: only alphanumeric characters, hyphens, and underscores allowed'
+    );
+  }
+
+  if (!validFormat.test(id)) {
+    throw new Error(
+      'Invalid tool id format: only alphanumeric characters, hyphens, and underscores allowed'
+    );
+  }
+
+  if (!validFormat.test(projectId)) {
+    throw new Error(
+      'Invalid projectId format: only alphanumeric characters, hyphens, and underscores allowed'
+    );
+  }
+
+  // Build URL with proper encoding
+  const url = `${MANAGEMENT_API_BASE_URL}/tenants/${encodeURIComponent(tenantId)}/crud/projects/${encodeURIComponent(projectId)}/tools/${encodeURIComponent(id)}/oauth-login`;
+
+  // Verify the final URL starts with our expected base
+  if (!url.startsWith(MANAGEMENT_API_BASE_URL)) {
+    throw new Error('Invalid OAuth URL generated');
+  }
+
+  return url;
+}

package/src/lib/utils/mcp-utils.ts

@@ -0,0 +1,18 @@
+import type { MCPTool } from '@/lib/api/tools';
+
+/**
+ * Parses an MCP tool name to extract the type and name components.
+ * Tool names are expected to be in the format "type::name".
+ *
+ * @param tool - The MCP tool object
+ * @returns Object containing the parsed type and name
+ *
+ * @example
+ * const tool = { name: "gmail::send_email", ... };
+ * const { type, name } = getToolTypeAndName(tool);
+ * // type: "gmail", name: "send_email"
+ */
+export const getToolTypeAndName = (tool: MCPTool) => {
+  const [type, name] = tool.name.split('::');
+  return { type, name };
+};

package/src/lib/utils/project-redirect.ts

@@ -0,0 +1,39 @@
+'use server';
+
+import { redirect } from 'next/navigation';
+import { fetchProjects } from '../api/projects';
+
+/**
+ * Fetches projects and redirects to the appropriate project page.
+ * If no projects exist, redirects to the create project page.
+ * If there's an error fetching projects, also redirects to create project page.
+ */
+export async function redirectToProject(
+  tenantId: string,
+  targetPath: string = 'graphs'
+): Promise<never> {
+  try {
+    const result = await fetchProjects(tenantId);
+
+    if (result.data && result.data.length > 0) {
+      // Redirect to the first project in the list
+      const firstProject = result.data[0];
+      redirect(`/${tenantId}/projects/${firstProject.projectId}/${targetPath}`);
+    } else {
+      // No projects found, redirect to projects page
+      redirect(`/${tenantId}/projects`);
+    }
+  } catch (error) {
+    // Re-throw redirect errors (these are expected Next.js behavior)
+    if (
+      error instanceof Error &&
+      (error.message === 'NEXT_REDIRECT' || (error as any).digest?.startsWith('NEXT_REDIRECT'))
+    ) {
+      throw error;
+    }
+
+    // Actual error occurred, redirect to projects landing page
+    console.error('Error fetching projects, redirecting to projects page:', error);
+    redirect(`/${tenantId}/projects`);
+  }
+}

package/src/lib/utils.ts

@@ -0,0 +1,46 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export function formatJson(jsonString: string) {
+  try {
+    const parsed = JSON.parse(jsonString);
+    return JSON.stringify(parsed, null, 2);
+  } catch (error) {
+    return jsonString;
+  }
+}
+
+export function formatJsonField(value: any): string {
+  if (value === undefined || value === null) {
+    return '';
+  }
+
+  const stringifiedValue = JSON.stringify(value);
+  if (stringifiedValue?.trim()) {
+    return formatJson(stringifiedValue);
+  }
+
+  return '';
+}
+
+/**
+ * Transform an array of components into a lookup map by ID
+ * Works with any component type that has an 'id' property
+ */
+export function createLookup<T extends { id: string }>(
+  components: T[] | undefined
+): Record<string, T> {
+  if (!components) return {};
+
+  return components.reduce(
+    (map, component) => {
+      map[component.id] = component;
+      return map;
+    },
+    {} as Record<string, T>
+  );
+}

package/src/lib/validation.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+/**
+ * Reusable ID validation schema for database primary keys.
+ * Ensures IDs are alphanumeric with underscores and dashes allowed, no whitespace.
+ */
+export const idSchema = z
+  .string()
+  .min(1, 'Id is required.')
+  .max(64, 'Id must be less than 64 characters.')
+  .regex(
+    /^[a-zA-Z0-9_-]+$/,
+    'Id must contain only alphanumeric characters, underscores, and dashes. No spaces allowed.'
+  );

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}