thought_bubble MCP

Abrakedabra - your boring documents are now a lovely website with workflow diagrams

A creative, MCP-native tool that transforms any documentation, system architecture, or plan into beautiful interactive HTML visualisations through seamless AI integration.

Transform plain documentation into interactive Sankey diagrams

What Is This?

A Model Context Protocol (MCP) server that works with your AI assistant to automatically analyse documentation and generate stunning, interactive HTML visualisations with embedded diagrams and charts. No build tools, no frameworks - just pure HTML, CSS, and JavaScript that works everywhere.

MCP-First Design:

Native integration with Claude Desktop, Cursor, and any MCP-compatible client
Automated analysis identifies systems, workflows, and data models in your content
Server-side SVG rendering with beautiful-mermaid and D3 (no CDN required!)
Smart diagram generation: Mermaid (flowchart, sequence, ER, class, state) + D3 charts (bar, pie, donut, line, area, gantt, timeline, quadrant, sankey, radial, treemap)
13 layout templates (sidebar, magazine, presentation, dashboard, minimal, editorial, comparison, briefing, tutorial, scorecard, report, dossier, dialogue)
Section roles (metric, pull-quote, lead, statement, full-width, supporting) for fine-grained visual control
Density presets (compact, comfortable, spacious) to match content type
12 curated themes including Tokyo Night, Dracula, Gruvbox, GitHub, and Solarized
Advanced chart styling (annotations, curve types, color strategies, emphasis effects, pattern encoding for accessibility)
Live theme switching - users can change themes without regenerating
One-command workflow - just say "visualise this" and your AI handles everything
Self-contained HTML that works completely offline

See It In Action

Browse the full examples gallery →

16 D3 Chart Types

Bar, line, area, pie, donut, gantt, timeline, quadrant, sankey, radial, treemap - all with annotations, emphasis effects, and live theme switching

Layout Templates

Same content rendered three ways to match your use case:

Sidebar - Multi-section navigation
Best for: API docs, technical references

Magazine - Hero + narrative flow
Best for: Reports, case studies

Dashboard - KPI cards + grid
Best for: Monitoring, metrics

Full Examples

Payment Gateway API
RESTful API docs with sequence diagrams and ER models

Product Roadmap 2026
9-phase development plan with $5M ARR target

View all examples with live previews →

How It Works

graph LR
    A[Documentation] --> C[LLM]
    B[User Request] --> C
    C <--> D[thought_bubble MCP]
    C --> E[HTML + Charts Output]
    
    style A fill:#d5f4f7,stroke:#00838f,stroke-width:3px
    style B fill:#d5f4f7,stroke:#00838f,stroke-width:3px
    style C fill:#d1e7fd,stroke:#0d47a1,stroke-width:3px
    style D fill:#fff4e1,stroke:#ff9900,stroke-width:3px
    style E fill:#d4edda,stroke:#28a745,stroke-width:3px

The MCP Workflow

You add: Documents to LLM context
You say: "Analyse and visualise this documentation"
thought_bubble MCP: Identifies systems, workflows, data models automatically
You choose: Which items to visualise
thought_bubble MCP: Creates Mermaid diagrams + complete HTML visualisation
You open: Beautiful visualisation in your browser
You experience: Clarity and joy

Alternative: Standalone Prompt Method

For environments without MCP support, you can use the standalone prompt-based approach:

Copy prompt_template.md + your content
Send to your LLM manually
Receive generated HTML

Quick Start

MCP Installation (Primary Method)

2-minute setup for Claude Desktop, Cursor, or any MCP client:

cd thought_bubble_mcp
npm install && npm run build

Then add to your MCP config and restart your AI client:

{
  "mcpServers": {
    "thought-bubble": {
      "command": "node",
      "args": ["/absolute/path/to/thought_bubble/thought_bubble_mcp/dist/index.js"]
    }
  }
}

Note: Replace /absolute/path/to/thought_bubble/ with your actual installation path.

Full instructions: thought_bubble_mcp/START_HERE.md

Usage:

"Use thought-bubble tools to analyse this content and create a visualisation:

[paste/add your documentation as context]"

That's it. Your AI will analyse, generate diagrams, and create the complete HTML visualisation.

Quick Test - Try It Now

Want to test thought_bubble immediately? We've included three ready-to-use test documents:

1. API Integration Documentation

File: test_inputs/test_doc_1_api_integration.md

Content: Payment Gateway API with authentication flows, service architecture, and data models

Expected visualisations:

Service architecture diagram (flowchart)
Payment processing sequence (sequence diagram)
Data model relationships (ER diagram)

2. Product Roadmap

File: test_inputs/test_doc_2_product_roadmap.md

Content: 2026 development roadmap with 9 phases across 4 quarters

Expected visualisations:

Development timeline (gantt-style flowchart)
Feature dependencies (flowchart)
Resource allocation

3. Organisational Structure

File: test_inputs/test_doc_3_org_structure.md

Content: Company hierarchy with 8 executives, VPs, and decision-making frameworks

Expected visualisations:

Executive leadership hierarchy (flowchart)
Decision-making flow (flowchart)
Team distribution

To test:

Open any test document in your AI assistant
Say: "Use thought-bubble to analyse and visualise this documentation"
Choose which systems to visualise from the identified list
Receive your interactive HTML visualisation

Alternative Methods (Without MCP)

For Claude/ChatGPT (Manual prompt):

Copy contents of prompt_template.md
Attach your source document
Send to your LLM
Receive HTML visualisation

For Cursor/AI IDE (Workspace reference):

Open your documentation file
Reference: @thought_bubble
Say: "Visualise this using thought_bubble"
AI generates custom HTML

What Can You Visualise?

System architectures
Development plans
API documentation
Organisation charts
Project roadmaps
Process flows
Data models
Integration guides
Technical specifications
Knowledge bases
Anything with structure!

Features

13 Layout Templates

Each optimised for specific content types and use cases:

sidebar - Multi-section docs with fixed navigation (7+ sections)
magazine - Reports and case studies with hero section and pull quotes
presentation - Pitch decks with full-viewport snap-scroll slides
dashboard - KPI monitoring with metric cards and chart grid
minimal - Single-topic deep dives with visual-first hero
editorial - Essays and narratives with centred academic style
comparison - Vendor evaluation with parallel columns
briefing - Sprint reviews with lead item and stats strip
tutorial - Step-by-step guides with progress spine
scorecard - Maturity assessments with semantic-colour scoring
report - RFCs and compliance docs with cover and TOC
dossier - Research synthesis with profile header and facts
dialogue - ADRs with structured arguments and trade-offs

Section Roles

Fine-grained visual control for individual sections:

metric - Large KPI cards with values and labels
pull-quote - Display-font blockquotes for standout insights
lead - Wider opening paragraphs with larger text
statement - Large centred text for key messages
full-width - Breakout visuals that span viewport
supporting - Appendices and secondary content

D3 Chart Capabilities

16+ chart types - bar, pie, donut, line, area, gantt, timeline, quadrant, sankey, radial, treemap

Example - Revenue chart with annotations:

{
  "diagramType": "line",
  "chartData": [
    {"x": "Q1", "y": 1200000},
    {"x": "Q2", "y": 1850000},
    {"x": "Q3", "y": 2100000},
    {"x": "Q4", "y": 3200000}
  ],
  "chartOptions": {
    "curve": "smooth",
    "emphasis": "glow",
    "colorStrategy": "monochrome",
    "annotations": [
      {"label": "Product launch +54%", "x": "Q2", "y": 1850000, "dx": 10, "dy": -20},
      {"label": "Enterprise deals", "x": "Q4", "y": 3200000, "dx": 10, "dy": -20}
    ]
  }
}

Example - Sankey flow diagram:

{
  "diagramType": "sankey",
  "chartData": [{
    "nodes": [
      {"id": "direct", "label": "Direct Sales"},
      {"id": "partner", "label": "Partners"},
      {"id": "enterprise", "label": "Enterprise"},
      {"id": "smb", "label": "SMB"}
    ],
    "links": [
      {"source": "direct", "target": "enterprise", "value": 45},
      {"source": "direct", "target": "smb", "value": 12},
      {"source": "partner", "target": "enterprise", "value": 28},
      {"source": "partner", "target": "smb", "value": 35}
    ]
  }]
}

Chart options:

Annotations - Data point labels with dx/dy positioning
Curve types - smooth, natural, sharp, step
Color strategies - categorical, sequential, diverging, monochrome
Emphasis effects - glow, shadow, lift, none
Pattern encoding - patterns: true for WCAG compliance
Animations - stagger, draw, grow, fade, none

Professional Design

12 curated themes - Tokyo Night, Dracula, Gruvbox, Solarized Dark/Light, GitHub Dark/Light, Professional, Creative, Technical, Minimal, Dark
Typography pairings - Theme-specific font combinations (display + body + mono)
Density presets - Compact (information-dense), comfortable (balanced), spacious (generous whitespace)
Live theme switching - Users can change themes in the browser without regenerating
Responsive layouts - Mobile, tablet, desktop breakpoints
Smooth animations - Entry choreography, hover states, transitions
Accessibility - ARIA labels, keyboard navigation, WCAG AA contrast, pattern encoding

Self-Contained

No build process required
No dependencies (except optional Mermaid CDN)
Single HTML file output
Works offline (after first load)
Copy-paste deployable

Chart and Diagram Types

thought_bubble supports a comprehensive range of visualization types. See showcase_examples/README.md for live examples of each.

D3 Charts

bar - Exact comparison, categorical data with rounded bars and value labels
line - Trends over time with configurable curve interpolation
area - Cumulative volume, growth trajectories with gradient fills
pie/donut - Composition breakdown (maximum 6 categories recommended)
radial - Multi-axis comparison in circular layout
gantt - Project timelines and milestone schedules
timeline - Chronological event sequences with central spine
quadrant - 2D positioning matrices (priority, impact analysis)
sankey - Flow volumes and revenue streams
treemap - Hierarchical proportions and taxonomy

Mermaid Diagrams

flowchart - Processes, workflows, decision trees, architecture
sequence - API interactions, authentication flows, message passing
class - Object models, data structures, relationships
er - Database schemas, entity relationships
state - State machines, status transitions, lifecycle management

Note: C4 diagrams are not currently supported.

View comprehensive examples with all chart types

Gantt Chart: Project Timeline

Perfect for project planning, roadmaps, and scheduling:

gantt
    title Project Development Timeline
    dateFormat YYYY-MM-DD
    section Planning
    Requirements Gathering    :done,    req, 2026-01-01, 2026-01-14
    Design & Wireframes       :done,    des, 2026-01-15, 2026-01-28
    section Development
    Backend API               :active,  dev1, 2026-01-29, 30d
    Frontend Components       :         dev2, after dev1, 25d
    Integration               :         dev3, after dev2, 15d
    section Testing
    QA Testing                :         test, after dev3, 20d
    Bug Fixes                 :         fix, after test, 10d
    section Deployment
    Production Release        :         rel, after fix, 5d

Sequence Diagram: Order Processing

Essential for API flows, service interactions, and message passing:

sequenceDiagram
    participant User
    participant UserService as User Service
    participant ProductCatalog as Product Catalog
    participant OrderService as Order Service
    participant PaymentGateway as Payment Gateway
    participant Stripe
    
    User->>UserService: Login Request
    UserService-->>User: JWT Token
    
    User->>ProductCatalog: Browse Products
    ProductCatalog-->>User: Product List
    
    User->>OrderService: Add to Cart
    OrderService->>ProductCatalog: Check Stock
    ProductCatalog-->>OrderService: Stock Available
    OrderService-->>User: Item Added
    
    User->>OrderService: Checkout
    OrderService->>UserService: Verify User
    UserService-->>OrderService: User Verified
    
    OrderService->>PaymentGateway: Process Payment
    PaymentGateway->>Stripe: Charge Card
    Stripe-->>PaymentGateway: Payment Success
    PaymentGateway-->>OrderService: Payment Confirmed
    
    OrderService->>ProductCatalog: Update Stock
    OrderService-->>User: Order Confirmation

User Journey: Onboarding Experience

Ideal for mapping user experiences and touchpoints:

journey
    title New User Onboarding Journey
    section Discovery
      Visit Homepage: 5: User
      Read Features: 4: User
      View Examples: 5: User
    section Registration
      Sign Up: 3: User
      Verify Email: 2: User
      Complete Profile: 4: User
    section First Use
      Watch Tutorial: 4: User
      Create First Project: 3: User
      Invite Team Member: 5: User
    section Adoption
      Daily Usage: 5: User
      Explore Features: 4: User
      Upgrade Plan: 5: User

Flowchart: User Registration Flow

Great for processes, workflows, and decision trees:

flowchart TD
    Start([User Visits Registration]) --> Submit[Submit Email & Password]
    Submit --> Validate{Validate Credentials}
    Validate -->|Valid| SendEmail[Send Verification Email]
    Validate -->|Invalid| Error[Show Error Message]
    Error --> Submit
    SendEmail --> WaitClick[Wait for User Action]
    WaitClick --> Click[User Clicks Activation Link]
    Click --> Activate[Activate Account]
    Activate --> Success([Registration Complete])
    
    style Start fill:#e1f5ff
    style Success fill:#d4edda
    style Error fill:#f8d7da
    style Activate fill:#d4edda

State Diagram: Order Lifecycle

Perfect for state machines, status flows, and lifecycle management:

stateDiagram-v2
    [*] --> Draft
    Draft --> Pending: Submit Order
    Pending --> Processing: Payment Approved
    Pending --> Cancelled: Payment Failed
    Processing --> Shipped: Order Dispatched
    Processing --> Cancelled: Out of Stock
    Shipped --> Delivered: Delivery Confirmed
    Delivered --> Returned: Return Requested
    Returned --> Refunded: Return Processed
    Cancelled --> [*]
    Refunded --> [*]
    Delivered --> [*]

Plus many more: ER diagrams, class diagrams, Git graphs, pie charts, quadrant charts, and C4 architecture diagrams. See all examples

Files in This Repo

thought_bubble/
├── README.md                          # This file
├── thought_bubble_mcp/                # MCP Server (Primary interface)
│   ├── START_HERE.md                 # MCP quick start guide
│   ├── README.md                     # Complete MCP documentation
│   ├── ARCHITECTURE.md               # Complete architectural reference
│   ├── THEMES.md                     # Theme documentation
│   ├── src/                          # TypeScript source code
│   │   ├── index.ts                  # MCP server entry point
│   │   ├── tools/                    # Tool implementations
│   │   ├── renderers/                # D3 and Mermaid rendering
│   │   ├── builders/                 # HTML assembly
│   │   ├── themes/                   # Theme system
│   │   └── prompts/                  # LLM prompt templates
│   ├── scripts/                      # Showcase generation scripts
│   └── dist/                         # Built server (after npm run build)
├── LLM_Design_Assets/                 # Design system documentation
│   └── ESSENTIAL_DESIGN_RULES.md     # Core design principles
├── DesignTeam/                        # Internal design documentation
│   └── DesignGuide/                  # Detailed design guides (POV, Typography, Layouts, D3, Color, Spacing)
├── showcase_examples/                 # 13 comprehensive example visualizations
│   ├── README.md                     # Detailed example documentation
│   ├── index.html                    # Example gallery
│   └── *.html                        # Individual examples
├── test_inputs/                       # Test documents for generating examples
├── base_template.html                 # Core HTML structure
└── prompt_template.md                 # Legacy: Manual prompt for non-MCP use

Usage Tips

For Best Results:

Provide structure - The more organised your content, the better the output
Specify preferences - Tell the LLM which components/theme you want
Include diagrams - Mermaid diagrams render beautifully
Define sections - Clear section headers help create navigation
Add metadata - Status, dates, authors enhance the visualisation

Example MCP Usage:

Simply ask your AI:

"Use thought-bubble to analyse and visualise this system architecture documentation.
I'd like flowcharts for the workflows and a professional theme with sidebar navigation."

[paste your documentation]

The AI will use the MCP tools to analyse, create diagrams, and generate the complete visualisation.

For manual/legacy prompt method:

Using thought_bubble, create an interactive HTML visualisation of this content.
Theme: Professional
Include: Sidebar navigation, Mermaid diagrams, stat cards, timeline layout

[Your content here]

Customisation

The LLM can customise:

Color schemes and themes
Component selection
Layout structure
Navigation style
Animation intensity
Content organisation

MCP Tools

The thought_bubble MCP server exposes 5 tools for your AI assistant:

`analyze_content`

Analyses documentation to identify visualisation opportunities:

Workflows (processes, sequences, flows)
Systems (architectures, components, services)
Data Models (entities, schemas, objects)
Metrics/KPIs (key performance indicators)

Returns structured analysis with layout recommendations.

`generate_visualization`

Generates complete self-contained HTML with:

13 layout templates (sidebar, magazine, presentation, dashboard, minimal, editorial, comparison, briefing, tutorial, scorecard, report, dossier, dialogue)
Section roles (metric, pull-quote, lead, statement, full-width, supporting)
Density presets (compact, comfortable, spacious)
16+ diagram/chart types (Mermaid + D3)
Advanced chart options (annotations, curve types, color strategies, emphasis effects, patterns)
12 themes with live switching capability
Responsive design for all devices

`generate_mermaid_prompt`

Returns prompt template to help LLMs generate Mermaid diagram code.

`list_themes`

Lists all 12 available themes with their details (name, mode, category, personality).

`get_design_guide`

Retrieves design guide documentation (POV, Typography, Layouts, D3StyleGuide, ColorTheory, Spacing).

Complete MCP documentation: thought_bubble_mcp/README.md | Architecture reference: thought_bubble_mcp/ARCHITECTURE.md

Browser Support

Generated visualisations work in:

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Mobile browsers (iOS, Android)

License

MIT License - Use freely in personal and commercial projects

Credits

Created to make documentation beautiful and accessible.

Contributing

Contributions welcome! We especially value:

MCP server enhancements (new tools, improved analysis)
New component patterns and themes
Example visualisations
Documentation improvements

Submit via PR.

Make your documentation unforgettable.

thought_bubble MCP

What Is This?

See It In Action

16 D3 Chart Types

Layout Templates

Full Examples

How It Works

The MCP Workflow

Alternative: Standalone Prompt Method

Quick Start

MCP Installation (Primary Method)

Quick Test - Try It Now

1. API Integration Documentation

2. Product Roadmap

3. Organisational Structure

Alternative Methods (Without MCP)

What Can You Visualise?

Features

13 Layout Templates

Section Roles

D3 Chart Capabilities

Professional Design

Self-Contained

Chart and Diagram Types

D3 Charts

Mermaid Diagrams

Gantt Chart: Project Timeline

Sequence Diagram: Order Processing

User Journey: Onboarding Experience

Flowchart: User Registration Flow

State Diagram: Order Lifecycle

Files in This Repo

Usage Tips

For Best Results:

Example MCP Usage:

Customisation

MCP Tools

analyze_content

generate_visualization

generate_mermaid_prompt

list_themes

get_design_guide

Browser Support

License

Credits

Contributing

Reviews (0)

`analyze_content`

`generate_visualization`

`generate_mermaid_prompt`

`list_themes`

`get_design_guide`