generate_ui_flow

Instructions

Implementation Reference

• src/index.ts:135-198 (handler)

  Main execution logic for the generate_ui_flow tool within the CallToolRequestSchema handler.

  if (request.params.name !== "generate_ui_flow") {
    throw new McpError(
      ErrorCode.MethodNotFound,
      `Unknown tool: ${request.params.name}`
    );
  }
  
  const args = request.params.arguments as {
    repoPath: string;
    isLocal: boolean;
    owner?: string;
    repo?: string;
    fileExtensions?: string[];
  };
  const { repoPath, isLocal, owner, repo, fileExtensions } = args;
  
  try {
    let contents: RepoContents[];
    if (isLocal) {
      contents = await fetchLocalRepoContents(repoPath);
    } else {
      if (!owner || !repo) {
        throw new McpError(
          ErrorCode.InvalidParams,
          "Owner and repo are required for GitHub repositories"
        );
      }
      contents = await fetchGitHubRepoContents(owner, repo);
    }
  
    const components = await parseUIFlow(contents, isLocal, fileExtensions);
    const mermaidChart = generateMermaidFlowchart(JSON.parse(components));
  
    // Determine output path based on repository type
    const outputPath = isLocal
      ? path.join(repoPath, "userflo.md")
      : path.join(process.cwd(), "userflo.md");
    const flowDescription = `# UI Flow Diagram\n\nThis document describes the UI flow of the application.\n\n`;
    const fullContent =
      flowDescription + "```mermaid\n" + mermaidChart + "\n```\n\n";
  
    await fs.writeFile(outputPath, fullContent);
    console.log(`[MCP] UI flow saved to ${outputPath}`);
  
    return {
      content: [
        {
          type: "text",
          text: mermaidChart,
        },
      ],
    };
  } catch (error) {
    if (error instanceof McpError) {
      throw error;
    }
    throw new McpError(
      ErrorCode.InternalError,
      `Failed to generate UI flow: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }

• src/index.ts:38-71 (schema)

  Input schema definition for the generate_ui_flow tool.

  inputSchema: {
    type: "object",
    properties: {
      repoPath: {
        type: "string",
        description:
          "Path to local repository or empty string for GitHub repos",
      },
      isLocal: {
        type: "boolean",
        description:
          "Whether to analyze a local repository (true) or GitHub repository (false)",
      },
      owner: {
        type: "string",
        description:
          "GitHub repository owner (required if isLocal is false)",
      },
      repo: {
        type: "string",
        description:
          "GitHub repository name (required if isLocal is false)",
      },
      fileExtensions: {
        type: "array",
        items: { type: "string" },
        description:
          "List of file extensions to analyze (e.g., ['js', 'jsx', 'ts', 'tsx'] for React, ['ts', 'html'] for Angular)",
        default: ["js", "jsx", "ts", "tsx"],
      },
    },
    required: ["repoPath", "isLocal"],
    additionalProperties: false,
  },

• src/index.ts:34-73 (registration)

  Tool registration in server capabilities.

    generate_ui_flow: {
      name: "generate_ui_flow",
      description:
        "Generate a UI flow diagram by analyzing React/Angular repositories. This tool scans the codebase to identify components, their relationships, and the overall UI structure.",
      inputSchema: {
        type: "object",
        properties: {
          repoPath: {
            type: "string",
            description:
              "Path to local repository or empty string for GitHub repos",
          },
          isLocal: {
            type: "boolean",
            description:
              "Whether to analyze a local repository (true) or GitHub repository (false)",
          },
          owner: {
            type: "string",
            description:
              "GitHub repository owner (required if isLocal is false)",
          },
          repo: {
            type: "string",
            description:
              "GitHub repository name (required if isLocal is false)",
          },
          fileExtensions: {
            type: "array",
            items: { type: "string" },
            description:
              "List of file extensions to analyze (e.g., ['js', 'jsx', 'ts', 'tsx'] for React, ['ts', 'html'] for Angular)",
            default: ["js", "jsx", "ts", "tsx"],
          },
        },
        required: ["repoPath", "isLocal"],
        additionalProperties: false,
      },
    },
  },

• src/utils/flowParser.ts:18-118 (helper)

  Core helper function that parses repository contents to extract UI component hierarchy and relationships.

  export async function parseUIFlow(
    contents: RepoContents[],
    isLocal: boolean,
    fileExtensions: string[] = ["js", "jsx", "ts", "tsx"]
  ): Promise<string> {
    console.log(
      `[MCP] Parsing UI flow with extensions: ${fileExtensions.join(", ")}`
    );
  
    const components: { [key: string]: ComponentInfo } = {};
  
    async function processContents(
      currentContents: RepoContents[],
      currentPath: string = ""
    ) {
      for (const item of currentContents) {
        if (
          item.type === "file" &&
          fileExtensions.some((ext) => item.name.endsWith(`.${ext}`))
        ) {
          let content: string;
          if (isLocal) {
            content = item.content || "";
          } else {
            try {
              const response = await axios.get(item.download_url || "");
              content = response.data;
            } catch (error) {
              console.warn(
                `[MCP] Failed to fetch content for ${item.name}: ${error}`
              );
              continue;
            }
          }
  
          const componentName = item.name.split(".")[0];
          const componentPath = path.join(currentPath, componentName);
          const componentType = getComponentType(componentPath);
  
          components[componentPath] = {
            name: componentName,
            type: componentType,
            filePath: path.join(currentPath, item.name),
            imports: [],
            children: [],
          };
  
          // Analyze import statements
          const importMatches = content.match(
            /import\s+(\w+|\{[^}]+\})\s+from\s+['"]([^'"]+)['"]/g
          );
          if (importMatches) {
            importMatches.forEach((match) => {
              const [, importedComponent, importPath] =
                match.match(
                  /import\s+(\w+|\{[^}]+\})\s+from\s+['"]([^'"]+)['"]/
                ) || [];
              if (importedComponent) {
                const cleanedImport = importedComponent
                  .replace(/[{}]/g, "")
                  .trim();
                const resolvedPath = path.join(
                  currentPath,
                  path.dirname(importPath),
                  cleanedImport
                );
                components[componentPath].imports.push(resolvedPath);
              }
            });
          }
        } else if (item.type === "dir") {
          const subContents = isLocal
            ? await fetchLocalRepoContents(item.path)
            : await fetchGitHubRepoContents(
                item.owner || "",
                item.repo || "",
                item.path
              );
  
          await processContents(subContents, path.join(currentPath, item.name));
        }
      }
    }
  
    await processContents(contents);
  
    // Build component hierarchy
    const rootComponents: ComponentInfo[] = [];
    Object.values(components).forEach((component) => {
      component.imports.forEach((importPath) => {
        if (components[importPath]) {
          components[importPath].children.push(component);
        }
      });
      if (component.imports.length === 0) {
        rootComponents.push(component);
      }
    });
  
    return JSON.stringify(rootComponents, null, 2);
  }

• src/utils/flowParser.ts:149-235 (helper)

  Helper function that generates Mermaid flowchart syntax from parsed UI components.

  export function generateMermaidFlowchart(components: ComponentInfo[]): string {
    let chart = "flowchart TD\n";
  
    // Create a map of all components for quick lookup
    const componentMap = new Map<string, ComponentInfo>();
    components.forEach((component) => {
      componentMap.set(component.name, component);
    });
  
    // Create nodes with proper styling and hierarchy
    const createNode = (component: ComponentInfo, depth: number = 0): string => {
      const nodeId = component.name.replace(/[^a-zA-Z0-9]/g, "_");
      const indent = "  ".repeat(depth);
  
      // Determine node style based on type
      let nodeStyle = "";
      switch (component.type) {
        case "page":
          nodeStyle = "(( ))";
          break;
        case "layout":
          nodeStyle = "{{ }}";
          break;
        default:
          nodeStyle = "[/ /]";
      }
  
      // Add node with proper indentation
      chart += `${indent}${nodeId}${nodeStyle}["${component.name} (${component.type})"]\n`;
  
      // Recursively process children
      component.children.forEach((child) => {
        const childComponent = componentMap.get(child.name);
        if (childComponent) {
          createNode(childComponent, depth + 1);
        }
      });
  
      return nodeId;
    };
  
    // Find root components (those with no parents)
    const rootComponents = components.filter(
      (component) =>
        !components.some((c) =>
          c.children.some((child) => child.name === component.name)
        )
    );
  
    // Start building the chart from root components
    rootComponents.forEach((component) => {
      createNode(component);
    });
  
    // Create relationships with labels
    components.forEach((component) => {
      const parentId = component.name.replace(/[^a-zA-Z0-9]/g, "_");
  
      component.children.forEach((child) => {
        const childId = child.name.replace(/[^a-zA-Z0-9]/g, "_");
        const relationshipType = determineRelationshipType(component, child);
        chart += `  ${parentId} -->|${relationshipType}| ${childId}\n`;
      });
    });
  
    // Validate Mermaid.js syntax
    try {
      // Basic validation - check for required elements
      if (!chart.includes("flowchart TD")) {
        throw new Error("Missing flowchart declaration");
      }
      if (!chart.match(/\[.*\]/)) {
        throw new Error("Missing node definitions");
      }
      if (!chart.match(/-->|--/)) {
        throw new Error("Missing relationship definitions");
      }
    } catch (error) {
      console.error("[MCP] Mermaid.js validation error:", error);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to generate valid Mermaid.js chart: ${error}`
      );
    }
  
    return chart;
  }