MCP 브레인스토밍 서버

대화형 AI 지원 브레인스토밍, 계획 및 시각화를 위한 가볍고 리소스 효율적인 로컬호스트 UI를 생성하는 MCP(Model Context Protocol) 서버입니다. 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 (가벼운 HTTP 서버를 위한 Flask/FastAPI)

• 프론트엔드 렌더링:

  • 다이어그램: 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 에이전트 친화적: 쉬운 파싱 및 연속성을 위한 구조화된 응답 형식

• 시각적 명확성: 마크다운/머메이드 렌더링을 통한 UI 섹션의 명확한 구분

향후 개선 사항

• 영구 세션 기록

• 실시간 협업 (향후 다중 사용자 지원)

• 브레인스토밍 템플릿을 위한 사용자 지정 Tailwind 구성 요소 라이브러리

• 다양한 형식(PDF, PNG 등)으로의 내장 내보내기

• 자동 계획 버전 관리를 위한 git 통합

라이선스

MIT

기여

기여를 환영합니다. Python 코드에 대해 PEP 8을 준수하고 서버가 가볍게 유지되도록 해주세요.