Flow-Forge MCP Server

MCP (Model Context Protocol) server that enables AI assistants like Claude, ChatGPT, and Gemini to generate flowcharts using Flow-Forge's multi-agent system.

Features

• Intelligent Flowchart Generation: Natural language to diagram conversion
• Multi-round Q&A: Interactive clarification for better results
• Multiple Formats: Mermaid, PlantUML, and BPMN 2.0 support
• Real-time Progress: SSE-based progress reporting
• Task Management: Status checking and cancellation

Installation

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Set the Flow-Forge API URL via environment variable:

export FLOWFORGE_API_URL=http://localhost:8000

Optionally, configure an API key for authentication:

export FLOWFORGE_API_KEY=your-api-key-here

Or create a .env file:

FLOWFORGE_API_URL=http://localhost:8000
FLOWFORGE_API_KEY=your-api-key-here  # Optional

Usage

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "flow-forge": {
      "command": "node",
      "args": ["/path/to/flow-forge-mcp/dist/index.js"],
      "env": {
        "FLOWFORGE_API_URL": "http://localhost:8000",
        "FLOWFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or using npx (after publishing):

{
  "mcpServers": {
    "flow-forge": {
      "command": "npx",
      "args": ["flow-forge-mcp"],
      "env": {
        "FLOWFORGE_API_URL": "http://localhost:8000",
        "FLOWFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Development

# Run in development mode
npm run dev

# Type checking
npm run typecheck

Tools

generate_flowchart

Generate or modify a flowchart based on natural language requirements.

Parameters:

• requirements (string, required): Natural language description
• answers (object, optional): Answers to clarification questions
• context (object, optional): Execution context from previous call
• current_code (string, optional): Existing diagram code for modification
• collection_id (string, optional): RAG collection ID
• diagram_format (string, optional): "mermaid" | "plantuml" | "bpmn"

Returns:

• status: "completed" | "questions_required" | "failed"
• diagram_format: Output format (when completed)
• diagram_code: Generated diagram code (when completed)
• questions: Clarification questions (when questions_required)
• context: Context for continuation

get_task_status

Get the current status of a flowchart generation task.

Parameters:

• task_id (string, required): Task ID from generate_flowchart

Returns:

• task_id: Task identifier
• status: Current status
• progress: Execution progress (0-1)
• current_agent: Currently executing agent
• result: Task result (when completed)
• error: Error message (when failed)

cancel_task

Cancel a running flowchart generation task.

Parameters:

• task_id (string, required): Task ID to cancel

Returns:

• status: "cancelled" | "already_finished" | "not_found"
• message: Status message

list_diagram_types

List all supported diagram types and their characteristics.

Returns:

• types: Array of diagram type information
  • type: Type identifier
  • name: Display name
  • description: Description
  • formats: Supported output formats
  • examples: Example requirements

Example Conversation

User: Help me create a user login flowchart

Claude: [calls generate_flowchart]

The system needs some clarification:

1. What authentication methods? (Username/Password, Phone verification, Social login)
2. Need "Remember me" feature?

What are your preferences?

User: Username/password, yes for remember me

Claude: [calls generate_flowchart with answers and context]

Here's your login flowchart:

flowchart TD
    A[Start] --> B[Enter username/password]
    B --> C{Validate}
    C -->|Success| D{Remember me?}
    D -->|Yes| E[Save token]
    D -->|No| F[Skip]
    E --> G[Go to home]
    F --> G
    C -->|Fail| H[Show error]
    H --> B

Supported Diagram Types

| Type | Description | Formats | |------|-------------|---------| | flowchart | Process visualization, decision trees | Mermaid, PlantUML, BPMN | | sequence | Interaction over time | Mermaid, PlantUML | | gantt | Project timeline | Mermaid | | mindmap | Concept organization | Mermaid | | class | UML class diagrams | Mermaid, PlantUML | | er | Entity-Relationship | Mermaid | | state | State machines | Mermaid, PlantUML | | component | System architecture | PlantUML | | usecase | Use case diagrams | PlantUML | | activity | Activity diagrams | PlantUML | | bpmn | Business processes | BPMN |

Requirements

• Node.js >= 18.0.0
• Flow-Forge API server running

License

MIT