AI 도구 연결

AI 도구 연결

이 AppScreenshots 배포에서 MCP가 활성화되어 있으면, 호환되는 AI 도구에 아래 엔드포인트를 등록합니다:

https://appscreenshots.net/api/mcp

HTTP / Streamable HTTP와 OAuth를 선택하세요. 브라우저에서 AppScreenshots 계정으로 로그인하고, 도구가 사용할 프로젝트와 에셋을 선택하고, 프로젝트 생성 허용 여부를 정합니다. 데이터베이스 접근이나 API 키는 필요하지 않습니다.

클라이언트 연결

아래 명령으로 각 클라이언트에 엔드포인트를 등록합니다. 연결 후 클라이언트가 브라우저 로그인을 보여주면 완료하세요.

claude mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcp

codex mcp add appscreenshots --url https://appscreenshots.net/api/mcp
codex mcp login appscreenshots

gemini mcp add --transport http --scope user appscreenshots https://appscreenshots.net/api/mcp

{
  "mcpServers": {
    "appscreenshots": {
      "url": "https://appscreenshots.net/api/mcp"
    }
  }
}

{
  "mcp": {
    "servers": {
      "appscreenshots": {
        "type": "http",
        "url": "https://appscreenshots.net/api/mcp",
        "oauth": {
          "type": "authorization_code",
          "scope": "projects:read projects:write assets:read offline_access"
        }
      }
    }
  }
}

연결 키트

공개 저장소 appscreenshots-mcp에는 위 모든 클라이언트의 설정 파일, 스크린샷 워크플로를 알려주는 선택적 에이전트 Skill, 터미널에서 서버를 점검하는 doctor 명령이 들어 있습니다:

git clone https://github.com/horace68/appscreenshots-mcp.git
node bin/appscreenshots.mjs config claude    # 클라이언트 설정 조각 출력
node bin/appscreenshots.mjs install-skill claude
node bin/appscreenshots.mjs doctor

이 도우미는 설정 출력과 Skill 설치만 합니다. 로컬 stdio 서버가 아니므로 클라이언트 자체의 원격 연결 기능을 사용하세요.

도구

아홉 가지 도구가 Streamable HTTP로 제공됩니다. 클라이언트가 이름에 접두사를 붙일 수 있습니다. 입력 스키마와 계정 권한의 기준은 호스팅 서버입니다.

편집 작업

update_project는 아래의 판별 가능한 작업 목록을 받습니다:

• set_name —— 프로젝트 이름 변경
• add_frame / remove_frame / reorder_frames —— 프레임 관리
• upsert_element —— 요소 삽입 또는 교체. 전체 지오메트리가 필요하며 같은 요소 유형의 생략 필드는 유지됩니다
• patch_element —— 요소 id로 부분 수정. 요소 유형 변경은 불가
• remove_element —— 요소 삭제
• set_background —— 한 프레임의 배경 설정. 공유 배경은 프레임별로 확정됩니다
• set_locales —— 1~20개 로캘과 기본 로캘 설정
• set_canvas —— 캔버스 크기(100~5000)와 모드(separate 또는 continuous)

요소는 타이포그래피, 기기 목업 필드, 이미지 assetId 참조, 도형, 아이콘, rotation, stackOrder를 담습니다. 이미지는 승인된 assetId로만 참조할 수 있습니다 — URL이나 로컬 경로는 사용할 수 없고, 기존 이미지 참조는 서버에 보관되므로 되돌려 보내지 마세요.

논리적 쓰기에는 매번 새 멱등 키를 사용하고, 완전히 동일한 재시도에만 재사용하세요. 리비전 충돌 후에는 최신 버전을 읽고 다시 진행합니다. SQL, HTML, 스크립트를 편집 지시로 사용하지 마세요.

오류

오류는 {code, message} JSON과 isError: true로 반환됩니다:

인증과 제한

서버는 OAuth 2.1 + PKCE 브라우저 로그인을 사용합니다:

• 스코프: projects:read, projects:write(생성·편집을 허용한 경우만), assets:read, offline_access.
• 액세스 토큰은 1시간, 리프레시 토큰은 30일 동안 유효합니다.
• 액세스 토큰은 유효한 그랜트를 요구합니다. 연결을 취소하면 기존 토큰은 즉시 작동을 멈춥니다.
• 속도 제한: 무료 플랜 분당 60회, 유료 플랜 분당 120회 MCP 호출. 초과 시 Retry-After: 60과 함께 HTTP 429를 반환합니다.
• 요청 본문은 2 MB, 프로젝트는 20프레임·프레임당 100요소가 한도입니다.

플랜 권한은 그대로 적용됩니다. 프로젝트 수, 유료 템플릿, 사용자 지정 폰트, 일괄 내보내기 제한은 변하지 않고, 호스팅 AI 요금도 없습니다 — 디자인과 카피는 연결된 AI가 제공합니다.

스크린샷 먼저 준비하기

원본 스크린샷은 먼저 웹사이트 에디터에 업로드하세요. 해당 프로젝트를 승인하거나 동의 페이지에서 개별 에셋을 선택합니다. MCP는 바이너리 업로드 도구를 제공하지 않으며, 채팅에 첨부된 파일은 자동으로 사용할 수 없습니다.

이런 프롬프트를 시도해 보세요:

디자인과 카피는 연결된 AI가 만들고 MCP는 편집 가능한 프로젝트를 저장합니다. get_project_preview는 이미지 바이트가 아니라 에디터 링크와 검토 안내를 반환합니다. 브라우저 도구가 있는 에이전트는 에디터를 열어 스크린샷을 확인하고 MCP로 수정한 뒤 안전하게 다시 불러와 검토할 수 있습니다. 브라우저 로그인은 MCP OAuth와 별개이며, 다시 불러오기 전에 저장되지 않은 편집은 보존해야 합니다. 미리보기와 내보내기는 사용자가 웹사이트 에디터에서 합니다.

접근 관리

Settings → Connected AI tools에서 프로젝트와 에셋 범위를 바꾸거나 연결을 취소할 수 있습니다. 도구는 선택되지 않은 프로젝트에 접근할 수 없습니다. 웹사이트와 AI 도구가 같은 프로젝트를 동시에 편집할 때는 저장 전에 최신 버전을 다시 읽으세요.

브라우저 검토에는 Browserless나 백그라운드 렌더링 대기열이 필요하지 않습니다. 이 MCP는 프로젝트 도구와 브라우저 검토 안내를 제공하며 클라우드 렌더링은 제공하지 않습니다. 브라우저/이미지 도구가 없다면 에이전트는 검증을 주장하는 대신 에디터 링크를 돌려주고 시각 확인이 미완료라고 보고해야 합니다.

문제 해결

클라이언트별 안내와 최신 검증 매트릭스는 연결 키트 문제 해결 가이드를 참고하세요.