Calypso 멀티모달 RAG MCP 서버

Claude Desktop, Cursor 및 에이전트 워크플로우를 위한 가장 쉬운 호스팅형 멀티모달 RAG MCP 서버

단 하나의 npx 명령어. Gemini File Search 기반. PDF, 스크린샷, 차트, 다이어그램, 이미지를 기본적으로 처리하며 검증 가능한 인용을 제공합니다.

Claude, Cursor, Windsurf 및 커스텀 에이전트에 호스팅형 멀티모달 RAG를 추가하는 가장 쉬운 방법입니다.

• 초간단 설정: npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-your-key-here

• 진정한 멀티모달 RAG: Gemini File Search를 통해 텍스트와 시각 자료를 기본적으로 처리

• 업로드 및 질의: 지속적인 지식 파일과 일괄 업로드를 위한 전용 도구

• 다중 턴 대화: /new 리셋으로 컨텍스트를 인식하는 답변

• 발견 가능한 워크플로우: 안전한 RAG, 업로드, 수집 흐름을 위한 리소스와 프롬프트

GitHub | Docs | Smithery | 공식 MCP 레지스트리

태그: multimodal-rag, easiest-mcp-rag, gemini-rag, hosted-rag-mcp, mcp-server

각 에이전트나 워크플로우를 일회성 문서 검색 스택에 연결하는 대신, 이 MCP를 에이전트가 접근하는 진입점으로 사용하여 하나의 재사용 가능한 답변 레이어를 구축하세요: 소스 자료를 한 번 업로드하고, 텍스트와 시각 콘텐츠 전반에서 검색하며, 사용자가 검증할 수 있는 증거와 함께 답변을 반환합니다.

빠른 시작 (가장 쉬운 방법)

# One-liner with npx
npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-your-key-here"

또는 환경 변수 사용:

CALYPSO_API_KEY="sk-..." npx -y @calypsohq/multimodal-rag-mcp-server

그런 다음 아래 구성 예시를 사용하여 Claude Desktop, Cursor 또는 Smithery에 동일한 명령을 추가하세요.

Related MCP server: RAG-Anything MCP Server

Calypso를 선택해야 하는 이유

Calypso는 가장 쉬운 호스팅형 멀티모달 RAG MCP 서버를 원하는 팀을 위해 설계되었습니다. 로컬 벡터 스택, Docker Compose, 또는 에이전트가 근거 기반 질문을 하기 전에 커스텀 OCR이나 이미지 처리 파이프라인이 필요 없습니다.

가장 쉬운 호스팅형 멀티모달 RAG MCP 서버를 원한다면 여기서 시작하세요.

제공되는 기능

• 다중 턴 메모리를 갖춘 프로덕션 멀티모달 RAG 에이전트

• 단일 파일 및 일괄 지식 업로드를 위한 내장 업로드 도구

• 팀의 RAG 변형 및 지식 버킷 자동 검색

• 소스 참조 및 검색 메타데이터가 포함된 검증 가능한 인용

• 안전한 워크플로우를 위한 읽기 전용 리소스 및 재사용 가능한 프롬프트

멀티모달 우선 RAG가 필요한 이유

대부분의 회사 지식은 텍스트만 있는 것이 아닙니다. 답은 종종 설정 스크린샷, PDF 표, 제품 다이어그램, 헬프센터 페이지, 또는 보고서 내 차트에 걸쳐 있습니다. Calypso는 전체 지식 표면을 단일 검색 레이어로 패키징하여 에이전트가 일반 모델 메모리에서 추측하지 않고 근거 기반 질문을 할 수 있게 합니다.

• 사용자가 실제로 의존하는 형식 검색: 문서, PDF, 스크린샷, 차트, 다이어그램, 제품 이미지, 지원 문서, 매뉴얼, 정책, FAQ, 보고서.

• 모델이 작성하기 전에 답변의 근거를 마련: Gemini File Search가 먼저 관련 텍스트와 시각적 컨텍스트를 검색한 다음, RAG 에이전트가 해당 소스 자료에서 답변합니다.

• 증거 추적 표시: 응답에 소스 참조, 페이지 인식 근거, 검색 메타데이터를 포함하여 사용자가 신뢰하기 전에 검증할 수 있습니다.

• 메타데이터로 검색 범위 지정: 워크스페이스, 팀, 고객, 언어, 파일 유형, 상태 또는 기타 메타데이터를 사용하여 지식 베이스를 중복하지 않고 관련성 있는 답변을 유지합니다.

• 동일한 지식 레이어를 어디서나 재사용: Cursor, Claude Desktop, AI 에이전트, n8n 워크플로우, 제품 UI, 지원 흐름, 웹사이트 경험을 동일한 소스 기반 레이어에 연결합니다.

실제로 이는 에이전트가 다음과 같은 질문에 답할 수 있음을 의미합니다:

• "이 설정 스크린샷과 첨부된 정책 PDF를 설명해 주세요. 지원 담당자는 다음에 무엇을 해야 하나요?"

• "이 온보딩 PDF가 승인 규칙에 대해 뭐라고 하나요?"

• "이 설정 화면이 왜 실패하나요?"

• "가격 차트를 우리 플랜 문서와 비교하고 적절한 등급을 추천해 주세요."

• "이 지원 티켓에 적용되는 정책을 요약해 주세요."

• "가격 문서에 따르면 이 고객에게 어떤 제품 플랜이 맞나요?"

• "다이어그램으로 표현된 수집 흐름을 검색 흐름과 비교해 주세요."

이 MCP가 하는 일

calypso-rag-agent를 사용하면 다음을 할 수 있습니다:

• 구성된 Calypso 지식 베이스에 대해 근거 기반 질문하기

• 선택적 model 인수로 발견된 팀 RAG 변형 선택

• 네이티브 /v1/responses 대화 모델을 통한 다중 턴 대화 계속

• /new로 대화 컨텍스트 리셋

• calypso-rag-agent를 제공하는 동일한 OpenAI 호환 Responses 엔드포인트 사용

• 지원되는 Calypso 워크플로우를 위한 내장 리소스 및 프롬프트 검색

요구 사항

• Node.js 18+

• 서버는 API 호출 및 SDK 호환성을 위해 Web Fetch API 기본 요소(fetch, Headers, Request, Response, FormData, Blob, File)를 사용합니다. 패키지는 Node 18+ Web API 표면의 일부만 노출하는 MCP 런타임을 위해 시작 시 누락된 전역을 부트스트랩합니다.

• 다음을 노출하는 Calypso API 엔드포인트:

  • POST /v1/responses

  • GET /v1/rag-agent/models

  • GET /v1/knowledge/buckets

  • POST /v1/knowledge/files/upload-session

  • POST /v1/knowledge/files/upload-session/{session_id}/finalize

  • POST /v1/knowledge/files:batch/upload-session

  • POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize

  • GET /v1/knowledge/batches/{batch_id}

• Calypso API 키 (sk-...)

구성

환경 변수:

• CALYPSO_API_KEY (필수)

• CALYPSO_API_BASE_URL (선택, 기본값 https://api.calypso.so/v1)

CLI 플래그:

• --api-key

• --api-base-url

구성 우선순위:

1. CLI 플래그 / Smithery 제공 명령 인수

2. 환경 변수

3. 기본 베이스 URL (https://api.calypso.so/v1)

npx로 실행

npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-..."

환경 변수로 실행

env CALYPSO_API_KEY="sk-..." CALYPSO_API_BASE_URL="https://api.calypso.so/v1" npx -y @calypsohq/multimodal-rag-mcp-server

Cursor에서 구성

다음과 같이 새 MCP 서버(명령 유형)를 추가하세요:

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

Claude Desktop에서 구성

1. Claude Desktop MCP 구성 열기

Claude Desktop에서:

Claude -> 설정 -> 개발자 -> 구성 편집

macOS에서 파일은 일반적으로:

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop은 데스크톱 MCP 서버에 claude_desktop_config.json을 사용합니다. Claude Code는 ~/.claude.json 또는 프로젝트 수준 .mcp.json과 같은 별도 구성 위치를 사용합니다.

2. Calypso MCP 서버 추가

claude_desktop_config.json에 다음을 붙여넣으세요:

{
  "mcpServers": {
    "Calypso Multimodal RAG": {
      "command": "npx",
      "args": [
        "-y",
        "@calypsohq/multimodal-rag-mcp-server"
      ],
      "env": {
        "CALYPSO_API_KEY": "sk-your-calypso-api-key",
        "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
      }
    }
  }
}

다음을 교체:

• sk-your-calypso-api-key

실제 Calypso API 키로.

3. Claude Desktop 완전히 다시 시작

Claude Desktop을 완전히 종료한 후 다시 엽니다.

창을 닫는 것만으로는 안 됩니다. macOS에서:

Cmd + Q

다시 시작한 후 MCP가 Claude에 나타나며 다음 도구를 사용할 수 있습니다:

• calypso-rag-agent

• calypso-list-buckets

• calypso-upload-file

• calypso-upload-files-batch

선택 사항: Claude 아티팩트를 Mac에 저장

Calypso는 호스팅형 멀티모달 RAG 도구를 제공합니다. 생성된 보고서, 요약, CSV, JSON 파일 또는 웹 검색 아티팩트를 로컬 컴퓨터에 직접 쓰지 않습니다.

Claude Desktop이 생성된 파일을 로컬에 저장하도록 하려면 Calypso와 함께 표준 filesystem MCP 서버를 추가하고 전용 안전 폴더로 제한하세요.

먼저 폴더를 만드세요:

mkdir -p ~/Claude

그런 다음 두 서버를 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "Calypso Multimodal RAG": {
      "command": "npx",
      "args": [
        "-y",
        "@calypsohq/multimodal-rag-mcp-server"
      ],
      "env": {
        "CALYPSO_API_KEY": "sk-your-calypso-api-key",
        "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Claude"
      ]
    }
  }
}

구성을 변경한 후 Claude Desktop을 완전히 종료하고 다시 엽니다.

예시 프롬프트:

Use Calypso for the grounded RAG answer, then save the final report as /Users/yourname/Claude/report.md using the filesystem tool.

안전을 위해 전체 홈 디렉토리가 아닌 ~/Claude와 같은 전용 폴더에만 파일시스템 접근 권한을 부여하세요.

Smithery

서버는 Smithery에서 사용할 수 있으며 데스크톱 클라이언트가 사용하는 동일한 npx 패키지 경로로 시작됩니다.

Smithery 사용자 구성:

• calypsoApiKey (필수)

• calypsoApiBaseUrl (선택, 기본값 https://api.calypso.so/v1)

Smithery 시작 경로는 다음과 동일합니다:

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

셀프 호스팅 Calypso 호환 배포를 대상으로 할 때만 calypsoApiBaseUrl을 사용하세요. 클라우드 기본값은 재정의할 필요가 없습니다.

문제 해결

• API 키 누락: --api-key 또는 CALYPSO_API_KEY를 제공하세요.

• 잘못된 API 호스트: --api-base-url / CALYPSO_API_BASE_URL이 /v1로 끝나는지 확인하세요.

• 셀프 호스팅 배포: https://api.calypso.so/v1을 사용하지 않는 경우에만 기본 URL을 재정의하세요.

• Smithery 실행 불일치: 새 클론에서 node dist/index.js를 실행하는 대신 패키징된 npx -y @calypsohq/multimodal-rag-mcp-server 경로를 사용하세요.

• FormData is not defined 또는 Headers is not defined: 최신 패키지로 업그레이드하세요. MCP 서버는 업로드 도구가 실행되기 전에 누락된 Web Fetch API 전역 변수를 부트스트랩합니다.

• /mnt/user-data/uploads/...에 대한 ENOENT: 해당 경로는 호스팅 에이전트 또는 첨부 파일 샌드박스에 속하며, 반드시 MCP 서버에 속하는 것은 아닙니다. filePath 대신 contentBase64로 다시 시도하세요.

• 로컬 아티팩트 저장: Calypso 답변은 Claude Desktop의 filesystem MCP 서버와 함께 사용할 수 있지만, 최종 출력을 허용된 로컬 경로에 저장하도록 Claude에게 명시적으로 요청해야 합니다.

filePath vs contentBase64 선택

filePath는 로컬 MCP 설치에서 사용하세요. 여기에는 이 패키지를 로컬 명령으로 실행하는 Claude Desktop 및 Cursor 구성이 포함됩니다:

npx -y @calypsohq/multimodal-rag-mcp-server

이 설정에서는 MCP 서버 프로세스가 사용자의 머신에서 실행되며 동일한 사용자 계정이 접근할 수 있는 경로를 읽을 수 있습니다. 로컬 경로를 직접 전달하세요. 서버가 원시 바이트를 읽어 Calypso 업로드 세션 URL을 통해 업로드합니다. 로컬 파일을 base64로 인코딩할 필요가 없습니다.

contentBase64는 호스팅 또는 원격 MCP 클라이언트에서 사용하세요. 여기에는 Smithery 호스팅 서버, 브라우저/클라우드 런타임, 메모리에서 생성된 콘텐츠, 에이전트 컨테이너가 포함됩니다. 이러한 환경에서는 Mac이나 워크스테이션의 경로를 MCP 서버 프로세스가 읽을 수 없습니다.

경로가 /mnt/user-data/uploads, /mnt/data, /mnt/attachments 또는 다른 호스팅 샌드박스 접두사로 시작하는 경우, 이 MCP 서버가 동일한 샌드박스에서 실행 중이 아니라면 filePath로 보내지 마세요. 대신 contentBase64 또는 다른 인라인 바이트 소스를 사용하세요.

사용 가능한 도구

calypso-rag-agent

Calypso RAG 에이전트에 직접 접근합니다.

참고:

• 다른 페르소나나 에이전트로 자동 라우팅하지 않습니다.

• 시작 시 API 키에서 사용 가능한 calypso-rag-agent 변형을 자동으로 발견합니다.

• 선택적 model 인수를 사용해 calypso-rag-agent:pricing 같은 명명된 변형을 선택하세요.

• 각 모델 변형은 자체 MCP 대화 체인을 유지하므로 변형을 전환해도 잘못된 스레드를 이어가지 않습니다.

• POST /v1/chat/completions 대신 POST /v1/responses를 사용합니다.

• 첫 번째 턴은 명명된 대화를 생성하며, 후속 턴은 previous_response_id로 연결됩니다.

• 검색 범위 질문에는 선택적 fileIds가 지원됩니다. 새 업로드는 내구성 있는 지식 업로드 도구를 사용하고 질문 전에 인덱싱이 완료될 때까지 기다려야 합니다.

• 프롬프트로 /new를 사용하여 MCP 대화를 초기화하세요.

calypso-list-buckets

구성된 Calypso API 키에 연결된 팀의 버킷을 나열합니다.

참고:

• GET /v1/knowledge/buckets를 사용합니다.

• team_id를 허용하지 않습니다. Calypso는 API 키에서 팀 범위를 결정합니다.

• 버킷 ID, slug, 이름, 상태, 멤버 수, 소스 수, 버킷 저장소 준비 상태를 반환합니다.

• 기본적으로 활성 버킷만 반환됩니다. 감사나 정리를 위해 보관된 버킷이 필요하면 includeArchived: true를 전달하세요.

• 대상 버킷을 선택해야 할 때 calypso-upload-file 또는 calypso-upload-files-batch 앞에 이 도구를 사용하세요.

• calypso://rag-agent-models는 각 RAG 변형에 바인딩된 버킷을 알려줍니다. calypso-list-buckets는 API 키 팀에 존재하는 버킷을 알려줍니다.

예시:

{
  "includeArchived": false
}

calypso-get-file

파일 ID로 하나의 지식 파일 메타데이터와 인덱싱 상태를 가져옵니다.

참고:

• GET /v1/knowledge/files/{file_id}를 사용합니다.

• calypso-list-buckets의 불투명한 fileIds를 파일명, MIME 유형, 크기, 인덱싱 상태, 버킷별 동기화 상태로 변환합니다.

• 상태가 오래된 것처럼 보일 때 verify: true를 전달하여 공급자(?verify=gemini)와 교차 확인하세요. 느리지만 신뢰할 수 있는 결과를 제공합니다.

예:

{
  "fileId": "file_123",
  "verify": true
}

calypso-create-bucket

생성 후 채우기 워크플로우를 위해 빈 버킷을 생성합니다.

참고:

• POST /v1/knowledge/buckets를 사용합니다(이 엔드포인트가 배포된 백엔드와 API 키에 대한 knowledge:bucket:create 권한이 필요합니다).

• 서버는 slug를 정규화하며, 충돌 발생 시 유형화된 bucket_slug_exists 오류를 반환합니다.

• idempotencyKey 재시도는 오류를 반환하는 대신 기존 버킷을 반환합니다.

• 업로드는 여전히 bucketSlugs + createMissingBuckets를 통해 암시적으로 버킷을 생성할 수 있습니다. 이 도구는 대상 버킷을 먼저 생성하기 위해 존재합니다.

예시:

{
  "name": "Product docs",
  "slug": "product-docs",
  "idempotencyKey": "create-product-docs-1"
}

calypso-create-agent

하나 이상의 버킷에 바인딩된 RAG 에이전트 변형을 생성합니다.

참고:

• POST /v1/rag-agent/agents를 사용합니다(이 엔드포인트가 배포된 백엔드와 API 키에 대한 rag:agent:create 권한이 필요합니다).

• 성공 응답은 model로 시작합니다. 이를 calypso-rag-agent에 바로 전달하세요.

• 버킷 바인딩은 서버 측에서 검증됩니다. 알 수 없거나 보관된 버킷은 bucket_not_found를, 에이전트 ID 충돌은 agent_id_exists를, 플랜의 에이전트 상한은 agent_limit_reached를 반환합니다.

• 에이전트를 생성하면 모델 카탈로그가 새로 고쳐지고 MCP tools/list_changed + resources/list_changed 알림이 전송되므로 재연결 없이도 새 변형을 사용할 수 있습니다.

예시:

{
  "agentId": "support",
  "name": "Support agent",
  "bucketSlugs": ["product-docs"],
  "idempotencyKey": "create-support-agent-1"
}

calypso-upload-file

파일을 내구성 있는 버킷 기반 지식 저장소 및 인덱싱 파이프라인에 업로드합니다.

참고:

• POST /v1/knowledge/files/upload-session을 사용하고 바이트를 스토리지에 직접 업로드한 다음, POST /v1/knowledge/files/upload-session/{session_id}/finalize로 마무리합니다.

• 업로드는 JSON 세션 요청과 서명된 바이너리 PUT을 사용하며, multipart 폼 업로드가 아닙니다.

• 채팅 첨부 file_id가 아닌 파일 및 작업 메타데이터를 반환합니다.

• bucketIds, bucketSlugs 또는 bucket을 통한 버킷 대상이 1개 필요합니다.

• 로컬 Claude Desktop/Cursor MCP 설치에서는 filePath를 사용하세요. 로컬 경로를 읽을 수 없는 호스팅 또는 원격 MCP 클라이언트에서는 contentBase64를 사용하세요.

• 에이전트가 /mnt/user-data/uploads/file.pdf 같은 경로를 확인하면 filePath가 아닌 contentBase64로 파일 바이트를 보내야 합니다.

• 선택적 title, tags, metadata, idempotencyKey를 지원합니다.

• bucketIds 또는 bucketSlugs로 기존 버킷에 업로드를 라우팅하거나 bucket을 단일 slug 단축키로 사용하세요.

• 업로드 중 Calypso가 없어진 대상 버킷을 생성하도록 하려면 버킷 slug와 함께 createMissingBuckets: true를 전달하세요.

• 반환 전에 인덱싱이 준비 상태에 도달할 때까지 선택적으로 대기할 수 있습니다.

예시:

{
  "filename": "handbook.pdf",
  "mimeType": "application/pdf",
  "filePath": "/Users/me/Documents/handbook.pdf",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "waitForIndexing": true
}

calypso-upload-files-batch

요청 하나로 1~100개의 파일을 내구성 있는 지식 저장소에 업로드합니다.

참고:

• POST /v1/knowledge/files:batch/upload-session을 사용하고 승인된 각 항목을 스토리지에 직접 업로드한 다음, POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize로 마무리합니다.

• 업로드는 multipart 폼 업로드가 아닌 JSON 세션 요청과 서명된 바이너리 PUT을 사용합니다.

• batchIdempotencyKey가 필요합니다. Calypso는 이를 사용하여 재시도를 위한 지속적인 배치 ID를 파생시킵니다.

• 모든 항목이 자체 버킷 대상을 제공하지 않는 한 bucketIds, bucketSlugs 또는 bucket을 통한 공용 버킷 대상이 필요합니다.

• 공용 bucketIds, bucketSlugs, bucket, createMissingBuckets 기본값과 항목별 재정의를 지원합니다.

• 로컬 MCP 설치에서는 항목별 filePath를 사용합니다. 로컬 경로를 읽을 수 없는 호스팅 또는 원격 MCP 클라이언트에서는 항목별 contentBase64를 사용하세요.

• clientFileId가 제공되지 않으면 Firestore 안전한 client_file_id 값을 생성합니다.

• accepted 또는 queued는 업로드가 지속성 있다는 의미이며 쿼리 준비가 되었다는 의미는 아닙니다. waitForBatchReady: true를 사용하면 GET /v1/knowledge/batches/{batch_id}?include_items=true를 폴링합니다.

• 각 항목의 상태, bucketSyncStatus, bucketSync를 확인하여 인덱싱된 콘텐츠와 버킷 준비 완료 검색을 구분하세요.

예시:

{
  "batchIdempotencyKey": "kb-seed-2026-06-04",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "items": [
    {
      "filename": "faq.txt",
      "mimeType": "text/plain",
      "filePath": "/Users/me/Documents/faq.txt"
    }
  ],
  "waitForBatchReady": true
}

사용 가능한 리소스

calypso://server-info

패키지 버전, API 기본 URL, 전송, 인증 모델, 노출된 기능을 포함한 읽기 전용 서버 메타데이터입니다.

calypso://rag-agent-models

구성된 API 키에서 발견한 팀 범위 calypso-rag-agent 모델 변형의 읽기 전용 런타임 카탈로그입니다. 각 변형의 활성 buckets, bucket_ids, missing_bucket_id를 포함합니다. 발견이 불가능하면 기본 calypso-rag-agent로 대체됩니다.

calypso://buckets

구성된 API 키에 연결된 팀지식 버킷의 읽기 전용 런타임 목록입니다. 업로드 전에 버킷 ID/slug 및 버킷 저장소 준비 상태를 확인하는 데 사용합니다.

calypso://workflows

지원되는 RAG 및 파일 업로드 워크플로우에 대한 간단한 안내서입니다.

calypso://security

API 키, 로컬 파일 읽기, 업로드, 로깅에 대한 운영 보안 참고 사항입니다.

사용 가능한 프롬프트

• calypso-question: calypso-rag-agent를 위한 근거 있는 지식 베이스 질문을 초안합니다

• calypso-ingestion: 내구성 있는 지식 저장소 업로드와 후속 질의를 준비합니다

• calypso-reset-conversation: /new로 깨끗한 새 RAG 스레드를 시작합니다

일반 워크플로우(복사/붙여넣기)

지식 검색

• 주제 요약:

  • Summarize the knowledge base guidance for campaign approvals

• 특정 답변 요청:

  • What does our documentation say about indexing retries?

• 두 개념 비교:

  • Compare file indexing with retrieval execution in the current architecture

• 새 스레드 시작:

  • /new

다중 턴 후속 질의

• 이전 답변 개선:

  • Focus only on the ingestion path and ignore retrieval

• 출처나 근거 요청:

  • Explain which documented components are involved and why

지식 저장소 파일 흐름

• 버킷 지속:

  • 대상을 선택하기 전에 calypso-list-buckets를 호출하거나 (calypso://buckets)를 읽습니다

• 지식 업로드:

  • 파일 페이로드와 선택 기능과 함께 calypso-upload-file을 호출합니다(--input title, tags, metadata 포함)

  • 로컬 Claude Desktop/Cursor MCP 설치에서는 filePath 사용을 권장하며, 로컬 경로를 읽을 수 없는 호스팅 또는 원격 MCP 클라이언트에서는 contentBase64를 사용하세요

• 지식을 버킷에 라우팅:

  • 단일 대상을 만들려면 bucket: "support-handbook", 여러 슬러그 대상을 지원할 경우 bucketSlugs, 이미 안정적인 버킷 ID가 있을 때 bucketIds를 사용하세요

• 온디맨드 버킷 대상 생성:

  • slug 기반 버킷 할당을 사용하는 경우 createMissingBuckets: true를 추가하세요

• 인덱싱 대기:

  • 지식 파일이 인덱싱 상태가 될 때까지 차단하려면 waitForIndexing: true 전달

지식 저장소 배치 흐름

• 다수 파일 일괄 업로드:

  • 로컬 설치용 MCP에서는 items, batchIdempotencyKey, 항목별 filePath와 함께 calypso-upload-files-batch를 호출하세요. 호스팅 또는 원격 MCP 클라이언트에서는 항목별 contentBase64를 사용하세요

• 배치를 버킷에 라우팅:

  • 공용 bucket, bucketSlugs, bucketIds 또는 createMissingBuckets를 호출 시 지정하고 필요한 경우에만 항목별로 재정의하세요

• 쿼리 준비 대기:

  • waitForBatchReady: true를 사용해 항목 상태와 버킷 동기화 필드를 확인 후 새 콘텐츠를 조회하세요

팁

• 다시 시작: /new를 사용하여 MCP 대화를 초기화하세요(새 conversation_id + 응답 체인 초기화).