Servidor MCP de Brainstorming

Un servidor MCP (Model Context Protocol) que lanza una interfaz de usuario ligera y eficiente en recursos en localhost para sesiones interactivas de brainstorming, planificación y visualización asistidas por IA. Diseñado para funcionar perfectamente con Claude y otros agentes de IA para flujos de trabajo de ideación colaborativa.

¿Qué hace?

Flujo de trabajo principal

1. Detección: Cuando mencionas palabras clave de brainstorming (brainstorm, plan, think, how do...), el agente de IA pregunta si deseas usar la interfaz de usuario interactiva.

2. Lanzamiento: El servidor se inicia en localhost con una URL específica para la sesión.

3. Interacción: Renderiza materiales de brainstorming usando diagramas mermaid o una interfaz HTML con estilo Tailwind.

4. Envío: Los usuarios interactúan con botones clicables, introducen comentarios y, opcionalmente, suben o pegan imágenes.

5. Recuperación: El agente de IA lee las respuestas enviadas para continuar con el trabajo.

6. Documentación: Guardado opcional en plans/*.md para referencia futura.

Related MCP server: tldraw-mcp

Características

• Soporte multi-sesión: Cada sesión de agente de IA obtiene su propia URL (localhost:{port}/{sessionid}) con nombres de pestaña que reflejan el directorio de trabajo para una fácil distinción.

• Instalación única compartida entre agentes: Un clon local y un entorno Python pueden ser reutilizados por Claude, Codex y otros agentes compatibles con MCP al mismo tiempo, por lo que instalas una vez por máquina en lugar de una vez por agente.

• Renderizado de contenido enriquecido:

  • Diagramas Mermaid para gráficos, diagramas de flujo y visualizaciones.

  • Interfaz de usuario con estilo Tailwind CSS para opciones e interfaces de brainstorming.

  • Renderizador de formato compatible con Markdown con diagramas y tablas integrados.

• Elementos interactivos:

  • IDs generados automáticamente para secciones y opciones (para una fácil referencia).

  • Botones clicables para las elecciones del usuario.

  • Campos de entrada de comentarios en línea.

  • Flujo de trabajo de Enviar/Listo.

• Soporte de imágenes:

  • Carga de archivos locales mediante selector de archivos.

  • URLs accesibles desde Internet.

  • Capacidad de pegar desde el portapapeles.

• Eficiente en recursos: Servidor Python ligero diseñado para operación de un solo usuario.

• Solo Loopback: La interfaz de usuario HTTP está estrictamente limitada a direcciones de loopback y rechaza clientes no locales.

Arquitectura

Componentes

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

Los datos de tiempo de ejecución se almacenan fuera del repositorio por defecto en ~/.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

Las preferencias por proyecto residen bajo la raíz de datos central (nunca dentro del repositorio del proyecto), por lo que configurar un proyecto nunca añade archivos al árbol de trabajo de ese proyecto.

Gestión de sesiones

• Cada sesión obtiene un sessionid único (UUID o similar).

• El estado de la sesión se almacena en un almacenamiento persistente ligero bajo el directorio ~/.mcp/brainstorm-mcp/ del usuario por defecto.

• URLs: localhost:PORT/{sessionid}

• Los títulos de las pestañas reflejan el directorio de trabajo (pwd) del terminal del agente de IA.

Stack tecnológico

• Framework MCP: Python MCP SDK

• Backend: Python (Flask/FastAPI para servidor HTTP ligero)

• Renderizado Frontend:

  • Diagramas: Mermaid.js

  • UI/Estilos: Tailwind CSS

  • Markdown: Formato compatible con soporte Mermaid integrado

• Almacenamiento: JSON/SQLite (mínimo, para el estado de la sesión)

Instalación y uso

Requisitos previos

• Python 3.9+

• Cliente MCP (Claude o agente de IA compatible)

Guía de instalación completa

Para obtener instrucciones de instalación completas, incluyendo:

• usar un clon local existente

• clonar en la ubicación recomendada del servidor MCP compartido

• conectar el servidor a Codex

• conectar el servidor a Claude Code

• reutilizar una instalación entre múltiples agentes

Ver INSTALL.md.

Configuración

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

Ejecución del servidor

El servidor es iniciado bajo demanda por la herramienta MCP cuando el agente de IA detecta palabras clave de brainstorming. Los usuarios también pueden iniciarlo manualmente:

python mcp_server.py

Dependencias esperadas

anthropic-mcp
flask  # or fastapi
pydantic
python-dotenv

Flujo del protocolo

Ejemplo: Planificación de una funcionalidad

1. Usuario: "Déjame hacer un brainstorming sobre la arquitectura para esta funcionalidad"

2. Agente de IA: Detecta la palabra clave → Pregunta "¿Debería abrir la interfaz de usuario de brainstorming interactiva?"

3. Usuario: "Sí"

4. Servidor: Se lanza en localhost:8080/abc-def-123-ghi (sessionid basado en pwd)

5. UI: Renderiza un diagrama mermaid de posibles arquitecturas con opciones clicables, campos de comentarios y área de carga de imágenes.

6. Usuario: Hace clic en la opción de arquitectura preferida, añade comentarios, opcionalmente sube un diagrama de referencia.

7. Usuario: Hace clic en "Enviar"

8. Servidor: Almacena el envío bajo el sessionid.

9. Usuario: Regresa al agente de IA y dice "respuesta enviada"

10. Agente de IA: Recupera el envío a través de MCP → Continúa la planificación con la entrada del usuario.

11. Agente de IA (opcional): "¿Debería guardar este plan? Ubicación sugerida: plans/feature-architecture.md" Ubicación guardada por defecto en disco: ~/.mcp/brainstorm-mcp/plans/feature-architecture.md

Especificación de la herramienta MCP

Herramientas disponibles

start_brainstorm_session

Inicia una sesión de interfaz de usuario de brainstorming interactiva.

Entrada:

• prompt (str): Prompt/contexto inicial de brainstorming

• content_type (str): "mermaid", "html" o "markdown"

• working_dir (str, opcional): Directorio de trabajo actual (usado para el título de la pestaña)

Salida:

• session_id (str): Identificador único de sesión

• url (str): URL completa de localhost para acceder a la UI

• port (int): Número de puerto utilizado

get_session_response

Recupera el envío del usuario de una sesión completada.

Entrada:

• session_id (str): Identificador de sesión

Salida:

• response (dict): Elecciones, comentarios e imágenes enviadas por el usuario

• timestamp (str): Cuándo ocurrió el envío

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

list_sessions

Lista todas las sesiones activas.

Salida:

• sessions (list): Matriz de objetos de sesión activos con IDs, URLs y tiempos de creación

close_session

Termina y limpia una sesión.

Entrada:

• session_id (str): Sesión a cerrar

set_brainstorm_preferences

Guarda las instrucciones orientadas al usuario que dan forma a cómo la IA hace brainstorming. Cualquier campo dejado sin establecer conserva el valor anterior, por lo que puedes actualizar un campo a la vez.

Entrada:

• scope (str): "global" (predeterminado para toda la máquina) o "project" (anulación para un proyecto — requiere project_path)

• project_path (str, opcional): Ruta absoluta al proyecto. Requerido cuando scope="project". Se utiliza como clave de búsqueda; el archivo en sí se almacena centralmente bajo ~/.mcp/brainstorm-mcp/preferences/projects/.

• uiux_level (str, opcional): Nivel de habilidad de UI/UX del usuario (texto libre). Valores sugeridos: never_before, amateur, intermediate, expert.

• uiux_style (str, opcional): Estilo de UI/UX del proyecto (texto libre). Ejemplos: corporate internal tool, marketing-heavy landing page, children education app.

• questioning_style (str, opcional): Cómo debe cuestionar la IA al usuario. Valores sugeridos: autonomous_review (la IA construye, el usuario revisa con la menor cantidad de preguntas posible) o collaborative_stepwise (la IA hace brainstorming paso a paso, haciendo muchas preguntas para converger en la UI imaginada).

Salida: Preferencias efectivas después de la fusión (el proyecto anula lo global, campo por campo), más la fuente de cada campo.

get_brainstorm_preferences

Lee las preferencias de brainstorming efectivas. Los valores del proyecto anulan los valores globales campo por campo.

Entrada:

• project_path (str, opcional): Ruta absoluta del proyecto para fusionar con los valores predeterminados globales. Omitir para leer solo los globales.

Salida: Misma forma que set_brainstorm_preferences. La IA también recibe este objeto en línea en cada respuesta de start_brainstorm_session, por lo que nunca necesita preguntar dos veces.

Principios de diseño

• Uso mínimo de recursos: Operación de un solo usuario, sin dependencias pesadas

• Sin estado donde sea posible: Las sesiones son efímeras a menos que se guarden en el disco

• Facilidad de referencia: IDs generados automáticamente en todos los elementos interactivos

• Amigable con agentes de IA: Formato de respuesta estructurado para un fácil análisis y continuación

• Claridad visual: Separación clara de las secciones de la UI con renderizado markdown/mermaid

Mejoras futuras

• Historial de sesiones persistente

• Colaboración en tiempo real (soporte multiusuario futuro)

• Biblioteca de componentes Tailwind personalizada para plantillas de brainstorming

• Exportación integrada a varios formatos (PDF, PNG, etc.)

• Integración con git para el versionado automático de planes

Licencia

MIT

Contribución

Las contribuciones son bienvenidas. Por favor, sigue PEP 8 para el código Python y asegúrate de que el servidor permanezca ligero.