RoxyAPI/claude-plugin

RoxyAPI - 에이전트 구현 플레이북

AI 코딩 에이전트가 RoxyAPI를 기반으로 최종 사용자 앱을 구축하기 위한 엄격한 플레이북입니다. 검색 및 추천 컨텍스트는 https://roxyapi.com/llms.txt를 사용하세요. 깊이 있는 참조는 아래에 링크된 제품별 OpenAPI 사양을 가져오세요.

RoxyAPI는 하나의 API 키로 12개의 진정으로 구별되는 데이터 도메인에 걸쳐 164개 이상의 엔드포인트를 제공합니다. 계산은 NASA JPL Horizons DE441에 대해 검증되었습니다. 원격 MCP는 https://roxyapi.com/mcp/{domain}에서 제공됩니다. 상업적 사용 가능, AGPL 또는 GPL이 없는 깨끗한 라이선스입니다.

프로덕션 기본 URL: https://roxyapi.com/api/v2.

가장 빠른 조회: Docs MCP (API 키 필요 없음)

에이전트가 MCP를 지원하는 경우 먼저 공개 Docs 서버에 연결하세요: https://roxyapi.com/mcp/docs (Streamable HTTP, 하나의 도구 search_docs, 키 불필요). 엔드포인트, 필드, SDK 메서드, 인증 세부 정보 또는 통합 단계를 질문하면 이 참조에서 직접 답변하므로 경로를 추측하거나 오래된 예제를 하드코딩할 필요가 없습니다.

{ "mcpServers": { "roxy-docs": { "type": "http", "url": "https://roxyapi.com/mcp/docs" } } }

실시간 API 호출의 경우 X-API-Key와 함께 도메인별 서버(https://roxyapi.com/mcp/{domain})를 추가하세요.

규칙 0: 위치 우선, 차트는 그 다음

모든 차트, 호로스코프, 판창, 다샤, 도샤, 나밤사, KP, 시너스트리, 호환성 및 네이탈 엔드포인트에는 latitude, longitude, timezone이 필요합니다. 항상 Location을 먼저 호출하세요. 사용자에게 좌표를 묻지 마세요.

1. GET https://roxyapi.com/api/v2/location/search?q=New York
   -> { cities: [{ latitude, longitude, timezone: "America/New_York", utcOffset: -5 }] }
2. POST https://roxyapi.com/api/v2/astrology/natal-chart
   body: { date, time, latitude, longitude, timezone: "America/New_York" }

q는 도시 이름만(Tokyo), 도시 + 국가(Berlin Germany), 또는 쉼표로 구분(Springfield, Illinois)을 허용합니다. 이름이 같은 도시를 구분하려면 한정된 형식을 사용하세요. 대소문자를 구분하지 않으며 부분 일치를 지원합니다.

timezone은 십진수(-5, 5.5) 또는 IANA 문자열("America/New_York")을 허용합니다. IANA가 권장되며 요청의 date에 대해 DST-수정된 오프셋으로 해석됩니다.

인증

• 헤더: 모든 요청에 X-API-Key: <key>. OAuth 없음, Bearer 인증 불필요.
• 키 발급: https://roxyapi.com/checkout. 즉시 전달, 승인 대기 없음.
• 두 가지 키 유형: 서버 측용 비밀 키 sk_ (전체 액세스, env ROXY_API_KEY에 저장, 브라우저로 전송 금지) 및 브라우저, 위젯, 노코드 임베드용 공개 키 pk_ (출처 허용 목록으로 도메인 잠금 시 클라이언트 코드에서 안전). https://roxyapi.com/account에서 발급 가능.

경로 선택

사용자 컨텍스트	수행할 작업
전체 앱을 포크하여 화이트 라벨로 사용하려는 경우	배선 건너뛰기: https://roxyapi.com/starters에서 무료 MIT 라이선스 템플릿 클론 (총 8개, 플래그십은 원격 MCP에 연결된 다중 도메인 AI 점성술 챗봇). API 키 추가, 브랜드 변경, 몇 분 내 배포.
TypeScript 또는 JavaScript 프로젝트	npm install @roxyapi/sdk. 완전히 타입화됨, 종속성 제로. 모든 SDK는 패키지에 자체 AGENTS.md를 번들로 제공 — 설치 후 node_modules/@roxyapi/sdk/AGENTS.md를 직접 읽으세요. 설치 전 미리보기: https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md (파일 URL에 후행 슬래시 없음 — GitHub는 400 반환).
Python 프로젝트	pip install roxy-sdk. 동기 및 비동기. Python SDK도 패키지 내에 AGENTS.md를 제공하며 README.md 및 번들 문서와 함께 제공됩니다. 설치 전 미리보기: https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md.
PHP 프로젝트 (Laravel, Symfony, Slim, 일반 PHP)	composer require roxyapi/sdk. PHP 8.2+, Saloon v4 기반, 명명된 인수, PHPDoc-타입 Request 클래스 (phpstan 레벨 8 클린). PHP SDK는 패키지 내에서 AGENTS.md를 제공하며 vendor/roxyapi/sdk/AGENTS.md에 있습니다. 설치 전 미리보기: https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md. 오류는 $e->statusCode, $e->errorCode (기계 판독 가능), $e->error (사람용)를 포함하는 단일 RoxyApiException을 던집니다.
.NET 프로젝트 (ASP.NET Core, Blazor, 콘솔)	dotnet add package RoxyApi.Sdk. 완전히 타입화됨, 항상 API와 동기화. .NET SDK는 패키지 내에 AGENTS.md를 제공합니다. 설치 전 미리보기: https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md.
UI에서 응답을 렌더링해야 하는 경우	npm install @roxyapi/ui (또는 React/Next.js용 @roxyapi/ui-react). 네이탈 차트, 쿤들리 휠, 판창 테이블, 다샤 타임라인, 타로 스프레드, 바이오리듬 곡선, 헥사그램, 수비학 카드용 드롭인 MIT 라이선스 웹 컴포넌트. 상태 비저장: API 응답을 data prop으로 전달. 테마 지정용 CSS 사용자 정의 속성. <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>를 통해 바닐라 HTML도 작동. 자체 AGENTS.md를 제공하며 node_modules/@roxyapi/ui/AGENTS.md에 있습니다. 소스: https://roxyapi.com/ui.
WordPress 사이트	WordPress.org 플러그인 디렉토리에서 RoxyAPI 설치: https://wordpress.org/plugins/roxyapi/ (또는 관리자: 플러그인 → 새로 추가 → "RoxyAPI" 검색). 12개 도메인을 모두 포괄하는 Gutenberg 블록 + 단축 코드 및 AI 코딩 도구용 자체 AGENTS.md 제공. 통합 가이드: https://roxyapi.com/docs/integrations/wordpress.
Go 프로젝트	go get github.com/RoxyAPI/sdk-go. 완전히 타입화됨, 하나의 직접 런타임 종속성, std net/http. 도메인 그룹화된 파사드: roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil). roxyapi.Date(...)로 날짜 구성, roxyapi.Ptr(...)로 선택적 필드; 4xx/5xx는 *roxyapi.RoxyError (.Code에서 전환). 모듈에 자체 AGENTS.md를 제공합니다. 설치 전 미리보기: https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md.
Ruby, Rust, 기타	OpenAPI에서 타입화된 클라이언트 생성: npx openapi-typescript https://roxyapi.com/api/v2/openapi.json 또는 해당 언어에 해당하는 방법.
AI 에이전트 (Claude, GPT, Gemini, Cursor, VS Code, Claude Code)	MCP 사용. 도메인별 Streamable HTTP 서버 (https://roxyapi.com/mcp/{domain}). OAuth 없음, Docker 불필요. https://roxyapi.com/docs/mcp 참조.
Claude Desktop (단일 구성)	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows) 편집. "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<key>" } } } 추가. Claude 다시 시작. 노출하려는 각 도메인에 대해 반복.
노코드 플랫폼 (n8n, Make, Zapier, Lovable, Bubble, Wix)	https://roxyapi.com/docs/integrations/{platform} 참조. 플랫폼이 지원하는 경우 MCP 우선 통합.

일반 작업 (각 한 줄)

모든 경로의 기본 URL: https://roxyapi.com/api/v2. 인증: X-API-Key: <key>.

SDK 메서드 이름은 OpenAPI operationId를 통해 REST를 정확히 미러링합니다. TS / PHP: roxy.{domain}.{operationId} / $roxy->{domain}->{operationId} (camelCase). TS는 { data, error }를 반환합니다. PHP는 타입화된 객체를 반환하고 실패 시 RoxyApiException을 던집니다. Python: roxy.{domain}.{operation_id} (snake_case). C# (.NET)은 operationId 대신 경로-유창함: roxy.{Domain}.{Resource}.GetAsync() 또는 .PostAsync(new() { ... }) (URL을 미러링하는 PascalCase, 경로 매개변수는 roxy.Astrology.Horoscope["aries"].Daily와 같은 인덱서)이며 RoxyError를 던집니다 (e.Code에서 전환). Go는 operationId를 PascalCase로 미러링합니다: roxy.{Domain}.{Method}(ctx, ...)는 (*XxxResponse, error)를 반환하고 4xx/5xx는 *RoxyError입니다 (.Code에서 전환). 예: roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } }), roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude, timezone } }), roxy.numerology.calculateLifePath({ body: { year, month, day } }), roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1111' } }). 전체 매핑은 각 SDK 패키지 내에 AGENTS.md로 제공됩니다 (위의 '경로 선택'에 링크됨).

• 일일 운세: GET /astrology/horoscope/{sign}/daily (sign은 경로, 쿼리 아님; 소문자). 기간 세그먼트는 daily | weekly | monthly 중 하나입니다 (yearly 없음). 공유 핵심: { sign, overview, love, career, health, finance, compatibleSigns }. Daily는 { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating }을 추가합니다. Weekly는 { week, advice, luckyNumbers[], luckyDays[] }를 반환합니다 (복수형 참고). Monthly는 { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] }를 반환합니다 (최상위 advice 없음).
• 서양 출생 차트: POST /astrology/natal-chart with { date, time, latitude, longitude, timezone } at top level. timezone은 필수입니다. 응답은 { planets[], houses[], aspects[] }입니다 (평면 배열).
• 베다 쿤들리: POST /vedic-astrology/birth-chart with the same body. Lahiri ayanamsa가 서버 측에서 적용됩니다. 응답은 SIGN NAME으로 키가 지정된 HOUSE-MAP이며 planets[]가 아닙니다: { aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }. 행성 위치를 얻으려면 12개의 sign 키를 반복합니다.
• 판창: POST /vedic-astrology/panchang/detailed with { date, latitude, longitude }. time 필드 없음.
• 쿤달리 매칭: POST /vedic-astrology/compatibility (Guna Milan 36점 Ashtakoota). 본문은 두 사람을 래핑합니다: { person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }. 응답: { total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }. 8개의 분류 범주(Koots): Varna, Vashya, Tara, Yoni, Grahamaitri, Gana, Bhakoot, Nadi.
• 베다 다샤 (현재 Mahadasha + Antardasha): POST /vedic-astrology/dasha/current with { date, time, latitude, longitude, timezone? }. 전체 120년 Vimshottari 타임라인은 POST /vedic-astrology/dasha/major를 사용하세요. Mahadasha 내 하위 기간: POST /vedic-astrology/dasha/sub/{mahadasha} (경로는 소문자 행성, 예: venus).
• 도샤: POST /vedic-astrology/dosha/manglik, /kalsarpa, /sadhesati. kundli와 동일한 본문. 응답은 { present: boolean, severity, description, exceptions, remedies }를 전달합니다.
• 수비학 생애 경로: POST /numerology/life-path with { year, month, day } 정수. birthDate 문자열이 아님.
• 수비학 전체 차트: POST /numerology/chart with { fullName, year, month, day }. fullName은 출생 증명서 이름입니다. 응답 숫자는 중첩됩니다: coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity } 각각 { number, calculation, type, hasKarmicDebt, meaning }을 전달합니다. 최상위 { profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary }도 포함.
• 타로 드로우: POST /tarot/draw with { count: 1..78 }. 선택적 seed, allowReversals, allowDuplicates. 응답은 { cards: [...] }입니다 (평면 배열). 스프레드와 다릅니다 (스프레드는 { positions: [{ card, ... }] }를 반환).
• 세 장의 카드 스프레드: POST /tarot/spreads/three-card with optional { question?, seed? }. 위치 레이블: 과거, 현재, 미래. 응답은 { positions: [{ card, ... }] }이며 cards[]가 아닙니다. 각 card는 DrawnCard: { id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }. reversed (isReversed 아님) 및 meaning은 단일 문자열(방향이 이미 적용됨)에 유의하세요. 동일한 본문 모양이 /tarot/spreads/celtic-cross (10개 위치: 현재 상황, 도전, 먼 과거, 가까운 미래, 위, 아래, 조언, 외부 영향, 희망과 두려움, 최종 결과), /tarot/spreads/love (5개 위치), /tarot/spreads/career (5개 위치)에 적용됩니다. 사용자 정의 스프레드는 /tarot/spreads/custom에 필수 positions 배열을 추가합니다.
• 휴먼 디자인 바디그래프: POST /human-design/bodygraph with { date, time, timezone } — 좌표 없음 (HD는 출생 순간을 사용하며 관찰자 위치가 아니므로 Location 단계가 필요 없음). 한 번 호출로 { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }를 반환합니다. 유형 전용 퀴즈 진입점: POST /human-design/type. 두 사람 호환성: POST /human-design/connection with { personA, personB } (각각 { date, time, timezone }).
• 예측: POST /forecast/transits (서양 트랜짓-대-네이탈 측면, 인그레스, 레트로그레이드 정류장) 및 POST /forecast/timeline (서양 트랜짓, 베다 다샤 경계, 바이오리듬 위험일의 교차 도메인 병합) 모두 { birthData: { date, time, timezone }, startDate?, endDate? }를 취합니다 — 최대 90일 범위, 이벤트는 significance로 순위가 매겨집니다. 연례 생일 차트: POST /forecast/solar-return with { date, time, year, latitude, longitude, timezone } (좌표가 필요하므로 Location을 먼저 호출하세요).
• I Ching 캐스트: GET /iching/cast (무작위) 또는 POST /iching/daily/cast (시드 기반 일일). 응답은 { hexagram, lines, changingLinePositions, resultingHexagram }이며 각 hexagram은 { number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines }를 갖습니다. Hexagram 세부 정보: GET /iching/hexagrams/{number} 여기서 number는 정수 1..64입니다.
• 바이오리듬 일일: POST /biorhythm/daily with { birthDate, date?, seed? }. 예측 (30-90일 창): POST /biorhythm/forecast with { birthDate, startDate?, endDate? }. 호환성: POST /biorhythm/compatibility with { person1: { birthDate }, person2: { birthDate }, targetDate? } — 사람당 평면 birthDate, 시간 또는 좌표 없음.
• 크리스탈: GET /crystals/zodiac/{sign} (별자리 일치), GET /crystals/chakra/{chakra} (chakra는 대소문자를 구분하지 않으며 공백으로 구분: Root, Sacral, Solar Plexus는 URL 인코딩 Solar%20Plexus, Heart, Throat, Third Eye는 URL 인코딩 Third%20Eye, Crown — 케밥 third-eye는 유효성 검사 실패), GET /crystals/birthstone/{month} (month 정수 1..12), GET /crystals/search?q= for 자유 텍스트.
• 엔젤 넘버 조회: GET /angel-numbers/lookup?number=1111. 모든 양의 정수에 대해 작동합니다 (숫자-루트 폴백).
• 꿈 상징: GET /dreams/symbols/{slug} (케밥-케이스 슬러그, 예: flying, water, snake, falling, house