Mothership
외부 도구와 파일
회사의 MCP 커넥터와 웹훅, 파일과 객체 저장소, 문서 변환과 결과물(artifact)을 다뤄요.
외부 도구 (MCP 커넥터)
회사 관리자가 회사 관리 → 외부 도구에서 MCP Streamable HTTP 서버(프로토콜 2025-11-25)나 웹훅을 등록해요. 주소는 운영자가 허용한 출처(MOTHERSHIP_TENANT_ALLOWED_INTEGRATION_ORIGINS, NARU_URL)만 돼요.
- 새 연결 — 이름, 주소, 자격(암호화해 저장, 다시 보여 주지 않아요), 위험도를 넣어요.
- 동기화 — 서버의 도구 목록을 읽어요.
- 도구 승인 — 쓸 도구를 하나씩 허용하고, 어느 앱이 쓸지 정해요.


앱은 manifest에 더 좁은 요청을 선언해요.
"connector_requests": [{ "id": "search", "tools": ["find"], "required_claims": [] }]
const { tools } = await ctx.api.connectors.listTools("search");
const result = await ctx.api.connectors.invoke("search", "find", { query: "report" });
- 쓸 수 있는 도구는 회사 승인과 앱 요청의 교집합이에요. Runtime 프로필의
tool_set에connector:search/find로 넣을 수 있어요. - 요청은 고정한 DNS 주소로, 리디렉트 없이, 크기와 시간 한도 안에서 가요(
MOTHERSHIP_CONNECTOR_TIMEOUT_SECONDS, 기본 30초). 사내 CA는MOTHERSHIP_INTEGRATION_CA_BUNDLE. - 공동 검증과 미리보기 환경의 커넥터는 운영 비밀값을 쓰지 않고 환경마다 따로 연결해요.
나루 toolset
나루는 회사의 외부 도구로 붙어서, 앱이 사람 이름으로 레거시 시스템을 불러요. Mothership은 부르는 사람을 밝히는 서명된 assertion을 보내고, 나루는 그 사람의 계정으로 레거시에 로그인해요. → 제품 잇기
파일과 객체
| API | 무엇 |
|---|---|
ctx.api.files.* |
업로드(sha256, 크기 한도 MOTHERSHIP_FILE_MAX_BYTES, 기본 10 MiB), 짧은 서명 링크로 내려받기 |
ctx.api.objects.* |
manifest에 api: "storage.objects"로 선언한 자원의 키·값 저장(버전, 커서, user_private) |
MOTHERSHIP_S3_BUCKET이 있으면 S3 호환 버킷(AWS S3, MinIO, R2)에, 없으면 DB에 저장해요. 내려받기는 언제나 게이트웨이를 거쳐서 지금의 세션, 구성원, 설치, 출처 권한을 다시 확인해요. HTML·SVG도 첨부로 내려가 게이트웨이 출처에서 실행되지 않아요.
문서 변환과 결과물
POST /api/v1/files/{fileId}/convert가 202 {jobId}를 돌려주고 document_worker가 처리해요.
| 원본 | text/plain |
application/pdf |
|---|---|---|
| UTF-8 텍스트, JSON, XML, YAML | 텍스트 | 텍스트를 감싼 쪽 |
| DOCX, PPTX | 문단 / 슬라이드 텍스트 | text_reflow(원래 레이아웃은 남지 않아요) |
| 본문 텍스트, 글자가 없는 쪽은 OCR | 확인한 원본 PDF | |
| PNG, JPEG, TIFF, WebP, BMP | Tesseract OCR(eng+kor) | 비율을 지킨 이미지 쪽 |
결과물(artifact)은 진짜 파일이에요(document, slide, spreadsheet, image, dataset, package). 만든 사람과 작업을 시작한 앱만 내려받아요.
백엔드 worker
회사만의 연동이나 계산이 필요하면 Golden Image의 Python(FastAPI) 또는 Node worker를 배포하고 카탈로그 관리 → 외부 백엔드 연결 · 고급에서 URL과 미리 나눈 서명 키로 연결해요. → Golden Image 백엔드