yampi-mcp

Claude에서 Yampi 스토어와 대화할 수 있게 해주는 MCP 서버입니다 — 주문 조회, 상품 생성, 재고 조정, 쿠폰 및 오퍼 제작이 가능합니다.

모든 판매자는 Cloudflare에 자신만의 복사본을 호스팅합니다. 이것은 서비스가 아닙니다: 여러분의 자격 증명을 보관하는 사람은 아무도 없습니다. 비공식 프로젝트이며 Yampi와 제휴하지 않았습니다.

작동 방식

Yampi 자격 증명은 스토어가 아닌 사용자에게 속합니다: 한 로그인으로 네 개의 스토어를 운영한다면 네 개 모두 표시됩니다. 한 번 연결하면 각 명령에서 스토어를 선택할 수 있습니다.

Related MCP server: MCP Shopify

설정

Cloudflare 계정(무료 플랜이면 충분)과 Node가 설치되어 있어야 합니다.

git clone https://github.com/Eduardo-Orsi/yampi-mcp && cd yampi-mcp
npm install
cp wrangler.example.jsonc wrangler.jsonc
npx wrangler kv namespace create OAUTH_KV   # paste the returned id into wrangler.jsonc
npx wrangler deploy

Claude 클라이언트(claude.ai, Desktop 또는 Code)에서 https://yampi-mcp.<your-subdomain>.workers.dev/mcp를 가리키는 사용자 지정 커넥터를 추가하세요.

연결 시 화면에서 User-Token과 User-Secret-Key를 입력하라는 메시지가 표시됩니다. Yampi 대시보드의 Perfil › Credenciais de API(프로필 › API 자격 증명)에서 찾을 수 있습니다. 그게 전부입니다 — 만들 비밀번호는 없습니다.

사용 방법

연결되면 일반 대화로 충분합니다:

"6월 1일부터 15일까지 스토어 X가 받은 결제 완료 주문은 몇 건인가요?" "Black T-Shirt라는 상품을 만들어 주세요. 브랜드는 Acme, SKU는 TS-BLACK-M, 가격 R$ 79.90, 재고 20개." "SKU TS-BLACK-M의 가격이 잘못되었습니다 — R$ 89.90으로 변경하고 재고를 5개로 줄이세요." "이번 주에 버려진 장바구니는 무엇이고 합계는 얼마인가요?" "월말까지 유효한 15% 쿠폰을 만들어 주세요. 최소 구매 R$ 100, 50회 사용."

계정에 스토어가 두 개 이상 있으면 어느 스토어인지 말하세요 — 도구는 잘못된 스토어에 아무것도 기록되지 않도록 명시적으로 요구합니다.

제공 기능

⚠️ 실제 API로 검증되지 않음. 나머지 열세 개는 실제 스토어에서 엔드투엔드로 실행되었습니다 — 상품 생성, 가격 변경, 재고 기록, 쿠폰 발행 — 그리고 그 과정에서 필드 이름이 수정되었습니다. 이 두 개는 기존 주문이 필요했지만 테스트 스토어에는 주문이 없었습니다. 엔드포인트는 정확합니다. 요청 본문은 문서에서 가져왔는데, 다른 다섯 개의 쓰기 작업 모두에서 문서에 필수 필드가 최소 하나 이상 누락되어 있었습니다. 첫 호출에서 422가 발생할 것으로 예상하세요 — 메시지에 누락된 필드가 명시됩니다.

의도적으로 하지 않는 일

주문 취소, 환불 처리, 결제 게이트웨이 전환을 하지 않습니다. 환경 변수 뒤에 숨겨진 기능이 아닙니다: 코드 자체가 존재하지 않습니다. 이것들은 API에서 되돌릴 수 없는 작업이며, Claude Desktop과 claude.ai 모두 elicitation을 지원하지 않습니다 — 즉 서버가 진정한 확인을 요청할 방법이 없습니다. 부재만이 누군가의 주의에 의존하지 않는 유일한 보장입니다.

이 금지는 테스트로 검증된 두 곳에서 적용됩니다: 상태 별칭(tools/write.ts)과 모든 요청이 통과하는 경계(yampi.ts)입니다. 근거는 docs/adr/0002에 있습니다.

주문 추적도 제외됩니다: Yampi는 해당 라우트를 시간당 3회 요청으로 제한하여 도구가 실질적으로 쓸모없게 만듭니다 — 두 번 호출하면 에이전트가 20분 동안 멈춥니다.

자격 증명

• OAuth 승인 속성에 암호화되어(AES-GCM) 여러분의 KV에 저장됩니다.

• 이를 암호화하는 키는 액세스 토큰에서 파생된 키로 래핑되며, KV에는 토큰의 해시만 보관됩니다. KV 유출만으로는 자격 증명이 열리지 않습니다.

• Claude는 이를 절대 받지 않습니다: 불투명한 토큰만 볼 수 있습니다.

• 철회는 승인을 삭제하는 것을 의미하며, 다른 연결은 계속 작동합니다.

/authorize는 공개되어 있으며 자격 증명을 검증하므로, 기술적으로 도난된 키를 테스트하는 오라클 역할을 합니다. 그래서 IP당 분당 5회 시도로 제한됩니다.

인스턴스를 특정 스토어로 제한하려면:

npx wrangler secret put ALLOWED_STORES   # e.g. my-store,other-store

API 제한

Yampi는 라우트별 분당 제한이 있습니다: 상품 및 SKU 30 req/min, 주문 읽기 120, 쓰기 30, 일반 60. 서버는 N+1 대신 단일 호출로 관계를 가져오기 위해 include=를 사용하고, 모든 응답에서 X-RateLimit-Remaining을 읽어 할당량이 소진될 때 모델에 경고합니다 — 429를 통해 알게 되는 대신입니다.

문제 발생 시

모든 것에서 403, 읽기도 포함. Yampi 대시보드에서 스토어가 active: false 상태입니다. 비활성 스토어는 모든 라우트를 거부합니다. 다시 활성화한 후 커넥터를 다시 연결하세요.

쓰기에서 422. 메시지는 Yampi가 거부한 정확한 필드를 명시합니다 — 서버는 errors 객체 전체를 전달합니다. Claude는 일반적으로 다음 시도에서 스스로 수정합니다.

"자격 증명 없는 승인". 승인이 속성을 잃었습니다. 커넥터를 제거하고 다시 추가하세요.

자격 증명 전환. 다시 연결하기만 하면 됩니다: 새 승인이 이전 것을 대체합니다. 다시 연결하지 않고 액세스를 차단하려면 KV 네임스페이스를 삭제하세요.

목록에서 스토어가 누락됨. 비활성 상태이거나 자격 증명이 해당 스토어에 도달하지 못하는 것입니다. describe_store를 실행하여 서버가 볼 수 있는 것을 확인하세요.

Yampi API 특이사항

실제 API 테스트를 통해 발견된 사항입니다. 모두 몇 시간을 태울 수 있으며 문서에는 명확하지 않습니다:

• 필터는 배열 구문이 필요합니다. ?status_id=4는 조용히 무시되고 전체 데이터셋을 반환합니다; ?status_id[]=4는 필터링합니다. active[]도 동일합니다. 필터링되지 않는 필터는 필터가 없는 것보다 나쁩니다: 에이전트가 7월 데이터를 보았다고 믿고 55,000건의 주문을 요약합니다.

• 날짜는 독특한 형식을 사용합니다: ?date=created_at:2026-06-01|2026-06-30. 다른 형식은 500을 반환하거나 무시됩니다.

• filters[...]는 필터링하지 않습니다. 응답을 scroll_id 페이지네이션으로 전환할 뿐입니다.

• /auth/me는 GET이 아닌 POST이며, 자격 증명의 모든 스토어를 반환합니다 — 자격 증명이 스토어가 아닌 사용자에게 속하기 때문입니다.

• 주문 include는 폐쇄된 열거형입니다: items, customer, marketplace, status, statuses, shipping_address, promocode, transactions, comments, files, discounts, seller, labels. payments는 없습니다.

• GET 응답은 Yampi 측에서 30분 동안 캐시됩니다. 에이전트 맥락에서 이는 거짓말입니다: 상품을 만들고 다시 읽어달라고 하면 이전 상태를 받습니다. 이 서버는 모든 읽기에 ?skipCache=true를 보냅니다.

• 재고는 SKU 필드가 아닙니다. SKU의 quantity는 항상 null입니다 — 실제 스토어의 실제 SKU에서도 마찬가지입니다. 재고는 /logistics/stocks(재고 위치)에 있으며 /catalog/skus/{id}/stocks에서 SKU와 조인됩니다. 그리고 stock_id는 /logistics/warehouses의 id가 아닙니다 — 이는 완전히 다른 리소스입니다.

• 쿠폰 discount_type은 p 또는 v만 허용합니다, percentage/fixed는 허용되지 않습니다.

• 쿠폰 날짜는 Y-m-d H:i:s 형식이 필요합니다. 날짜만 있으면 422를 반환합니다.

• PUT /catalog/skus/{id}는 부분 업데이트에도 product_id와 price_cost가 필요합니다.

• 상품 생성에는 simple, brand_id 및 skus.*.blocked_sale이 필요합니다, 어느 것도 명확하지 않습니다.

• active: false인 스토어는 모든 것에서 403을 반환합니다, 읽기도 포함. 이 서버는 연결 시 이러한 스토어를 필터링하여 모델이 실패할 수밖에 없는 옵션을 제공받지 않도록 합니다.

• 422 응답에는 실패한 정확한 필드를 명시하는 errors 객체가 포함됩니다. 상태 코드만 표시하는 대신 모델에 전달할 가치가 있습니다 — 스스로 수정할 수 있게 해주기 때문입니다.

개발

npm test              # 32 unit tests, no network
npm run typecheck
npm run dev           # wrangler dev

자체 스토어로 테스트

단위 테스트 스위트는 가짜 fetch를 사용하여 서버의 로직을 검증합니다. Yampi가 엔드포인트, 필드 이름 또는 필터 구문을 변경하는 것을 감지할 수 없습니다 — 그리고 이 프로젝트를 구축하는 동안 그런 일이 반복적으로 발생했습니다. 나머지 절반은 실제 API를 호출하는 통합 테스트 스위트가 담당하며, 읽기 전용으로 아무것도 생성하거나 변경하지 않습니다:

cp .env.example .env    # fill in the alias and credentials of YOUR store
npm run test:integration

스토어 검색이 작동하는지, 상태 별칭이 존재하는지, 상태별 필터링이 실제로 필터링되는지, 날짜 형식이 허용되는지, include가 관계를 확장하는지, 할당량 헤더가 도착하는지 확인합니다. 하나라도 실패하면 API가 변경된 것이며 서버는 깨지기 전에 거짓말을 시작할 것입니다.

아키텍처에는 하나의 규칙이 있습니다: 어떤 도구도 HTTP를 직접 말하지 않습니다. 모든 것은 src/yampi.ts를 통과합니다. 이것이 "금지된 라우트에 도달하지 않는다"는 약속을 감사 가능하게 만드는 이유입니다 — 전체 표면이 하나의 파일에 들어 있습니다.

프로젝트 용어집은 CONTEXT.md에 있습니다. 결정 사항은 docs/adr/에 있습니다.

알려진 제한 사항

• 주문 추적 없음 (Yampi의 3 req/h 제한으로 사용 불가).

• 배너, 무료 배송 규칙, 점진적 할인 또는 콤보 없음.

• advance_order_status와 add_order_comment는 실제 API에서 실행된 적 없음.

• 재고는 스토어의 첫 번째 등록 재고 위치에 기록됩니다. 여러 위치를 사용하는 경우 src/tools/write.ts의 defaultStockId()를 조정해야 합니다.

기여

풀 리퀘스트를 환영합니다. 포크하여 main에 PR을 열면 CI가 타입체크와 단위 테스트를 실행합니다. 버그 수정보다 큰 작업은 먼저 이슈를 열어주세요.

패치 품질과 관계없이 병합되지 않을 것이 하나 있습니다: 주문을 취소하거나, 구매를 환불하거나, 결제 게이트웨이를 전환하는 모든 것, 간접적인 경로를 포함합니다. 그 부재가 이 프로젝트의 핵심입니다 — 근거는 ADR 0002에 있습니다.

자세한 내용은 CONTRIBUTING.md에 있습니다. 보안 문제를 발견했나요? 공개 이슈를 열지 마세요 — SECURITY.md를 참조하세요.

라이선스

MIT — LICENSE 참조.

assets/에 있는 Yampi 로고는 Yampi의 상표이며, 이 서버가 통신하는 플랫폼을 식별하기 위한 목적으로만 사용됩니다. 이 로고는 MIT 라이선스의 적용을 받지 않으며, 이 프로젝트는 Yampi와 제휴 관계가 없고 Yampi의 보증을 받지 않습니다.