# MCP Brainstorm Server

An MCP (Model Context Protocol) server that spawns a lightweight, resource-efficient localhost UI for interactive AI-assisted brainstorming, planning, and visualization. Designed to work seamlessly with Claude and other AI agents for collaborative ideation workflows.

## What It Does

### Core Workflow
1. **Detection**: When you mention brainstorming keywords (brainstorm, plan, think, how do...), the AI agent asks if you want to use the interactive UI
2. **Launch**: Server starts on localhost with a session-specific URL
3. **Interaction**: Render brainstorming materials using mermaid diagrams or Tailwind-styled HTML UI
4. **Submission**: Users interact with clickable buttons, input comments, and optionally upload/paste images
5. **Retrieval**: AI agent reads submitted responses to continue work
6. **Documentation**: Optional saving to `plans/*.md` for future reference

### Features

- **Multi-Session Support**: Each AI agent session gets its own URL (`localhost:{port}/{sessionid}`) with tab names reflecting working directory for easy distinction
- **Shared Single Install Across Agents**: One local clone and one Python environment can be reused by Claude, Codex, and other MCP-compatible agents at the same time, so you install once per machine instead of once per agent
- **Rich Content Rendering**:
  - Mermaid diagrams for graphs, flowcharts, and visualizations
  - Tailwind CSS-styled UI for brainstorming options and interfaces
  - Markdown-compatible format renderer with embedded diagrams and tables
  
- **Interactive Elements**:
  - Auto-generated IDs for sections and options (for easy reference)
  - Clickable buttons for user choices
  - Inline comment input fields
  - Submit/Done workflow
  
- **Image Support**: 
  - Local file upload via file picker
  - Internet-accessible URLs
  - Clipboard paste-in capability
  
- **Resource Efficient**: Lightweight Python server designed for single-user operation
- **Loopback Only**: The HTTP UI is hard-limited to loopback addresses and rejects non-local clients

## Architecture

### Components

```
├── mcp_server.py          # MCP server implementation (Python)
├── server/                # localhost UI server
│   ├── app.py            # Flask/FastAPI server
│   ├── templates/        # HTML templates
│   └── static/           # CSS, JS, assets
└── requirements.txt      # Dependencies
```

Runtime data is stored outside the repository by default under `~/.mcp/brainstorm-mcp/`:

```text
~/.mcp/brainstorm-mcp/
├── sessions/             # Session state storage
│   └── assets/           # Uploaded or pasted image data
├── plans/                # User-saved markdown plans
└── preferences/          # Brainstorm preferences (instructions to the AI)
    ├── global.json       # Machine-wide defaults
    └── projects/         # Per-project overrides, keyed by hashed absolute path
```

Per-project preferences live under the central data root (never inside the
project repo), so configuring a project never adds files to that project's
working tree.

### Session Management

- Each session gets a unique `sessionid` (UUID or similar)
- Session state stored in lightweight persistent storage under the user's `~/.mcp/brainstorm-mcp/` directory by default
- URLs: `localhost:PORT/{sessionid}`
- Tab titles reflect the working directory (`pwd`) of the AI agent terminal

## Tech Stack

- **MCP Framework**: Python MCP SDK
- **Backend**: Python (Flask/FastAPI for lightweight HTTP server)
- **Frontend Rendering**:
  - **Diagrams**: Mermaid.js
  - **UI/Styling**: Tailwind CSS
  - **Markdown**: Compatible format with embedded Mermaid support
- **Storage**: JSON/SQLite (minimal, for session state)

## Installation & Usage

### Prerequisites
- Python 3.9+
- MCP client (Claude or compatible AI agent)

### Full Installation Guide

For complete installation instructions, including:

- using an existing local clone
- cloning into the recommended shared MCP server location
- connecting the server to Codex
- connecting the server to Claude Code
- reusing one install across multiple agents

See [INSTALL.md](INSTALL.md).

### Setup
```bash
git clone <repo-url>
cd mcp-brainstorm-server
pip install -r requirements.txt
```

### Running the Server
The server is started on-demand by the MCP tool when the AI agent detects brainstorming keywords. Users can also manually start it:

```bash
python mcp_server.py
```

### Expected Dependencies
```
anthropic-mcp
flask  # or fastapi
pydantic
python-dotenv
```

## Protocol Flow

### Example: Planning a Feature

1. **User**: "Let me brainstorm the architecture for this feature"
2. **AI Agent**: Detects keyword → Asks "Should I open the interactive brainstorming UI?"
3. **User**: "Yes"
4. **Server**: Launches at `localhost:8080/abc-def-123-ghi` (sessionid based on pwd)
5. **UI**: Renders mermaid diagram of possible architectures with clickable options, comment fields, and image upload area
6. **User**: Clicks preferred architecture option, adds comments, optionally uploads a reference diagram
7. **User**: Clicks "Submit"
8. **Server**: Stores submission under sessionid
9. **User**: Returns to AI agent and says "response submitted"
10. **AI Agent**: Retrieves submission via MCP → Continues planning with the user's input
11. **AI Agent** (optional): "Should I save this plan? Suggested location: `plans/feature-architecture.md`"
   Default saved location on disk: `~/.mcp/brainstorm-mcp/plans/feature-architecture.md`

## MCP Tool Specification

### Available Tools

#### `start_brainstorm_session`
Starts an interactive brainstorming UI session.

**Input**:
- `prompt` (str): Initial brainstorming prompt/context
- `content_type` (str): `"mermaid"`, `"html"`, or `"markdown"`
- `working_dir` (str, optional): Current working directory (used for tab title)

**Output**:
- `session_id` (str): Unique session identifier
- `url` (str): Full localhost URL to access the UI
- `port` (int): Port number used

#### `get_session_response`
Retrieves user submission from a completed session.

**Input**:
- `session_id` (str): Session identifier

**Output**:
- `response` (dict): User's submitted choices, comments, and images
- `timestamp` (str): When submission occurred
- `status` (str): `"pending"`, `"submitted"`, `"expired"`

#### `list_sessions`
Lists all active sessions.

**Output**:
- `sessions` (list): Array of active session objects with IDs, URLs, and creation times

#### `close_session`
Terminates and cleans up a session.

**Input**:
- `session_id` (str): Session to close

#### `set_brainstorm_preferences`
Saves user-facing instructions that shape how the AI brainstorms. Any field left
unset preserves the prior value, so you can update one field at a time.

**Input**:
- `scope` (str): `"global"` (machine-wide default) or `"project"` (override for
  one project — requires `project_path`)
- `project_path` (str, optional): Absolute path to the project. Required when
  `scope="project"`. Used as the lookup key; the file itself is stored centrally
  under `~/.mcp/brainstorm-mcp/preferences/projects/`.
- `uiux_level` (str, optional): User's UI/UX skill level (free text). Suggested
  values: `never_before`, `amateur`, `intermediate`, `expert`.
- `uiux_style` (str, optional): Project's UI/UX style (free text). Examples:
  `corporate internal tool`, `marketing-heavy landing page`,
  `children education app`.
- `questioning_style` (str, optional): How the AI should question the user.
  Suggested values: `autonomous_review` (AI builds, user reviews with as few
  questions as possible) or `collaborative_stepwise` (AI brainstorms step by
  step, asking many questions to converge on the imagined UI).

**Output**: Effective preferences after the merge (project overrides global,
field by field), plus the source of each field.

#### `get_brainstorm_preferences`
Reads the effective brainstorm preferences. Project values override global
values field by field.

**Input**:
- `project_path` (str, optional): Absolute project path to merge into the global
  defaults. Omit to read globals only.

**Output**: Same shape as `set_brainstorm_preferences`. The AI also receives
this object inline on every `start_brainstorm_session` response, so it never
needs to ask twice.

## Design Principles

- **Minimal Resource Usage**: Single-user operation, no heavy dependencies
- **Stateless Where Possible**: Sessions are ephemeral unless saved to disk
- **Ease of Reference**: Auto-generated IDs on all interactive elements
- **AI-Agent Friendly**: Structured response format for easy parsing and continuation
- **Visual Clarity**: Clear separation of UI sections with markdown/mermaid rendering

## Future Enhancements

- Persistent session history
- Real-time collaboration (future multi-user support)
- Custom Tailwind component library for brainstorming templates
- Built-in export to various formats (PDF, PNG, etc.)
- Integration with git for automatic plan versioning

## License

MIT

## Contributing

Contributions welcome. Please follow PEP 8 for Python code and ensure the server remains lightweight.