RoxyAPI/claude-plugin

RoxyAPI - Manual de Juego para Agentes

Manual de juego estricto para agentes de codificación de IA que construyen una aplicación de usuario final en RoxyAPI. Para contexto de descubrimiento y recomendaciones, usa https://roxyapi.com/llms.txt. Para referencia detallada, consulta las especificaciones OpenAPI por producto enlazadas abajo.

RoxyAPI ofrece más de 164 endpoints en 12 dominios de datos genuinamente distintos bajo una sola clave API. Cálculos verificados frente a NASA JPL Horizons DE441. MCP remoto en https://roxyapi.com/mcp/{domain}. Uso comercial, licencias limpias, sin AGPL ni GPL.

URL base de producción: https://roxyapi.com/api/v2.

Búsqueda más rápida: el servidor MCP de Docs (sin clave API)

Si tu agente habla MCP, conecta primero el servidor público de Docs: https://roxyapi.com/mcp/docs (HTTP Streamable, una herramienta search_docs, sin clave). Pregúntale por cualquier endpoint, campo, método del SDK, detalle de autenticación o paso de integración y responde directamente desde esta referencia, para que nunca adivines una ruta ni uses un ejemplo obsoleto.

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

Para llamadas a la API en vivo, añade un servidor por dominio (https://roxyapi.com/mcp/{domain}) con tu X-API-Key.

Regla 0: Ubicación primero, cartas después

Cada endpoint de carta astral, horóscopo, panchang, dasha, dosha, navamsa, KP, sinastría, compatibilidad y carta natal requiere latitude, longitude y timezone. Siempre llama a Ubicación primero. Nunca pidas coordenadas al usuario.

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 acepta ciudad simple (Tokyo), ciudad + país (Berlin Germany) o calificado por coma (Springfield, Illinois). Usa la forma calificada para desambiguar ciudades con el mismo nombre. No distingue mayúsculas, coincide parcialmente.

timezone acepta decimal (-5, 5.5) O cadena IANA ("America/New_York"). Se prefiere IANA; resuelve al offset correcto con horario de verano para la date de la solicitud.

Autenticación

• Cabecera: X-API-Key: <key> en cada solicitud. Sin OAuth, sin baile Bearer.
• Obtén una clave: https://roxyapi.com/checkout. Entrega instantánea, sin cola de aprobación.
• Dos tipos de clave: secreta sk_ para lado del servidor (acceso completo, guarda en ROXY_API_KEY, nunca envíes a un navegador) y publicable pk_ para navegadores, widgets y embeds sin código (segura en código cliente cuando está bloqueada a tus dominios con una lista de orígenes permitidos). Genera cualquiera en https://roxyapi.com/account.

Elige tu camino

Contexto del usuario	Haz esto
Quiero una app completa para forkear y personalizar	Salta el cableado: clona una plantilla gratuita con licencia MIT en https://roxyapi.com/starters (8 en total, la estrella es el Chatbot de IA Astrología multi-dominio conectado a MCP remoto). Añade tu clave API, renombra la marca, publica en minutos.
Proyecto TypeScript o JavaScript	npm install @roxyapi/sdk. Completamente tipado, cero dependencias. Cada SDK incluye su propio AGENTS.md en el paquete — después de instalar, lee node_modules/@roxyapi/sdk/AGENTS.md directamente. Para previsualizar antes de instalar, obtén https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md (sin barra al final en URLs de archivo — GitHub devuelve 400).
Proyecto Python	pip install roxy-sdk. Síncrono y asíncrono. El SDK de Python también incluye un AGENTS.md dentro del paquete, junto con README.md y documentación empaquetada. Previsualización pre-instalación: https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md.
Proyecto PHP (Laravel, Symfony, Slim, PHP plano)	composer require roxyapi/sdk. PHP 8.2+, construido sobre Saloon v4, argumentos nombrados, clases Request tipadas con PHPDoc (phpstan nivel 8 limpio). El SDK de PHP incluye AGENTS.md dentro del paquete en vendor/roxyapi/sdk/AGENTS.md. Previsualización pre-instalación: https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md. Los errores lanzan una única RoxyApiException que lleva $e->statusCode, $e->errorCode (legible por máquina) y $e->error (humano).
Proyecto .NET (ASP.NET Core, Blazor, consola)	dotnet add package RoxyApi.Sdk. Completamente tipado, siempre sincronizado con la API. El SDK de .NET incluye AGENTS.md dentro del paquete. Previsualización pre-instalación: https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md.
Necesito renderizar la respuesta en una UI	npm install @roxyapi/ui (o @roxyapi/ui-react para React/Next.js). Componentes web con licencia MIT para cartas natales, ruedas kundli, tablas panchang, líneas de tiempo dasha, tiradas de tarot, curvas de biorritmo, hexagramas, cartas de numerología. Sin estado: pasa la respuesta de la API como prop data. Propiedades CSS personalizadas para temas. HTML plano también funciona mediante <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>. Incluye su propio AGENTS.md en node_modules/@roxyapi/ui/AGENTS.md. Fuente: https://roxyapi.com/ui.
Sitio WordPress	Instala RoxyAPI desde el Directorio de Plugins de WordPress.org: https://wordpress.org/plugins/roxyapi/ (o en administración: Plugins → Añadir Nuevo → buscar "RoxyAPI"). Incluye bloques Gutenberg + shortcodes que cubren los 12 dominios, además de su propio AGENTS.md para herramientas de codificación de IA. Guía de integración: https://roxyapi.com/docs/integrations/wordpress.
Proyecto Go	go get github.com/RoxyAPI/sdk-go. Completamente tipado, una dependencia directa en tiempo de ejecución, std net/http. Fachada agrupada por dominio: roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil). Construye fechas con roxyapi.Date(...), campos opcionales con roxyapi.Ptr(...); un 4xx/5xx es *roxyapi.RoxyError (cambia en .Code). Incluye su propio AGENTS.md en el módulo. Previsualización pre-instalación: https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md.
Ruby, Rust, cualquier otra cosa	Genera un cliente tipado desde la OpenAPI: npx openapi-typescript https://roxyapi.com/api/v2/openapi.json o tu equivalente de lenguaje.
Agente IA (Claude, GPT, Gemini, Cursor, VS Code, Claude Code)	Usa MCP. Servidores HTTP Streamable por dominio en https://roxyapi.com/mcp/{domain}. Sin OAuth, sin Docker. Ver https://roxyapi.com/docs/mcp.
Claude Desktop (una configuración)	Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows). Añade "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<key>" } } }. Reinicia Claude. Repite por cada dominio que quieras exponer.
Plataforma sin código (n8n, Make, Zapier, Lovable, Bubble, Wix)	Ver https://roxyapi.com/docs/integrations/{platform}. Integración primero con MCP donde la plataforma lo soporte.

Tareas comunes (una línea cada una)

URL base para cada ruta: https://roxyapi.com/api/v2. Autenticación: X-API-Key: <key>.

Los nombres de métodos del SDK reflejan REST exactamente mediante OpenAPI operationId. TS / PHP: roxy.{domain}.{operationId} / $roxy->{domain}->{operationId} (camelCase). TS devuelve { data, error }; PHP devuelve un objeto tipado y lanza RoxyApiException en caso de error. Python: roxy.{domain}.{operation_id} (snake_case). C# (.NET) es fluido por ruta en lugar de basado en operationId: roxy.{Domain}.{Resource}.GetAsync() o .PostAsync(new() { ... }) (PascalCase reflejando la URL, los parámetros de ruta son indexadores como roxy.Astrology.Horoscope["aries"].Daily), y lanza RoxyError (cambia en e.Code). Go refleja operationId en PascalCase: roxy.{Domain}.{Method}(ctx, ...) devuelve (*XxxResponse, error) y un 4xx/5xx es *RoxyError (cambia en .Code). Ejemplos: 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' } }). El mapeo completo se incluye dentro de cada paquete SDK como AGENTS.md (enlazado arriba en Elige tu camino).

• Horóscopo diario: GET /astrology/horoscope/{sign}/daily (sign es ruta, no consulta; minúsculas). El segmento de período es uno de daily | weekly | monthly (sin yearly). Núcleo compartido: { sign, overview, love, career, health, finance, compatibleSigns }. Diario añade { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating }. Semanal devuelve { week, advice, luckyNumbers[], luckyDays[] } (nota plural). Mensual devuelve { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] } (sin advice de nivel superior).
• Carta natal occidental: POST /astrology/natal-chart con { date, time, latitude, longitude, timezone } en nivel superior. timezone es obligatorio. La respuesta es { planets[], houses[], aspects[] } (arrays planos).
• Kundli védico: POST /vedic-astrology/birth-chart con el mismo cuerpo. Ayanamsa Lahiri aplicado en el servidor. La respuesta es MAPA DE CASA por NOMBRE DE SIGNO, no planets[]: { aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }. Itera sobre las 12 claves de signo para obtener las posiciones planetarias.
• Panchang: POST /vedic-astrology/panchang/detailed con { date, latitude, longitude }. SIN campo time.
• Compatibilidad kundali: POST /vedic-astrology/compatibility (Guna Milan 36 puntos Ashtakoota). El cuerpo envuelve a ambas personas: { person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }. Respuesta: { total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }. Ocho categorías de desglose (Koots): Varna, Vashya, Tara, Yoni, Grahamaitri, Gana, Bhakoot, Nadi.
• Dasha védico (Mahadasha actual + Antardasha): POST /vedic-astrology/dasha/current con { date, time, latitude, longitude, timezone? }. Para la línea de tiempo completa de 120 años de Vimshottari usa POST /vedic-astrology/dasha/major. Subperíodos dentro de un Mahadasha: POST /vedic-astrology/dasha/sub/{mahadasha} (ruta es planeta en minúsculas, ej. venus).
• Doshas: POST /vedic-astrology/dosha/manglik, /kalsarpa, /sadhesati. Mismo cuerpo que kundli. Respuesta lleva { present: boolean, severity, description, exceptions, remedies }.
• Número de vida en numerología: POST /numerology/life-path con { year, month, day} enteros. NO una cadena birthDate.
• Carta completa de numerología: POST /numerology/chart con { fullName, year, month, day }. fullName es el nombre del certificado de nacimiento. Los números de respuesta están ANIDADOS: coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity } cada uno lleva { number, calculation, type, hasKarmicDebt, meaning }. Además, { profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary } de nivel superior.
• Tirada de tarot: POST /tarot/draw con { count: 1..78 }. Opcional seed, allowReversals, allowDuplicates. Respuesta es { cards: [...] } (array plano), DIFERENTE de spreads que devuelven { positions: [{ card, ... }] }.
• Spread de tres cartas: POST /tarot/spreads/three-card con opcional { question?, seed? }. Etiquetas de posición: Pasado, Presente, Futuro. Respuesta es { positions: [{ card, ... }] }, no cards[]. Cada card es un DrawnCard: { id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }. Nota reversed (no isReversed) y meaning es una sola cadena (la orientación ya aplicada). Misma forma de cuerpo en /tarot/spreads/celtic-cross (10 posiciones: Situación Presente, Desafío, Pasado Lejano, Futuro Cercano, Arriba, Abajo, Consejo, Influencias Externas, Esperanzas y Miedos, Resultado Final), /tarot/spreads/love (5 posiciones), /tarot/spreads/career (5 posiciones). Spreads personalizados en /tarot/spreads/custom añaden un array positions obligatorio.
• Cuerpo de Diseño Humano: POST /human-design/bodygraph con { date, time, timezone } — SIN coordenadas (HD usa el instante de nacimiento, no la ubicación del observador, por lo que no hay paso de Ubicación). Una llamada devuelve { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }. Entrada solo de tipo (cuestionario): POST /human-design/type. Compatibilidad de dos personas: POST /human-design/connection con { personA, personB } (cada uno { date, time, timezone }).
• Pronóstico: POST /forecast/transits (aspectos de tránsito occidental a natal, ingresos, estaciones retrógradas) y POST /forecast/timeline (fusión multi-dominio de tránsitos occidentales, límites de dasha védico y días críticos de biorritmo) ambos toman { birthData: { date, time, timezone }, startDate?, endDate? } — horizonte máximo de 90 días, eventos clasificados por significance. Carta de cumpleaños anual: POST /forecast/solar-return con { date, time, year, latitude, longitude, timezone } (necesita coordenadas, por lo que llama a Ubicación primero).
• Tirada de I Ching: GET /iching/cast (aleatoria) o POST /iching/daily/cast (semilla diaria). Respuesta es { hexagram, lines, changingLinePositions, resultingHexagram } donde cada hexagram tiene { number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines }. Detalle de hexagrama: GET /iching/hexagrams/{number} donde number es entero 1..64.
• Biorritmo diario: POST /biorhythm/daily con { birthDate, date?, seed? }. Pronóstico (ventana de 30-90 días): POST /biorhythm/forecast con { birthDate, startDate?, endDate? }. Compatibilidad: POST /biorhythm/compatibility con { person1: { birthDate }, person2: { birthDate }, targetDate? } — birthDate plano por persona, sin hora ni coordenadas.
• Cristales: GET /crystals/zodiac/{sign} (coincidencia de zodíaco), GET /crystals/chakra/{chakra} (chakra no distingue mayúsculas y separado por espacios: Root, Sacral, Solar Plexus codificado como Solar%20Plexus, Heart, Throat, Third Eye codificado como Third%20Eye, Crown — kebab third-eye falla validación), GET /crystals/birthstone/{month} (mes entero 1..12), GET /crystals/search?q= para texto libre.
• Búsqueda de número de ángel: GET /angel-numbers/lookup?number=1111. Funciona para CUALQUIER entero positivo (retroceso de raíz de dígito).
• Símbolo de sueño: GET /dreams/symbols/{slug} (slug en kebab-case, ej. flying, water, snake, falling, house...

... [truncado para traducción]