Butler MCP 서버
MCP 서버를 등록하고, 어시스턴트로 묶어 AI 챗봇을 만들 수 있습니다.
Butler Chat — 웹 채팅 (새 탭)
이 시스템은 계정 분산식으로 운영됩니다. 각자 자신의 AI API 키를 입력해 주세요.
문서 분석에는 요청자의 키가, 어시스턴트 응답에는 제작자의 키가 사용됩니다.
AI 업체 & API 키
config.llm_secrets에 AES-256-GCM 암호화되어 저장됩니다.
마스터 키 소스: 환경 변수 BUTLER_SECRETS_KEY(권장) 또는 자동 생성 data/.butler-secrets-key.환경 변수
OPENAI_API_KEY 등은 항상 우선합니다.모델 목록은 서버 기동 시 벤더 API(
GET /v1/models 등)에서 자동으로 가져옵니다.
키를 나중에 넣었다면 서버를 재시작하거나 모델 목록 갱신을 눌러주세요.
키 등록·삭제할 제공자 선택
분석 설정
이미지·문서 분석, 텍스트 정제에 사용되는 모델
미설정 시 응답용 제공자를 따릅니다
이미지 장변 최대 픽셀. 큰 이미지만 축소하며 작은 이미지는 원본 유지
응답 설정
챗봇·플레이그라운드 대화에 사용되는 모델
서브 응답 모델·연속 세션 런타임은 계정 공통이 아니라 어시스턴트마다입니다. 콘솔 상단 탭 「어시스턴트」 → 카드를 열거나 새 어시스턴트 폼에서 JSON·체크박스로 설정합니다.
환경 변수로 모델 덮어쓰기:
OPENAI_PLAYGROUND_MODEL, ANTHROPIC_CHAT_MODEL, GEMINI_MODEL /
분석: OPENAI_ANALYSIS_MODEL, ANTHROPIC_ANALYSIS_MODEL, GOOGLE_ANALYSIS_MODEL
MCP 서버 만들기
아래 4가지 방법 중 하나로 새 MCP 서버를 등록할 수 있습니다. 등록된 항목은 다음 카드의 카탈로그에서 검색·관리합니다.
등록된 MCP 서버
문서 MCP(document-mcp-runner) 카드는 본문을 클릭하거나
문서 보강을 누르면 파일·텍스트 추가·figure 삭제 등 패키지 갱신을 모달로 엽니다.
같은 창은 generated-mcp 표에서 패키지 행을 눌러도 열 수 있습니다.
조건에 맞는 MCP 서버가 없습니다. 검색어나 필터를 조정해보세요.
문서에서 MCP 서버 만들기
파일·본문을 추출한 뒤, LLM 활용 레벨에 따라 보강 범위를 정합니다.
PDF 임베드 이미지·업로드 이미지는 generated-mcp/<uuid>/images/에 PNG로 항상
저장됩니다.
여러 파일을 한 번에 선택하거나, 아래 점선 영역에 끌어다 놓을 수 있습니다.
비로그인으로 생성하면 항상 Public으로 등록됩니다.
켜면 다른 인증된 creator 도 본문·도구·메타를 _덮어쓸_ 수 있습니다. 삭제와 이 옵션 자체는 소유자·관리자만 변경할 수 있습니다.
끄면 저장용 도구는 그대로 노출되며, 호출 시 저장 불가 안내만 반환됩니다.
—
선택한 문서 패키지 — 갱신·삭제
에 대해 PDF·이미지 추가, 본문 이어 붙이기, figure
삭제, 제목 변경, LLM으로 저장된 본문 보정(프롬프트)을 할 수 있습니다. 위쪽
등록된 MCP 서버 그리드에서 해당 문서 MCP 카드를 선택해도 이
폼이 열립니다. PUT /api/mcp-generate/document/:packageId ·
DELETE …?unlinkCatalog=true
카탈로그에 등록된 문서 MCP가 있을 때만 반영됩니다. 편집 권한이 없으면 비활성화됩니다.
여러 파일을 한 번에 선택하거나, 아래 점선 영역에 끌어다 놓을 수 있습니다 (순서대로 이어 붙습니다).
비우면 이 칸은 무시되고, 파일·추가 본문·제목만 반영됩니다. 내용이 있으면
문서 편집·보정 전용 LLM이 한 번에 해석합니다 — 오류 수정, 구간만 고치기, figure 삭제, 제목 변경 등.
추가 본문·파일이 있으면 먼저 합친 뒤 보정이 적용됩니다.
한편 패키지를 처음 만들 때 붙는 ## 문서 요약 형식·톤은
서버의 종합 분석 시스템 프롬프트(소스 src/mcp/extractDocumentText.ts 기본값,
또는 환경변수 BUTLER_FULL_DOCUMENT_DIGEST_SYSTEM으로 덮어쓰기)가 정합니다.
이미 저장된 요약 문장만 고치려면 이 칸에 지시하면 되고, 생성 규칙 전체를 바꾸려면 그 프롬프트를 손보세요.
분석용 모델이 잡히지 않았습니다. 분산 모드는 시스템 설정의 분석용 API 키, 중앙 모드는 관리자 LLM 설정의 분석용 키·모델을 확인한 뒤 이 기능을 사용할 수 있습니다.
새 MCP 서버
패키지 목록
카탈로그에서 MCP 서버를 삭제해도 data/generated-mcp/ 폴더는 남을 수 있습니다.
고아 패키지는 복원 가능하고, 잔여 폴더는 삭제만 됩니다.
로컬 PC 제어 MCP 생성
셸 명령·앱 제어·시스템 정보 등 로컬 PC를 제어하는 커스텀 MCP 스크립트를 생성합니다
고급 설정
다운로드된 shell-mcp-runner.mjs가 있는 폴더에서
npm init -y && npm install @modelcontextprotocol/sdk zod 후
node shell-mcp-runner.mjs로 실행하세요.
PKM 페이지 MCP 생성
선택한 PKM 페이지 묶음을 MCP 서버 하나로 등록합니다. 공개 범위는 이 MCP 의 읽기 접근을 결정하고, 변경 제안은 제작자·관리자에게만 열립니다.
새 PKM MCP 만들기
이름, 공개 범위, 포함 페이지를 정하면 MCP 카탈로그에 서버가 하나 추가됩니다.
고급 설정
LLM 에 노출할 페이지 제목 목록의 상한. 100~300 권장.
특정 PKM 인스턴스를 직접 지정할 때만 입력합니다.
체크박스로 개별 페이지를 고르거나 하위 토글로 서브트리 전체를 포함합니다.
PKM 페이지 MCP 수정
포함 페이지와 읽기 공개 범위를 바꾸면 연결된 MCP 카탈로그 항목도 함께 갱신됩니다.
고급 설정
체크박스로 개별 페이지를 고르거나 하위 토글로 서브트리 전체를 포함합니다.
어시스턴트 관리
여러 MCP 서버를 묶어 어시스턴트를 만들면, 임베드 챗봇·POST /api/bot-groups/:id/chat 등에서
같은 assistantId 로 쓸 수 있습니다. (예: PKM 페이지 챗·페이지 생성 AI·향후 회의록 UI.)
서브 응답 모델·연속 세션은 아래에서 편집하는 각 어시스턴트 설정에 붙습니다.
플레이그라운드 응답 LLM
이 탭 시험 채팅에만 적용됩니다. 계정 기본과 다르게 시험할 때만 지정하세요.
MCP 서버 채팅 (시험)
아래에서 시험에 쓸 MCP 서버를 필요한 것만 체크한 뒤 질문하세요. 기본은 모두 해제입니다. 선택한 순서가
s0, s1, … 도구 이름 접두사와 같습니다. 도구가 있을 때는
보내는 메시지마다 최소 한 번 연결된 MCP 서버의 도구 호출이 강제되어, 일반
상식만으로 문서 내용을 대신 말하는 일을 줄입니다. OpenAI 키가 필요하며 모델은
OPENAI_PLAYGROUND_MODEL로 바꿀 수 있습니다(관리 화면·파일 기본은
gpt-5.4-nano).
답변·내 메시지는 마크다운(코드 블록, 표, 링크 등)과 안전하게 허용된
HTML로 표시됩니다.
—
임베드 코드 생성
외부 사이트에 챗봇을 삽입할 수 있는 코드를 생성합니다. 어시스턴트를 선택하고 스타일을 고른 뒤 다운로드하세요.
비워두면 현재 서버 주소를 사용합니다. 외부 도메인에서 사용 시 서버의 CORS 설정에 해당 도메인을 허용해야 합니다.
사용자 관리
콘솔에 접근할 수 있는 사용자를 관리합니다. admin: 모든 기능, creator: MCP/어시스턴트 제작·수정, user: 읽기·사용만 가능
새 사용자
수정 시 비워두면 기존 비밀번호를 유지합니다.
새 어시스턴트
MCP 서버를 선택하고, 이름과 설명을 입력하세요. 시스템 프롬프트를 지정하면 기본 도입 문구가 교체됩니다.
동일 assistantId 는 여러 제품 화면에서 재사용할 수 있습니다.
시스템 관리와 동일한 모델 카탈로그에서 선택합니다. STT·이미지 등 역할별로 목록이 좁혀지며, 행을 추가/삭제하세요.
(페이지 챗·페이지 생성·향후 회의록 UI 등 assistantId 만 같으면 동일 설정을 재사용할 수 있습니다.)
고급: JSON 직접 편집
켜면 다른 인증된 creator 도 시스템 프롬프트·MCP 구성을 _덮어쓸_ 수 있습니다. 삭제·공개 범위·이 옵션 자체는 여전히 소유자·관리자만 변경할 수 있습니다.
—
이 어시스턴트 응답 LLM
계정 「응답 설정」과 다른 프로바이더·모델을 쓰려면 아래에서 지정하세요. 체크 시 오버라이드를 비우고 계정과 동일하게 맞춥니다.
도우미 (공개 채팅) 설정
POST /api/bot-groups/:id/chat 호출(웹 임베드·butler-bot 등)에 적용됩니다.
비활성화 시 해당 API가 거절됩니다. 한도는 UTC 자정 기준으로,
요청에 X-Butler-Rate-Client-Key(본문이 아니라 헤더: 사용자 식별 문자열의 SHA-256 64자 hex)가 있으면 그 값으로 집계하고,
없으면 연결 IP로 집계합니다. butler-bot은 Teams 사용자·웹 방문자 IP+닉네임 등으로 이 헤더를 붙입니다.
0 = 무제한(기본값). 1 이상이면 같은 식별자(위 헤더 또는 IP)당 하루에 그만큼의 /chat 요청만 허용합니다.