MCP Brainstorm 服务器

一个 MCP (Model Context Protocol) 服务器，可启动轻量级、资源高效的本地主机 UI，用于交互式 AI 辅助头脑风暴、规划和可视化。旨在与 Claude 及其他 AI 代理无缝协作，实现协作式构思工作流。

功能概述

核心工作流

1. 检测：当您提到头脑风暴关键词（brainstorm, plan, think, how do...）时，AI 代理会询问您是否要使用交互式 UI

2. 启动：服务器在本地主机上启动，并提供特定于会话的 URL

3. 交互：使用 Mermaid 图表或 Tailwind 样式的 HTML UI 渲染头脑风暴材料

4. 提交：用户通过可点击按钮进行交互、输入评论，并可选择上传/粘贴图像

5. 检索：AI 代理读取提交的响应以继续工作

6. 文档记录：可选择保存到 plans/*.md 以供将来参考

特性

• 多会话支持：每个 AI 代理会话都有自己的 URL (localhost:{port}/{sessionid})，标签页名称反映工作目录，便于区分

• 跨代理共享单次安装：一个本地克隆和一个 Python 环境可同时被 Claude、Codex 和其他兼容 MCP 的代理重复使用，因此每台机器只需安装一次，而不是每个代理安装一次

• 富内容渲染：

  • 用于图表、流程图和可视化的 Mermaid 图表

  • 用于头脑风暴选项和界面的 Tailwind CSS 样式 UI

  • 兼容 Markdown 的格式渲染器，支持嵌入式图表和表格

• 交互式元素：

  • 自动生成的章节和选项 ID（便于引用）

  • 可点击的用户选择按钮

  • 内联评论输入字段

  • 提交/完成工作流

• 图像支持：

  • 通过文件选择器进行本地文件上传

  • 支持互联网可访问的 URL

  • 支持剪贴板粘贴

• 资源高效：专为单用户操作设计的轻量级 Python 服务器

• 仅限回环：HTTP UI 被严格限制在回环地址，拒绝非本地客户端

Related MCP server: tldraw-mcp

架构

组件

├── 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

运行时数据默认存储在存储库之外的 ~/.mcp/brainstorm-mcp/ 下：

~/.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

每个项目的偏好设置位于中央数据根目录下（绝不在项目仓库内），因此配置项目永远不会向该项目的工作树添加文件。

会话管理

• 每个会话都有一个唯一的 sessionid（UUID 或类似值）

• 会话状态默认存储在用户 ~/.mcp/brainstorm-mcp/ 目录下的轻量级持久存储中

• URL：localhost:PORT/{sessionid}

• 标签页标题反映 AI 代理终端的工作目录 (pwd)

技术栈

• MCP 框架：Python MCP SDK

• 后端：Python (Flask/FastAPI，用于轻量级 HTTP 服务器)

• 前端渲染：

  • 图表：Mermaid.js

  • UI/样式：Tailwind CSS

  • Markdown：兼容格式，支持嵌入式 Mermaid

• 存储：JSON/SQLite（最小化，用于会话状态）

安装与使用

先决条件

• Python 3.9+

• MCP 客户端（Claude 或兼容的 AI 代理）

完整安装指南

有关完整的安装说明，包括：

• 使用现有的本地克隆

• 克隆到推荐的共享 MCP 服务器位置

• 将服务器连接到 Codex

• 将服务器连接到 Claude Code

• 在多个代理之间重复使用一次安装

请参阅 INSTALL.md。

设置

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

运行服务器

当 AI 代理检测到头脑风暴关键词时，MCP 工具会按需启动服务器。用户也可以手动启动它：

python mcp_server.py

预期依赖

anthropic-mcp
flask  # or fastapi
pydantic
python-dotenv

协议流程

示例：规划功能

1. 用户：“让我们为这个功能构思架构”

2. AI 代理：检测到关键词 → 询问“我应该打开交互式头脑风暴 UI 吗？”

3. 用户：“是的”

4. 服务器：在 localhost:8080/abc-def-123-ghi 启动（基于 pwd 的 sessionid）

5. UI：渲染可能架构的 Mermaid 图表，包含可点击选项、评论字段和图像上传区域

6. 用户：点击首选架构选项，添加评论，并可选择上传参考图

7. 用户：点击“提交”

8. 服务器：将提交内容存储在 sessionid 下

9. 用户：返回 AI 代理并说“响应已提交”

10. AI 代理：通过 MCP 检索提交内容 → 使用用户的输入继续规划

11. AI 代理（可选）：“我应该保存这个计划吗？建议位置：plans/feature-architecture.md” 磁盘上的默认保存位置：~/.mcp/brainstorm-mcp/plans/feature-architecture.md

MCP 工具规范

可用工具

start_brainstorm_session

启动交互式头脑风暴 UI 会话。

输入：

• prompt (str)：初始头脑风暴提示/上下文

• content_type (str)："mermaid", "html" 或 "markdown"

• working_dir (str, 可选)：当前工作目录（用于标签页标题）

输出：

• session_id (str)：唯一会话标识符

• url (str)：访问 UI 的完整本地主机 URL

• port (int)：使用的端口号

get_session_response

从已完成的会话中检索用户提交的内容。

输入：

• session_id (str)：会话标识符

输出：

• response (dict)：用户提交的选择、评论和图像

• timestamp (str)：提交发生的时间

• status (str)："pending", "submitted", "expired"

list_sessions

列出所有活动会话。

输出：

• sessions (list)：包含 ID、URL 和创建时间的活动会话对象数组

close_session

终止并清理会话。

输入：

• session_id (str)：要关闭的会话

set_brainstorm_preferences

保存指导 AI 如何进行头脑风暴的用户指令。任何未设置的字段都会保留先前的值，因此您可以一次更新一个字段。

输入：

• scope (str)："global"（全机默认）或 "project"（单个项目覆盖 — 需要 project_path）

• project_path (str, 可选)：项目的绝对路径。当 scope="project" 时必需。用作查找键；文件本身集中存储在 ~/.mcp/brainstorm-mcp/preferences/projects/ 下。

• uiux_level (str, 可选)：用户的 UI/UX 技能水平（自由文本）。建议值：never_before, amateur, intermediate, expert。

• uiux_style (str, 可选)：项目的 UI/UX 风格（自由文本）。示例：corporate internal tool, marketing-heavy landing page, children education app。

• questioning_style (str, 可选)：AI 应该如何向用户提问。建议值：autonomous_review（AI 构建，用户以尽可能少的问题进行审查）或 collaborative_stepwise（AI 逐步进行头脑风暴，提出许多问题以收敛到设想的 UI）。

输出：合并后的有效偏好设置（项目覆盖全局，逐字段），以及每个字段的来源。

get_brainstorm_preferences

读取有效的头脑风暴偏好设置。项目值逐字段覆盖全局值。

输入：

• project_path (str, 可选)：要合并到全局默认值中的绝对项目路径。省略则仅读取全局设置。

输出：与 set_brainstorm_preferences 形状相同。AI 也会在每次 start_brainstorm_session 响应中内联接收此对象，因此无需重复询问。

设计原则

• 最小资源使用：单用户操作，无繁重依赖

• 尽可能无状态：除非保存到磁盘，否则会话是短暂的

• 易于引用：所有交互元素上自动生成的 ID

• AI 代理友好：结构化的响应格式，便于解析和继续

• 视觉清晰：通过 markdown/mermaid 渲染清晰区分 UI 区域

未来增强

• 持久会话历史

• 实时协作（未来的多用户支持）

• 用于头脑风暴模板的自定义 Tailwind 组件库

• 内置导出为各种格式（PDF, PNG 等）

• 与 git 集成以实现自动计划版本控制

许可证

MIT

贡献

欢迎贡献。请遵循 Python 代码的 PEP 8 规范，并确保服务器保持轻量级。