MCP 도구 레퍼런스

@sayren/mcp의 도구입니다. 필요 스코프는 연결한 액세스 토큰에 있어야 합니다. 원격 MCP에는 스토어프론트 만들기 표의 도구 중 get_store_context·list_template_files·get_template_file만 있고, 나머지 두 표의 도구는 모두 있습니다. 호스팅 사이트를 고치는 도구(read_file·write_files·create_version 등)는 원격 MCP에만 있고 설치 없이 MCP 연결하기에서 설명합니다.

스토어프론트 만들기

도구	입력	출력	필요 스코프
`get_store_context`	없음	상점 코드, 스토어프론트 API 주소, 카테고리, 상품 수(`productCount`·`publicProductCount`), 상품 표본, 결제 설정 상태(액세스 토큰으로는 확인 불가), 요금제와 이번 달 남은 MCP 쓰기·읽기 수(`plan.aiActions.remaining`·`plan.aiReads.remaining`)	`store:r`. `product:r`이 없으면 `productCount`가 `null`
`get_scaffold_plan`	없음	만드는 순서, 규칙, 확장 지점, 유지할 파일, `.env` 값, 템플릿 파일 목록	`store:r`(없으면 상점 코드 빈칸)
`list_template_files`	원격만: `templateId`(생략하면 기본 템플릿)·`version`(지금 카탈로그 버전만)	템플릿 파일 경로 목록(`files`). 원격은 `templateId`·`version`·고를 수 있는 템플릿(`templates`)도	없음
`get_template_file`	`path`: `list_template_files`가 준 경로. 원격만: `templateId`·`version`	파일 원문(이진 파일은 `path`·`encoding`·`content` JSON)	없음
`verify_storefront`	`projectDir`: 프로젝트 절대 경로	`ok`, `summary`, 규칙별 결과(`results`), 위반(`findings`), 다음 할 일(`nextSteps`)	없음

verify_storefront 출력

results는 규칙별 pass·violation과 위반 수, summary는 규칙·통과·위반 수입니다. 위반(findings) 하나의 필드는 아래와 같습니다.

필드	설명
`ruleId` · `rule`	지켜야 할 규칙의 id와 설명
`file` · `line` · `detail`	고칠 파일·줄과 다른 점. 프로젝트 전체를 본 규칙은 `(프로젝트 전체)`
`cause` · `fix` · `example`	깨지는 것, 고치는 방법, 예시 코드
`doc` · `docUrl`	관련 문서
`templateFile`	규칙을 지키는 템플릿 파일(`get_template_file`로 대조)
`severity`	`error`는 고쳐야 통과하고(호스팅 버전 빌드를 막습니다), `warning`은 권고입니다. `ok`는 `error` 위반이 없으면 `true`입니다

관리 API 호출

관리 API 전체를 아래 도구로 호출합니다.

도구	입력	출력	필요 스코프
`list_operations`	없음	관리 API 목록(operationId·메서드·경로·제목·필요 스코프)	없음
`describe_operation`	`operationId`	파라미터, 요청 본문, 응답(`data`) 스키마, 멱등키 지원, 호출할 도구	없음
`call_api_read`	`operationId`(GET만), `pathParams`, `query`	응답의 `data`(큰 목록은 줄임)	오퍼레이션의 필요 스코프
`call_api_write`	`operationId`(GET 제외), `pathParams`, `query`, `body`, `idempotencyKey`, `dryRun`	응답의 `data`. `dryRun: true`면 판정(`ALLOW`·`APPROVAL_REQUIRED`·`DENIED`)과 영향만. 승인이 필요하면 `APPROVAL_PENDING`과 승인 링크	오퍼레이션의 필요 스코프
`get_approval_request`	`approvalId`	승인 요청 상태(`PENDING`·`SUCCEEDED`·`REJECTED`·`EXPIRED` 등)와 실행 결과	없음
`list_approvals`	`approvalId`(선택), `status`(기본 `PENDING`), `cursor`	승인 요청 목록 또는 한 건(사유·경로·본문·영향 미리보기·기한·승인 링크)	`store:r`, OWNER·ADMIN
`decide_approval`	`approvalId`, `decision`(`APPROVE`·`REJECT`), `note`	원격 MCP에서 확인 창으로 사람이 수락하면 결정(`APPROVAL_EXECUTING`·`APPROVAL_REJECTED`). 확인할 수 없으면 `NOT_DECIDED`와 승인 링크. 로컬 MCP는 승인 링크만	`store:rw`와 원 요청의 스코프, OWNER·ADMIN
`upload_image`	`sourceUrl`(https 이미지 주소) 또는 `base64` + `contentType` 중 하나, `filename`(선택)	공개 주소 `url`, 형식 `contentType`, 크기 `size`(바이트)	`product:rw`

list_operations는 승인 필요·조건부 승인 필요·호출 불가를 표시합니다(AI 작업 승인과 감사 로그). 연결한 토큰에 없는 스코프가 필요한 오퍼레이션에는 토큰 스코프 없음을 붙이고, describe_operation은 missingTokenScopes를 줍니다. 이런 오퍼레이션이나 403 INSUFFICIENT_ROLE 결과는 권한을 늘려 다시 연결하거나 필요한 스코프로 새 액세스 토큰을 만들어야 부를 수 있습니다.

상품 이미지는 upload_image로 올립니다. 도구가 업로드 자리(POST /v1/uploads)를 받아 파일을 올리고 공개 주소 url을 돌려줍니다. 상품에 연결하려면 call_api_write로 상품의 images에 url을 넣습니다(상품 이미지 등록).

형식은 JPG·PNG·WEBP·AVIF·GIF이고 장당 10MB까지입니다. 형식은 파일 내용으로 판정합니다.
sourceUrl은 https만 받고 리다이렉트는 3번까지 따라갑니다. 웹 페이지 주소는 이미지가 아니라서 실패합니다.
원격 MCP는 요청 크기 한도 때문에 base64로 약 3MB까지 올립니다. 더 큰 이미지는 sourceUrl로 올립니다.

스토어프론트 호스팅

스토어프론트 호스팅 사이트를 다룹니다. 사이트는 연결한 상점(SAYREN_STORE_ID·X-Store-Id)에서 정해지므로 입력에 상점·사이트 id가 없습니다.

도구	입력	출력	필요 스코프
`get_site`	없음	`enabled`, `domain`, `site`(주소 `url`, 공개 상태 `visibility`, 발행 버전 `publishedVersion`, 반영 상태 `provisioning`). 사이트가 없으면 `site`가 `null`. 미리보기 안내(`preview`)	`storefront:r`
`list_versions`	없음	버전 목록(최신 먼저, `versionId`·`number`·`status`·`published`)	`storefront:r`
`publish_version`	`versionId`, `expectedPublishedVersionId`, `idempotencyKey`, `dryRun`	승인 대기(`APPROVAL_PENDING`)와 승인 링크	`storefront:rw`
`rollback`	`versionId`(생략하면 직전 발행 버전), `expectedPublishedVersionId`, `idempotencyKey`, `dryRun`	승인 대기(`APPROVAL_PENDING`)와 승인 링크	`storefront:rw`
`set_visibility`	`visibility`(`COMING_SOON`·`PUBLIC`), `expectedVisibility`, `idempotencyKey`, `dryRun`	승인 대기(`APPROVAL_PENDING`)와 승인 링크	`storefront:rw`

AI 도구의 발행·되돌리기·공개 전환은 설정 › 보안 › 승인 요청에서 승인해야 실행됩니다. expected… 값을 주면 그사이 다른 사람이 바꿨을 때 409로 멈춥니다. 미리보기 링크는 도구로 주지 않습니다. 상점 플랫폼의 스토어프론트 › 개요에서 **[미리보기 열기]**로 봅니다.

환경변수

환경변수	설명
`SAYREN_TOKEN`	Sayren 계정 액세스 토큰. 필수. 옛 API 토큰(`sy_pat_…`)은 받지 않습니다
`SAYREN_STORE_ID`	다룰 상점 id. 토큰의 상점 범위 안이어야 합니다. 범위가 상점 하나면 생략할 수 있습니다
`SAYREN_API_ORIGIN`	API 호스트. 생략하면 `https://api.sayren.app`
`SAYREN_TELEMETRY`	`0`이면 아래 집계를 보내지 않습니다

검증 결과 집계

verify_storefront와 sayren-mcp create는 검사 결과 요약을 보냅니다. 자주 막히는 규칙의 안내를 고치는 데 씁니다.

보내는 값은 도구 이름과 버전, 실행마다 새로 만드는 임의 세션 값과 호출 순번, 실행 시간, 통과 여부, 검사한 파일 수, 규칙별 통과·위반과 위반 개수입니다. 파일 이름·경로, 소스 코드, 위반 상세(detail), 토큰, 사람·기기 식별 값은 보내지 않습니다. 전송은 2초 상한이고 실패해도 결과에 영향이 없습니다. 이 요청도 API 로그에 남습니다. 끄려면 env에 "SAYREN_TELEMETRY": "0"을 넣습니다.