MCP 도구

MCP 도구 참조

모든 Showly MCP 도구 — 범위, 매개변수, 반환 형태, 감사 동작.

Showly MCP 서버가 공개하는 모든 도구. 각 항목에는 필요한 범위, 짧은 형식의 입력 스키마, 반환 형태 및 감사 로그에 기록되는 항목이 나열됩니다.

모든 도구에는 인증된 MCP 클라이언트가 필요합니다. 작업공간 설정 → MCP 클라이언트에서 토큰이 발급됩니다.

호출이 차단되었을 때

Showly가 반환하는 모든 실패는 같은 엔벨로프를 씁니다. 도구가 판정한 실패든, 도구를 실행하기 전에 MCP 계층이 판정한 실패든(토큰에 없는 범위, 너무 큰 인자나 결과) 형태가 같습니다. ok는 false이고 error는 분기에 사용하는 string 코드이며 객체가 되지 않습니다. MCP 계층의 거부는 MCP isError 플래그도 함께 설정하므로 그 플래그로 분기하는 클라이언트에는 여전히 실패로 보이고, 플래그 옆의 텍스트는 같은 JSON입니다.

이 엔벨로프가 아닌 실패는 세 가지이며, 모두 Showly 코드가 실행되기 전에 MCP SDK가 응답합니다. 셋 다 isError: true와 평문 메시지로 도착합니다.

  • 인자가 빠졌거나 타입이 틀린 경우 — MCP error -32602: Input validation error: Invalid arguments for tool <name>: …. 연동 측이 가장 자주 만드는 실패이므로 파싱을 방어적으로 하십시오.
  • 이 서버가 공개하지 않은 도구 이름 — MCP error -32602: Tool <name> not found.
  • 예기치 못한 오류 — 전송 장애나 결함.

도구가 선언하지 않은 인자는 이 목록에 없으며 애초에 실패도 아닙니다. SDK가 호출 전에 알 수 없는 키를 제거하므로 도구는 자신이 선언한 인자만 받습니다.

파싱할 수 없는 본문은 코드를 추측하지 말고 알 수 없는 오류로 처리하십시오.

{
  ok: false,
  error: "insufficient_credits",
  message: "A production deployment costs 5 credits and this workspace has 2 left.",
  status?: 402,

  resolvedBy: "agent" | "human",
  actionUrl?: "https://showly.ai/app/billing#upgrade",
  humanAction?: "Open Plan & Billing and add credits, then tell the agent to retry.",
  agentNext: {
    kind: "retry" | "retry_with" | "call_tool" | "poll" | "wait_for_human" | "stop",
    tool?: "publish_site",
    afterSeconds?: 10,
    note: "After the balance changes, start the publish over from step 1."
  }
}

resolvedBy를 먼저 읽으십시오. "agent"는 이미 가진 도구만으로 해결할 수 있다는 뜻입니다 — 다른 previewSlug를 고르거나, 빠진 id를 가져오거나, agentNext.tool이 지정한 도구를 호출하십시오. "human"은 어떤 도구 호출로도 풀리지 않는다는 뜻입니다. humanAction과 actionUrl을 사용자에게 전달한 뒤 agentNext를 따르십시오.

actionUrl은 절대 URL이며 Showly 웹 앱의 페이지를 가리키고, 관리자 전용 영역을 가리키지 않습니다. actionUrl이 있으면 링크로 전달하고, humanAction은 항상 전달하십시오. 그 링크를 누가 쓸 수 있는지는 이 문장이 정합니다. 중요한 사례는 요금제 및 결제 페이지입니다. 이 페이지는 작업공간 소유자, 관리자, 결제 역할로 제한되고 결제에는 billing:write까지 필요하므로, 일반 멤버가 링크를 열면 대시보드로 되돌아갑니다. 둘 중 누가 이 메시지를 읽는지 Showly는 알 수 없습니다. 페이지는 본인의 웹 세션을 보고 판단하지만 MCP 토큰이 나타내는 것은 에이전트이기 때문입니다. 그래서 링크는 항상 보내고 조건은 humanAction이 전합니다. 소유자는 바로 처리하고, 그 외에는 전달하면 됩니다. 요금제나 크레딧 실패에 실리는 기존 webUpgradeUrl도 같은 URL이며 조건도 같습니다.

사람이 필요한 유일한 성공 응답에도 같은 네 필드가 실립니다. request_publish는 resolvedBy, actionUrl, humanAction, agentNext를 실패 응답과 똑같은 최상위 위치에 반환하므로 if (result.actionUrl)이 양쪽 모두에서 동작합니다. 이 필드들은 data 안에도 기존 webApprovalUrl과 나란히 중복으로 실리므로 data.actionUrl을 읽는 기존 연동도 그대로 동작합니다.

기존 연동이 계속 동작하도록 이전 두 필드도 actionUrl과 같은 값으로 함께 전송됩니다. email_verification_required의 webVerificationUrl과 성공한 request_publish의 webApprovalUrl입니다.

list_projects

범위: project:read

토큰이 볼 수 있는 프로젝트(작업 공간)를 나열합니다.

Input:  {}
Output: { ok, data: Array<{ id, name, slug, createdAt }> }
Audit:  mcp.list_projects

list_sites

범위: site:read

현재 작업공간의 사이트를 나열합니다. 목록의 범위를 지정하려면 projectId를 전달하세요. 프로젝트 범위의 MCP 토큰은 매개변수에 관계없이 이 필터를 강제합니다.

Input:  { projectId?: string }
Output: { ok, data: Array<Site>, view: ListSitesView }
Audit:  mcp.list_sites

텍스트 블록 두 개로 응답하는 도구는 이것뿐입니다. 첫 번째는 서버에서 작성한 요약으로 사이트 이름, 공개 여부, 권장하는 다음 작업 하나를 담고 있어 호출할 때마다 동일하게 표시됩니다. 두 번째는 위의 JSON 봉투이며 내용은 그대로입니다. content[0]이 아니라 content[content.length - 1]에서 읽으세요. 같은 봉투는 structuredContent로도 반환되며, view는 요약과 아래의 대화형 렌더링이 공유하는 투영입니다.

클라이언트가 initialize 기능에서 MCP Apps 확장 io.modelcontextprotocol/ui를 선언하면 이 도구에 _meta.ui.resourceUri도 함께 전달됩니다. 이는 호스트가 샌드박스 iframe에서 렌더링하는 ui:// HTML 리소스를 가리킵니다. 선언하지 않은 클라이언트는 해당 메타데이터를 받지 않으며 결과의 나머지 부분도 달라지지 않습니다.

get_site_context

범위: site:read

사이트, 감지된 프레임워크, 경로, 참조된 환경 변수 이름, 최신 미리보기 URL 및 특정 siteId에 대한 마지막 프로덕션 배포 ID를 반환합니다. [공통 유형](#common-types)의 Site 모양을 참고하세요.

Input:  { siteId }
Output: { ok, data: { site, framework, routes, envReferences, latestPreviewUrl, lastProductionDeploymentId } }
Audit:  mcp.get_site_context  (records siteId)

create_change_plan

범위: site:read

변경 계획 제안을 작성합니다. 파일을 수정하지 _않습니다_. 상담원은 일반적으로 반환된 계획을 읽고 사용자에게 확인을 요청한 다음 apply_site_patch에 전화합니다.

Input:  { siteId, request: string }
Output: { ok, data: { siteId, request, plan, nextStep } }
Audit:  mcp.create_change_plan

apply_site_patch

범위: site:write

사이트의 스테이지 파일 편집. 단계적 변경 세트는 일시적이며 create_preview에 의해 구체화되어야 합니다.

Input:  { siteId, files: Array<{ path, content }>, message: string }
Output: { ok, data: { changesetId, siteId, fileCount, ttlSeconds, nextStep } }
Audit:  mcp.apply_site_patch  (records siteId + changesetId + file count)

create_preview

범위: preview:create

패치된 작업공간을 빌드하고 미리보기 URL을 생성합니다. 사용자는 비공개 액세스 결정: 짧은 서버 생성 XXX-XXX의 경우 access를 생략합니다. 비밀번호를 선택하고 6~128자의 맞춤 비밀번호를 전달하거나 organization를 선택하세요. (Pro+) 또는 organization_or_password. 생성된 일반 텍스트는 한 번 반환되고 나중에 검색할 수 없습니다. 미리보기는 공개할 수 없습니다. 라이브로 게시하세요. 모든 사람에게 표시되어야 합니다. previewSlug를 지정하면 별도의 단일 레벨 주소 <previewSlug>.showly.site를 선택할 수 있습니다.

Input:  { changesetId?, siteId?, files?, previewSlug?, access?: { mode, password? } }
Output: { deploymentId, previewUrl, framework?, fileCount?, access: { mode, passwordConfigured, password? } }
Audit:  mcp.create_preview

create_github_preview

범위: preview:create

연결된 사이트의 최신 커밋에서 비공개 미리보기를 구축합니다 GitHub 지점. 설치 자격 증명은 Showly 안에 있습니다. access를 생략하면 짧은 서버 생성 XXX-XXX 비밀번호가 한 번 반환되면 사용자 정의 6–128을 전달합니다. 문자 비밀번호를 입력하거나 Pro+에서 조직 구성원 액세스를 선택하세요. 이 도구 라이브를 게시하지 않습니다. 반환된 항목으로 설문조사 get_preview_status deploymentId.

사이트에 활성 GitHub 앱 저장소가 없으면 먼저 Showly 웹에 연결하세요. 저장소 자동 빌드는 현재 정적 배포 대상을 지원합니다. 역동적인 컨테이너 대상은 무엇보다 먼저 repository_build_target_unsupported를 반환합니다. 대기열에 있습니다. 확인되지 않은 Showly 이메일은 웹 URL과 함께 email_verification_required를 반환합니다. 확인을 완료합니다.

set_preview_access

범위: preview:create

URL을 변경하지 않고 기존 Preview 또는 게시된 Live 배포의 액세스 정책을 변경합니다. 게시된 사이트를 보호하려면 list_deployments가 반환한 ready 상태의 production ID를 사용합니다. 기존 클라이언트 호환성을 위해 도구 이름은 유지됩니다. 비밀번호 모드는 비밀번호를 교체합니다. 6~128자 값을 전달하거나 생략합니다. password 서버측에서 짧은 XXX-XXX 공유 코드를 생성합니다. 응답 previewUrl 옆에 새로운 일반 텍스트 비밀번호가 한 번 표시됩니다. 모든 정책 변경하면 이전에 발행된 미리 보기 액세스 쿠키가 무효화됩니다.

조직 모드는 방문자의 활성 Showly 조직 멤버십을 확인하고, 따라서 팀원은 비밀번호를 공유하는 대신 로그인할 수 있습니다. organization_or_password 외부 검토자가 비밀번호를 사용할 수 있도록 허용하면서 내부 흐름을 유지합니다.

Input:  { deploymentId, access: { mode: "password" | "organization" | "organization_or_password", password? } }
Output: { deploymentId, target, previewUrl, access: { mode, passwordConfigured, password? }, policyVersion, advancedDeploymentControls }
Audit:  mcp.set_preview_access

사용자 정의 비밀번호 교체 예시:

{
  "deploymentId": "00000000-0000-4000-8000-000000000000",
  "access": { "mode": "password", "password": "ABC-123" }
}

retry_deployment

범위: preview:create

실패 또는 취소 미리보기 배포를 다시 빌드합니다. create_preview에 제공한 것과 동일한 files를 다시 제공하세요. 소스는 서버측에 보관되지 않으므로 files가 필수입니다. status: "building"에 새 deploymentId(실패한 항목은 기록으로 유지됨)을 생성하고 폴링을 위해 반환합니다. 각 재시도는 월별 배포 할당량에 포함됩니다. 이는 새로운 빌드입니다. 배포가 아직 구축 중이거나 이미 준비된 경우 409 not_retryable, 토큰에 표시되지 않는 경우 404, 할당량을 초과한 경우 402를 반환합니다.

Input:  { deploymentId, files: [{ path, content }] }
Output: { ok, data: { deploymentId, status: "building", pollUrl, retriedFrom } }
Audit:  mcp.retry_deployment

run_checks

범위: checks:run

미리보기에 대해 작업공간의 검사 매트릭스(린트, 유형, 사용자 정의 CI 후크)를 실행합니다. checks는 { id, status } 행 목록입니다(lint / typecheck / build / audit-gate). summary는 "3 passed / 1 pending"과 같은 한 줄 문자열입니다.

Input:  { deploymentId }
Output: { ok, data: { deploymentId, checks: [{ id, status }], summary } }
Audit:  mcp.run_checks

request_publish

범위: publish:request

준비된 미리보기 배포에 대한 승인 요청을 엽니다. 응답에는 다음이 포함됩니다. webApprovalUrl 딥 링크; 사용자가 정확한 내용을 검토할 수 있도록 해당 링크를 표시하세요. 계획에 필요한 2인 승인을 미리 보고 완료합니다. 출판은 OTP/MFA 등록이 필요하지 않습니다. MCP 토큰에 바인딩된 사용자는 Showly 계정 이메일을 확인했습니다. 도구가 반환되는 경우 email_verification_required, 다시 보내려면 사용자를 webVerificationUrl로 보내세요. 다시 시도하기 전에 확인을 완료하세요.

Input:  { deploymentId, message: string }
Output: { approvalId, deploymentId, state: "pending", expiresAt, reused, webApprovalUrl }
Audit:  mcp.request_publish

publish_site

범위: publish:confirm

승인 워크플로가 없는 단독 작업 공간 및 계획에 대해 대화에서 직접 준비된 미리 보기 배포를 프로덕션에 게시합니다. MCP 토큰에 바인딩된 사용자는 확인된 Showly 계정 이메일을 가지고 있어야 합니다. 도구가 email_verification_required를 반환하면 사용자를 webVerificationUrl로 보내고 확인이 완료될 때까지 기다린 다음 2단계 흐름을 다시 시작합니다. 사이트가 아직 활성화되지 않았습니다. 2단계 사람이 확인: siteId + deploymentId(아니요 confirmationToken)로 호출하여 요약 + 단기 confirmationToken를 얻습니다. 사용자에게 곧 시작될 내용을 보여준 다음 토큰을 사용하여 다시 호출하세요. 2단계에서는 202 publishing을 반환합니다. 승인 작업 흐름이 활성화된 계획에서는 대신 request_publish를 사용하세요. 이 도구가 그곳으로 연결됩니다.

Step 1: { siteId, deploymentId }                        → { confirmationToken, summary }
Step 2: { siteId, deploymentId, confirmationToken }      → { siteId, deploymentId, status: "publishing" }
Audit:  mcp.publish_site

MCP Apps를 렌더링하는 호스트에서는 1단계의 왕복을 건너뛸 수 있습니다. 준비된 Preview 카드에 Publish live 버튼이 있고, 클릭하면 사용자의 확인이 메시지로 대화에 전달됩니다. 그 메시지를 확인으로 간주해 사전 점검과 토큰을 사용한 발행을 연달아 실행하고 결과만 한 번 답하세요. 나머지는 그대로입니다. 동일한 두 번의 호출, 동일한 서버 발급 토큰, 동일한 차단 조건, 그리고 일반 프로덕션 배포와 동일한 크레딧 비용입니다.

get_preview_status

범위: preview:read

미리보기 배포의 현재 상태를 반환합니다. 상태가 알려진 값에서 벗어날 때까지 선택적으로 긴 폴링(기본값 30초, 최대 60초) — 검토자를 기다리는 동안 request_publish 이후에 유용합니다. status가 failed 또는 canceled인 경우 결과에는 errorCode, errorMessage, stage와 빌드가 실패한 이유를 설명하는 짧은 logTail도 포함됩니다. 재구축하려면 retry_deployment와 짝을 이루세요.

Input:  { deploymentId, waitForChange?: boolean, currentStatus?: string, timeoutMs?: number }
Output: { ok, data: Deployment & { productionUrl?, errorCode?, errorMessage?, stage?, logTail? }, changed?, timedOut? }
Audit:  mcp.get_preview_status

get_deployment_logs

범위: logs:read

배포에 대한 빌드 로그 테일을 반환합니다(캡처된 빌드 출력의 마지막 lineCount 줄, 기본값 200). source는 db(실제 로그 줄), pending(배포가 존재하지만 아직 캡처된 로그가 없음 - 여전히 구축 중이거나 테일이 없음) 또는 not-found(이 토큰에 대한 배포가 없음)을 구별합니다.

Input:  { deploymentId, lineCount?: number }
Output: { ok, data: { deploymentId, lineCount, source, lines } }
Audit:  mcp.get_deployment_logs

diagnose_deployment

범위: logs:read

자신만의 배포 중 하나를 자가 진단하세요. 단일 구조화된 AI 사용 가능 진단 번들을 반환하므로 에이전트는 별도의 get_preview_status / get_deployment_logs 읽기를 함께 연결하는 대신 한 번의 호출로 빌드가 실패한 이유를 추론한 다음 소스와 retry_deployment를 수정합니다. 번들은 다음을 집계합니다: 빌드 실패(stage, errorCode, errorMessage, a logTail), Sentry의 관련 런타임 오류(커밋 SHA + 환경 + 배포 주변 창, 페일 소프트로 상관 관계), 배포의 ops-job 상태, 조직의 할당량 상태, 모든 에이전트 푸시 clientLogs(수정됨) + 제한됨) 및 결정적 hypotheses — 고품질 출발점으로 규칙(AI 아님)에 의해 파생된 확실한 근본 원인(예: quota_exceeded / build_install_failed)입니다.

테넌트 격리: 자체 조직의 배포만 진단할 수 있습니다. 토큰에 표시되지 않는 배포 ID는 404를 반환합니다(존재하지 않는 ID와 구별할 수 없음 - 조직 간 존재 누출 없음). 이는 직원 진단 센터 번들의 상담원용 트윈입니다. 둘 다 하나의 백엔드 수집기를 공유합니다. 전화 GET /deployments/:deploymentId/diagnostics.

Input:  { deploymentId }
Output: { ok, data: { deployment, failure, jobRun, quota, sentry, clientLogs, hypotheses } }
Audit:  mcp.diagnose_deployment

list_templates

범위: template:read

현재 토큰에 사용할 수 있는 Showly 사이트 템플릿을 나열합니다. Git 저장소 없이 새 사이트를 온보딩하려면 create_site_from_template와 페어링하세요.

Input:  { framework?: string }
Output: { ok, data: Array<{ slug, displayName, description, framework, screenshots }> }
Audit:  mcp.list_templates

create_site_from_template

범위: template:create, site:write

템플릿에서 새로운 Showly 관리 사이트를 구현하고 첫 번째 사이트를 구축합니다. 비공개 미리보기. 생략됨 access 반환된 서버 소유 비밀번호를 생성합니다. initialPreviewUrl로 정확히 한 번; 정리 모드에는 Pro가 필요합니다. siteSlug는 첫 미리보기와 Live가 함께 사용하는 안정적인 <siteSlug>.showly.site 주소입니다.

Input:  { projectId, templateSlug, name, siteSlug, variables?: Record<string, unknown>, access?: { mode, password? } }
Output: { ok, data: { siteId, projectId, initialVersionId, initialPreviewDeploymentId, initialPreviewUrl, access, templateSlug, createdAt } }
Audit:  mcp.create_site_from_template

create_site_from_html

범위: site:write, preview:create

템플릿, 프레임워크, Git 저장소 없이 일반 HTML/CSS/JS 파일에서 직접 새로운 Showly 관리 사이트를 만듭니다. 파일 인라인(index.html 필수, 바이너리 자산의 경우 encoding: "base64")을 전달하거나 또는 request_upload_url를 통해 대역 외 업로드한 대규모 소스의 경우 sourceBundleId(정확히 files / sourceBundleId 중 하나)를 전달합니다. 한 번의 호출로 사이트가 생성되고 첫 번째 미리보기가 구축됩니다. 반환된 deploymentId를 get_preview_status로 폴링합니다. siteSlug는 미리보기/Live가 공유하는 <siteSlug>.showly.site 주소가 됩니다. 제작은 게시 흐름을 유지합니다.

Input:  { projectId, name, siteSlug, files?: Array<{ path, content, encoding?: "utf8" | "base64" }>, sourceBundleId?, framework?, access?: { mode, password? } }
Output: { ok, data: { siteId, deploymentId, status | previewUrl, access, ... } }
Audit:  mcp.create_site_from_html

request_upload_url

범위: site:write, preview:create

모델을 통해 전달하기에 적합하지 않은 대형 사이트 소스를 위해 짧은 시간 동안 한 번만 사용할 수 있는 업로드 URL을 발급합니다. Content-Type: application/x-tar로 tar 아카이브를 반환된 uploadUrl에 PUT한 다음, files 대신 반환된 sourceBundleId를 사용하여 create_site_from_html를 호출합니다.

Input:  {}
Output: { ok, data: { uploadUrl, sourceBundleId, contentType, expiresInSeconds } }
Audit:  mcp.request_upload_url

request_download_url

범위: site:read

request_upload_url에 대응하는 읽기 도구입니다. 접근 가능한 deploymentId를 전달하면 보존된 소스 아카이브에 대한 짧은 시간의 일회용 downloadUrl을 받습니다. 아카이브를 로컬에서 편집하고 request_upload_url로 새 소스를 업로드한 뒤, 해당 sourceBundleId를 create_preview에 전달합니다. 소스 아카이브가 없으면 source_not_retained(422)를 반환합니다. 작은 사이트에는 get_site_files를 사용하세요.

Input:  { deploymentId }
Output: { ok, data: { downloadUrl, expiresInSeconds } }
Audit:  mcp.request_download_url

claim_trial_site

범위: site:write

Showly의 공개 평가판 흐름에서 만든 사이트를 현재 인증된 계정으로 가져와 만료되지 않는 영구 사이트로 만듭니다. 서버가 제공한 trialId + guestToken을 전달합니다. 평가판이 만료되었거나 워크스페이스에 활성 사이트 수에 대한 명시적 제한이 있으면 실패합니다. 사용하지 않는 사이트를 삭제하거나 Showly 지원팀에 문의한 뒤 다시 시도하세요. Free와 Pro는 기본적으로 미리보기와 공개 사이트 수가 모두 무제한이며 요금제를 변경해도 사이트 슬롯은 늘지 않습니다.

Input:  { trialId: string, guestToken: string }
Output: { ok, data: { trialId, siteId, claimed: true } }
Audit:  mcp.claim_trial_site

delete_preview

범위: preview:create

ID별로 미리 보기 배포를 일시 삭제합니다. deletedAt를 반환합니다. 멱등성 — 이미 삭제된 미리보기를 삭제하면 404 preview_not_found가 반환됩니다. 여기서는 미리보기만 삭제할 수 있습니다. 생산에는 영향을 미치지 않습니다.

Input:  { deploymentId }
Output: { ok, data: { deploymentId, deletedAt } }
Audit:  mcp.delete_preview

delete_site

범위: site:delete

사이트를 일시 삭제하고 해당 배포, 버전 및 사용자 지정 도메인에 계단식 적용합니다. 2단계 사람이 확인: siteId(아니요 confirmationToken)로 호출하여 요약(슬러그 + 계단식 배포 수)과 단기 confirmationToken를 얻습니다. 사용자를 표시한 다음 삭제할 토큰을 사용하여 다시 호출하세요. 백업에서만 복구 가능합니다.

Step 1: { siteId }                          → { confirmationToken, summary: { siteSlug, cascade: { deployments } } }
Step 2: { siteId, confirmationToken }        → { siteId, deletedAt }
Audit:  mcp.delete_site

list_site_domains

범위: site:read

사이트에 연결된 사용자 정의 도메인의 현재 안내 단계, DNS 레코드, 인증서 상태, 복구 CTA, 관리 페이지 및 라이브 URL을 나열합니다. 결과는 기본 50개이며 최대 100개까지 요청할 수 있습니다. pagination.nextCursor가 null이 아니면 값을 변경하지 않고 cursor로 다시 전달하세요. 커서는 불투명하며 하나의 사이트에만 연결됩니다.

결과가 비어 있지 않으면 각 대상 행의 domains[].journey를 따르세요. 이때 최상위 journey는 없습니다. 최상위 journey는 빈 목록에서만 반환되며 첫 도메인 연결을 안내합니다. 대상 도메인의 단계가 setting_up_https인 동안에만 폴링하고, needs_attention이 되면 중지하세요.

Input:  { siteId, limit?, cursor? }
Output: { ok,
          journeyGuide: { steps, whatShowlyGivesYou },
          domains: [{ id, hostname, status, isLive, certStatus, liveUrl,
                      manageUrl, dnsRecords, proxyNote, apexNote?,
                      journey: { phase, currentStep, stepStatuses,
                                 whereYouAre, userAction, agentAction,
                                 actionUrl }, recovery? }],
          pagination: { count, total, nextCursor },
          journey? }
Audit:  mcp.list_site_domains

add_custom_domain

범위: site:write · 모든 요금제에서 사용 가능

고객 자신의 도메인을 사이트에 연결하고 사용자가 도메인 공급자에 게시해야 하는 DNS 레코드를 반환합니다.

이 단계를 완료할 수 없습니다. 클레임은 보류 중인 레코드를 생성하고 트래픽을 라우팅하지 않습니다. 도메인은 고객이 도메인을 구입한 사람에게서 DNS 수정한 후에만 실제가 됩니다. 그들에게 기록을 건네주고 그들이 기록을 추가할 때까지 아무 일도 일어나지 않는다고 분명히 말하고 기다리십시오. 루트 도메인에서 응답은 apexNote을 전달합니다. 이는 일반 CNAME이 zone apex에서 유효하지 않기 때문입니다. 모든 응답에는 proxyNote도 포함됩니다. CNAME은 프록시를 거치지 않고 게시해야 하며(Cloudflare에서는 회색 구름, 새 레코드는 주황색입니다) 그렇지 않으면 인증서를 발급할 수 없습니다. TXT 레코드는 어느 쪽이든 검증되므로 이 흐름의 다른 어떤 단계도 이를 잡아내지 못합니다. 반드시 사용자에게 전달하세요.

반환된 내용을 보관하세요 verificationToken; verify_custom_domain 이 정보가 필요하며 한 번만 표시됩니다.

Input:  { siteId, hostname }
Output: { ok, domain: { id, hostname, status, dnsRecords, proxyNote, apexNote?, verificationToken }, nextStep }
Audit:  mcp.add_custom_domain

verify_custom_domain

범위: site:write · 모든 요금제에서 사용 가능

보류 중인 도메인이 있는지 DNS를 다시 확인합니다. 사용자가 레코드를 추가했다고 말한 후에 호출하세요. 레코드가 실제로 게시되고 전파되는 경우에만 성공합니다. 실패는 일반적으로 "깨짐"이 아니라 "아직 아님"을 의미하므로 오류를 보고하는 대신 몇 분 정도 기다렸다가 다시 시도하세요.

성공하면 TLS 인증서가 자동으로 요청되고 도메인은 한 시간 내에 활성화됩니다. isLive에 대해 list_site_domains를 투표하세요.

Input:  { siteId, domainId, token }
Output: { ok, domain: { id, hostname, status, isLive, ... } }
Audit:  mcp.verify_custom_domain

상담원은 의도적으로 도메인을 제거할 수 없습니다. 라이브 도메인을 보관하면 고객의 사이트가 광고한 주소에서 즉시 오프라인으로 전환되며 Showly 외부 동의가 필요하지 않으므로 대시보드에 개인의 작업이 유지됩니다. ADR 0015를 참조하십시오.

list_site_versions

범위: site:read

사이트의 버전 기록을 나열합니다(최신 버전부터): id, source, changeSummary, 작성자, createdAt. 해당 버전의 콘텐츠를 읽으려면 get_site_files(versionId 전달)와 페어링하세요.

키 세트로 페이지가 매겨졌습니다. limit 페이지당 100으로 제한됩니다. 이전 버전에 도달하려면 이전 응답의 pagination.nextCursor를 cursor로 다시 전달하세요. nextCursor/null는 기록의 끝에 도달했음을 의미합니다. 커서는 불투명하고 한 사이트에 바인딩되어 있습니다. 카탈로그를 첫 번째 페이지의 순간에 고정하므로 페이지를 보는 동안 생성된 버전은 이미 읽은 페이지로 행을 이동할 수 없습니다.

hasMore는 지원 중단되었으며 pagination.nextCursor !== null 미러링되었습니다. pagination를 선호합니다.

Input:  { siteId, limit?, cursor? }
Output: { ok, data: {
          versions: [{ id, source, changeSummary, authorUserId, createdAt }],
          hasMore,
          pagination: { limit, nextCursor: string | null }
        } }
Audit:  mcp.list_site_versions

list_deployments

범위: site:read

사이트의 배포를 나열합니다(최신 항목부터): id, target (preview / staging / production), status, url, createdAt. 이것이 deploymentId의 유래입니다. 반환된 id를 retry_deployment, delete_preview, request_publish 또는 publish_site와 함께 사용하세요.

Input:  { siteId }
Output: { ok, data: [{ id, siteId, target, status, url, createdAt }] }
Audit:  mcp.list_deployments

get_site_files

범위: site:read

편집하기 전에 현재 콘텐츠를 볼 수 있도록 사이트 버전의 파일 트리(path → content)를 읽습니다. siteId + versionId(list_site_versions부터)를 통과하세요. 대형/매니페스트 지원 버전은 files: null와 note를 반환합니다.

Input:  { siteId, versionId }
Output: { ok, data: { versionId, source, changeSummary, files: Record<string,string> | null, note? } }
Audit:  mcp.get_site_files

diff_site_versions

범위: site:read

두 버전을 비교하고 파일별 상태(added / removed / changed)와 줄 수준 add / remove / context 등 변경된 내용을 정확하게 반환합니다. siteId + versionA(이전 "이전") + versionB(최신 "이후")를 모두 list_site_versions에서 전달합니다. "어제와 오늘 사이에 무엇이 바뀌었나"와 같은 질문에 답합니다. 대형/매니페스트 지원 버전은 비교할 수 없으며 오류를 반환합니다.

Input:  { siteId, versionA, versionB }
Output: { ok, data: {
          versionA: { id, source, changeSummary, createdAt },
          versionB: { id, source, changeSummary, createdAt },
          summary: { filesChanged, filesAdded, filesRemoved, linesChanged },
          files: Array<{ path, status, lines: Array<{ type, text }> }>
        } }
Audit:  mcp.diff_site_versions

rollback_to_version

범위: rollback:confirm

프로덕션을 이전 버전으로 롤백하고 미리 보기 없이 게시합니다. 이는 여기서 가장 중요한 도구입니다. 2단계 사람이 확인: siteId + versionId(아니요 confirmationToken)로 호출하여 warning + 요약 + confirmationToken를 얻습니다. 사용자에게 경고를 표시한 다음 토큰을 사용하여 다시 호출하세요. 2단계에서는 202 building를 반환합니다. — Showly는 해당 버전의 미리 보기를 빌드하고 프로덕션 버전으로 자동 승격합니다. 최신 버전으로 롤포워드하여 복구할 수 있습니다.

Step 1: { siteId, versionId }                       → { confirmationToken, warning, summary: { changeSummary, versionCreatedAt, previewed: false } }
Step 2: { siteId, versionId, confirmationToken }     → { siteId, versionId, deploymentId, status: "building" }
Audit:  mcp.rollback_to_version

제작 도구(MCP 노출되지 않음)

MCP 노출되지 않음 - 웹/API 승인 흐름이 필요합니다.

기존 rollback_deployment 작업은 MCP에서 사용할 수 없습니다. tools/list에 표시되지 않으며 MCP 토큰으로 호출할 수 없습니다. 해당 Showly 웹 승인 화면을 사용하세요.

프로덕션 게시 는 MCP 호출 가능: publish_site(위의 2단계 확인)은 직접 게시하고 rollback_to_version는 프로덕션을 롤백합니다. 두 가지 모두 첫 번째 호출에서는 작동하지 않는 kind: "confirm-publish" 스타일 도구입니다.

일반적인 유형

참조에서는 위의 몇 가지 명명된 모양을 사용합니다. 구체적인 필드 세트는 실제 JSON로 전체 세션을 진행하는 종단 간 흐름에 표시됩니다. 빠른 요약:

유형주요 분야
Siteid, name, slug, projectId, framework (자동 감지), repositoryUrl
Deploymentid, siteId, target (preview / staging / production), status, previewUrl?, createdAt
plancreate_change_plan 제안: 의도된 파일 편집 목록과 사람이 읽을 수 있는 요약; apply_site_patch까지 적용되지 않음
checks작업 공간 검사 매트릭스(린트, 유형, 사용자 정의 CI 후크)의 검사별 결과
summaryrun_checks에서 반환된 checks(성공/실패 횟수)의 롤업

status는 queued, building, ready, failed, canceled 중 하나입니다. ready는 미리 보기 및 프로덕션 배포 모두에 대한 최종 성공 상태입니다. framework는 빌드 시 자동 감지되며 astro, vite, next-export, static-html, custom 또는 unknown 중 하나입니다. 이는 매니페스트에서 설정한 것이 아닙니다.

버전 관리

도구 스키마는 MCP version 필드를 통해 semver를 따릅니다. 주요 변경 사항에는 새로운 도구 이름(apply_site_patch_v2)이 제공됩니다. 이전 이름은 notes에 지원 중단 메모가 포함된 최소 한 번의 릴리스 주기 동안 계속 작동합니다.