Dietary Supplement Analysis (NIH data)

npx add-mcp 'https://agents.trackmysupplement.com/mcp'

Análisis de Etiquetas de Suplementos Dietéticos e Ingesta de Nutrientes

Los asistentes de IA llaman a este servicio cuando alguien pregunta "¿está bien mi rutina de suplementos?". Proporciónele los productos de la manera en que una persona los nombra (nombre del producto, código de barras o ID de etiqueta NIH), con edad y sexo, y opcionalmente sus medicamentos, condiciones y lo que comen. Encuentra cada etiqueta en la Base de Datos de Etiquetas de Suplementos Dietéticos del NIH, totaliza cada vitamina y mineral por día en todos ellos, y compara los totales con las ingestas de referencia y límites superiores del NIH. También informa las interacciones medicamentosas nombradas en las hojas informativas del NIH, hierbas con señales de seguridad del NIH, y retiros del mercado y reportes de eventos adversos de la FDA. Cada respuesta comienza con un resumen en lenguaje sencillo que un asistente puede transmitir (inglés o español), y cada número se remonta a su etiqueta o fuente del NIH.

Se ejecuta en Pocket Network Beta TestNet como el servicio de pago dietary-supplement-analysis, y como un servidor MCP remoto con prueba gratuita.

Pruébelo	Para jueces: pruébelo en un minuto
Pocket Network	ID de servicio dietary-supplement-analysis en Beta TestNet, endpoint de relevo https://pokt-beta.trackmysupplement.com. Cumple las 9 reglas de aceptación del portal Pocket, con un relevo de pago liquidado en cadena (registro)
Servidor MCP	https://agents.trackmysupplement.com/mcp, listado en el Registro oficial de MCP y en Smithery. Ver mcp/README.md
Precisión	56 casos trabajados a mano, todos aprobados (EVAL.md)
Versión en ejecución	/v1/version; cada versión está en CHANGELOG.md
Ejecutar un proveedor o puerta de enlace	OPERATORS.md: se publica una imagen multi-arquitectura para cada versión

Fuentes de datos, todas públicas:

• Etiquetas: Base de Datos de Etiquetas de Suplementos Dietéticos del NIH (DSLD), API v9 más un espejo semanal de la descarga completa del NIH (214,782 etiquetas).
• Valores de referencia: DRI de la Junta de Alimentos y Nutrición, publicados en las hojas informativas de la Oficina de Suplementos Dietéticos del NIH.
• Interacciones y hierbas: hojas informativas del NIH ODS y NCCIH; los nombres de medicamentos se normalizan con RxNorm del NIH.
• Retiros y eventos adversos: openFDA.
• Alimentos: USDA SR28 (FoodData Central "SR Legacy"); ingesta típica de EE. UU. de What We Eat in America, NHANES 2017–marzo 2020.

Lo que no es: consejo médico ni diagnóstico. Informa lo que declaran las etiquetas, compara los totales con valores de referencia publicados, y transmite las interacciones y declaraciones de seguridad que publica el NIH. La lista de interacciones no es exhaustiva, y ninguna bandera significa que no se encontró nada que informar, no una señal de todo claro.

Para jueces: pruébelo en un minuto

ID de servicio	dietary-supplement-analysis (Pocket Network Beta TestNet, rpc_type: REST, 500 unidades de cómputo por relevo)
Endpoint de relevo (proveedor con participación)	https://pokt-beta.trackmysupplement.com. Acepta solo relevos Pocket firmados.
Endpoint de demostración (directo, prueba gratuita)	https://agents.trackmysupplement.com. El mismo backend sin la capa de relevo, para que pueda usar curl. Hasta 30 solicitudes por minuto y 100 llamadas al día por cliente (detalles); al superar un límite devuelve 429 con "code":"RATE_LIMITED" y un encabezado Retry-After.

Los agentes que pagan llaman al servicio a través de Pocket Network: con una aplicación con participación para dietary-supplement-analysis en Beta, relevo con pocket-ap como se muestra en A través de Pocket Network. Las rutas y cuerpos de solicitud a continuación son los mismos de cualquier manera; el endpoint de demostración simplemente omite la capa de relevo para que pueda usar curl sin participación.

Cada ejemplo es una llamada, hecha de la manera en que un asistente la haría después de que un usuario describe su rutina en palabras sencillas. jq -r .agent_summary imprime la respuesta que el asistente transmite; una copia recortada de la respuesta en vivo se muestra debajo de cada uno.

1. "Tengo 74 años y tomo Coumadin. Tomo Centrum Silver, aceite de pescado y ginkgo."

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 74, "sex": "female", "detail": "summary", "medications": ["Coumadin"],
  "products": [{"query": "Centrum Silver Women 50+"}, {"query": "Nature Made Fish Oil 1200 mg"}, {"query": "Ginkgo Biloba 120 mg"}]}' | jq -r .agent_summary

Ginkgo (en Nutricost Ginkgo Biloba 120 mg): NCCIH: el ginkgo puede aumentar el riesgo de sangrado en personas que toman anticoagulantes como warfarina. Coumadin con vitamina K en este conjunto: la vitamina K contrarresta la warfarina; el NIH describe una interacción grave y potencialmente peligrosa. Coumadin con vitamina E en este conjunto: … Coumadin con EPA/DHA en este conjunto: el aceite de pescado en dosis altas puede prolongar el tiempo de coagulación y elevar el INR … 1 hallazgo de interacción más en interactions.findings.

El nombre de marca se reconoce como warfarina, tres productos se encuentran por nombre en la base de datos de etiquetas del NIH, y cada advertencia cita su hoja informativa del NIH o NCCIH.

2. "Estoy embarazada. Tomo un prenatal, vitamina A 25,000 UI para mi piel, y ashwagandha para el estrés."

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 29, "sex": "female", "life_stage": "pregnancy", "detail": "summary",
  "products": [{"query": "Nature Made Prenatal Multi + DHA"}, {"query": "vitamin A 25000 IU"}, {"query": "ashwagandha root extract"}]}' | jq -r .agent_summary

Vitamina A: 7500 mcg al día frente a un UL de 3000 mcg (250%) … El UL protege contra el daño hepático y defectos de nacimiento cuando se toma durante el embarazo (solo vitamina A preformada). Dejar fuera … Vitamina A 25000 UI llevaría la vitamina A a 0 mcg. Ashwagandha: … NCCIH: evite la ashwagandha durante el embarazo y la lactancia.

3. "Tengo 62 años: Centrum Silver, aceite de pescado, magnesio y zinc. ¿Debería agregar vitamina D 5000?" Con "diet": "typical", los alimentos también se cuentan.

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 62, "sex": "female", "diet": "typical",
  "products": [{"query": "Centrum Silver Women 50+"}, {"query": "Nature Made Ultra Fish Oil 1400"},
               {"query": "KAL Magnesium Glycinate 400"}, {"query": "Thompson Zinc 50 mg", "servings_per_day": 1}],
  "candidates": [{"query": "vitamin d3 5000 iu"}]}' | jq -r .agent_summary

Zinc: 65 mg al día frente a un UL de 40 mg (163%), principalmente de Thompson Zinc 50 mg. El UL protege contra el estado reducido de cobre … Magnesio: 500 mg al día frente a un UL de 350 mg (143%) … Dejar fuera Thompson Zinc 50 mg llevaría el zinc a 15 mg (37.5% del UL). … Agregar … Vitamina D3 5000 UI pondría la vitamina D (150% del UL) por encima del límite superior.

La respuesta da el único cambio que lo soluciona, y el qué pasaría si responde la pregunta que el usuario realmente hizo.

4. En español: "Tomo Centrum Silver y Caltrate; tomo warfarina y levotiroxina."

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 68, "sex": "female", "lang": "es", "detail": "summary", "medications": ["warfarina", "levotiroxina"],
  "products": [{"query": "Centrum Silver Women 50+"}, {"query": "Caltrate 600+D3"}]}' | jq -r .agent_summary

Warfarina con vitamina K de este conjunto: La vitamina K contrarresta la warfarina … Levotiroxina con calcio de este conjunto: … No tome la levotiroxina dentro de las 4 horas del carbonato de calcio. Levotiroxina con hierro de este conjunto: …

5. Escanear un frasco: un código de barras encuentra la etiqueta, y el mismo código de barras encuentra retiros de la FDA y reportes de eventos adversos.

curl -s https://agents.trackmysupplement.com/v1/products/lookup -H 'Content-Type: application/json' -d '{"upc":"031604026974"}' | jq -r '.product.brand + " " + .product.name'
curl -s https://agents.trackmysupplement.com/v1/products/fda -H 'Content-Type: application/json' -d '{"upc":"031604026974"}' | jq -r .agent_summary

Para un producto con retiros, pruebe {"query":"Nature Made Vitamin D3 1000 IU"}: la FDA lista 4 retiros coincidentes.

6. Agente a agente: gran parte del uso se espera que provenga de otros agentes que hacen un trabajo más grande, sin que una persona escriba: un agente de farmacia verificando una nueva receta contra los suplementos en archivo, un agente de compras verificando un carrito antes del pago, un agente de visión transmitiendo una etiqueta que leyó de una foto, el chequeo semanal de un agente de entrenamiento, y un agente de revisión de medicamentos que combina este servicio con servicios de interacción medicamentosa. examples/ tiene los cinco como un solo script (bash examples/agent-flows.sh), más un asistente de 50 líneas que carga las herramientas de GET /v1/tools y permite que un modelo las llame (agent_loop.py).

Más llamadas: POST /v1/nutrients/reference (RDA y UL para un nutriente, sin conexión), POST /v1/products/search (encontrar etiquetas), POST /v1/interactions/check (medicamentos sin un conjunto), y GET /v1/tools, GET /v1/guide y GET /openapi.json para marcos de agentes. Todos están listados bajo Endpoints.

A través de Pocket Network (relevo de pago)

Necesita una aplicación con participación para dietary-supplement-analysis en Beta TestNet. Financie una dirección desde el grifo Beta y haga una participación como aplicación con al menos 1,000 POKT. Luego instale pocket-ap y haga relevos con la configuración de cliente de este repositorio:

export POCKET_APP_PRIVATE_KEY=<your app key, 64 hex>   # pocketd keys export <name> --unarmored-hex --unsafe
pocket-ap call --config deploy/beta-stake/pocket-ap.yaml \
  --service dietary-supplement-analysis --rpc-type rest \
  -X POST --path /v1/stack/analyze \
  -d '{"age":34,"sex":"female","products":[{"name":"Custom magnesium","ingredients":[{"name":"magnesium","amount":250,"unit":"mg"}]}]}' -v

Registro en cadena (Beta TestNet)

Paso	Hash de transacción	Bloque
Servicio registrado, con la tarjeta de card/card.json	BC01B11F…7DD5	722359
Proveedor con participación, 60,000 POKT	9CBCBAAF…51FA	722747
Aplicación de prueba con participación, 1,100 POKT	6734D5F4…05EE	722744
Reclamo por el primer relevo de pago (liquidado en el bloque 722813)	F3D81B3F…88EB	722793
Reclamo por un relevo del ejemplo A de los jueces en v0.12.6, enviado con pocket-ap desde la Mac del propietario el 2026-10-11 (liquidado; 500 unidades de cómputo debitadas de la participación de la aplicación)	A9A5B384…3DA5	724433

Los detalles y la configuración del servidor están en deploy/PHASE4_READINESS.md.

Por qué es importante para Pocket Network

• Una pregunta que millones de personas tienen. El 60.2% de los adultos de EE. UU. tomó un suplemento dietético en los últimos 30 días, el 38.7% tomó dos o más, y el 75.9% de los adultos de 60 años o más tomó al menos uno (CDC NCHS, 2021–2023). Los asistentes de salud, farmacia, compras y fitness reciben preguntas sobre si una rutina está bien, y una buena respuesta necesita las cantidades exactas en cada etiqueta y los límites del NIH para esa persona, que un modelo solo no tiene.
• Llamadas repetidas, muchas de otros agentes. Cada llamada es un relevo (500 unidades de cómputo). Los agentes de farmacia, compras, entrenamiento y revisión de medicamentos lo llaman en cada nueva receta, carrito, foto o chequeo semanal, sin una persona en el ciclo (ejemplos).
• Llena un vacío junto a los propios servicios de salud de Pocket. El catálogo de Pocket tiene servicios de medicamentos (fda, med-safety, clinical-trials) pero nada para suplementos, que la mayoría de esos usuarios también toman. Un agente que ya llama a esos servicios para recetas puede llamar a este para todo lo demás en el botiquín.
• Una prueba gratuita que lleva a relevos de pago. El servidor MCP está listado en el Registro oficial de MCP, en Smithery y en mcpservers.org. Su prueba gratuita (25 verificaciones al día por conexión) es suficiente para que una persona lo pruebe, y cada mensaje de límite apunta a los agentes con volumen real a la ruta de Pocket, que nunca se mide.
• Listo para más proveedores. Se publica una imagen multi-arquitectura para cada versión, OPERATORS.md configura un proveedor en unos 5 minutos, y las respuestas nunca usan 5xx, para que las puertas de enlace no confundan una entrada incorrecta con un proveedor defectuoso.
• Verificado. 56 casos trabajados a mano pasan en cada versión (EVAL.md), y el servicio en vivo se prueba cada 30 minutos contra el endpoint público y la auditoría del portal Pocket.

Endpoints

Todas las entradas provienen del cuerpo de solicitud JSON. Todas las respuestas son objetos JSON, incluidos los errores.

Método	Ruta	Propósito
GET/HEAD	/	Identidad del servicio
GET	/v1/version	{"service":"dietary-supplement-analysis","version":"0.12.7"}
GET	/v1/health	{"status":"ok"}
GET	/openapi.json	Especificación OpenAPI 3.1 (también en openapi/openapi.json)
POST	/mcp	Servidor MCP remoto (HTTP Streamable, sin estado): las mismas herramientas para clientes MCP
GET	/v1/provenance	Versión del código, commit de git y la edición de cada fuente de datos
GET	/v1/tools	Definiciones de herramientas (name, description, JSON Schema input_schema) para llamadas de funciones
GET	/v1/guide	Guía de uso para agentes, como markdown dentro de JSON (mismo texto que llms.txt)
POST	/v1/stack/analyze	Una llamada: totales por nutriente en 1–15 productos (nombres, códigos de barras, IDs o personalizados), banderas, correcciones, candidatos de qué pasaría si
POST	/v1/interactions/check	Interacciones de nutrientes listadas por el NIH para medicamentos o condiciones, sin necesidad de conjunto: {"medications":["Synthroid"],"nutrients":["calcium"]}
POST	/v1/products/search	Encontrar productos en DSLD: {"query":"vitamin d3 5000","brand":"NOW","limit":5}; versiones de etiquetas colapsadas
POST	/v1/products/lookup	Etiqueta para un código de barras: {"upc":"031604026974"}
POST	/v1/products/fda	Retiros de la FDA y reportes de eventos adversos (openFDA) para un producto: {"query":"Nature Made D3 1000 IU"}, {"upc":...}, {"dsld_id":...} o {"brand":...,"name":...}
POST	/v1/products/get	Etiquetas normalizadas: {"dsld_id":12345} o {"dsld_ids":[...]} (máx. 10)
POST	/v1/nutrients/reference	RDA/EAR/AI/UL y base del UL para un nutriente: {"nutrient":"vitamin d","age":34,"sex":"female"} (sin conexión)
POST	/v1/tool	Despachador estilo MCP: {"tool":"stack_analyze","arguments":{...}}

POST /v1/stack/analyze

{
  "age": 34,
  "sex": "female",
  "products": [
    { "query": "Centrum Silver Women 50+" },
    { "upc": "031604026974", "servings_per_day": 1 },
    { "dsld_id": 67890 },
    { "name": "Homemade magnesium", "ingredients": [ { "name": "magnesium glycinate", "amount": 200, "unit": "mg", "nutrient_basis": "elemental" } ] }
  ],
  "medications": [ "warfarin", "Synthroid 50 mcg" ],
  "conditions": [ "smoker" ],
  "candidates": [ { "query": "vitamin d3 5000 iu" } ]
}

• Productos (1–15) pueden ser un nombre de producto (query, opcionalmente con brand), un código de barras (upc), un ID de DSLD, o un producto personalizado con ingredientes explícitos. Los ingredientes personalizados pueden incluir un form (por ejemplo "folic acid" o "d-alpha tocopherol") para que se puedan aplicar conversiones de IU y DFE.
• Nombres y códigos de barras se resuelven en el servidor. Un nombre se compara con los resultados de búsqueda de DSLD según la proporción de sus palabras encontradas en el nombre de la marca y del producto; las versiones de etiqueta del mismo producto se colapsan y se usa la más reciente en el mercado. resolutions[] registra cada coincidencia con confidence (high: cada palabra coincidió con un producto; medium: cada palabra coincidió pero otros productos también, o la mayoría de las palabras coincidieron; low: menos del 60%) y hasta tres alternativas. Un producto que no se puede identificar se reporta (PRODUCT_NOT_RESOLVED) y se omite; la llamada falla con 404 solo cuando no se pudo identificar nada.
• diet: "typical" añade la ingesta diaria promedio de alimentos y bebidas en EE. UU. para la edad y sexo (What We Eat in America, NHANES 2017–marzo 2020) y repite las comparaciones en with_typical_diet. Los alimentos cuentan para un UL solo donde el UL los cubre: todo para UL de ingesta total, ácido fólico de alimentos para folato, retinol para vitamina A, vitamina E añadida para vitamina E, nada para magnesio. No se aplica en menores de 2 años ni en embarazo y lactancia.
• medications (hasta 30, nombres genéricos o de marca tal como los da el usuario) se comparan con 46 clases de medicamentos y se verifican contra las 55 interacciones medicamentosas listadas en las hojas informativas de la Oficina de Suplementos Dietéticos de los NIH (data/interactions.json). Los nombres que la lista no reconoce se normalizan a su ingrediente con NIH RxNorm (RxNav) cuando el servicio puede alcanzarlo; la coincidencia es por palabra completa, nunca difusa. interactions.findings[] da el tipo de cada interacción (supplement_changes_drug, drug_lowers_nutrient, drug_raises_nutrient, additive_risk, two_way), el consejo de tiempo de los NIH cuando lo da, la hoja informativa, y in_stack con los productos involucrados; los hallazgos dentro del stack aparecen primero y lideran agent_summary. La lista no es exhaustiva (INTERACTIONS_PARTIAL), y los nombres de medicamentos nunca se registran.
• Botánicos. Hierbas y otros ingredientes no nutritivos con señales de seguridad de los NIH (16 hasta ahora: ashwagandha, kava, hierba de San Juan, ginkgo, extracto de té verde, cúrcuma/curcumina, black cohosh, garcinia cambogia, arroz de levadura roja, sello de oro, berberina, yohimbe, efedra, valeriana, equinácea, creatina) se reportan en botanicals[] con la declaración de NCCIH u ODS, la declaración de embarazo, y verificaciones de dosis donde los NIH citan dosis (creatina por encima de 5 g y 25 g al día, EGCG a 843 mg al día, valeriana por encima de 600 mg al día). Se comparan con el grupo de ingredientes de DSLD o el nombre exacto después de eliminar palabras de parte de planta y preparación ("Extracto de raíz de ashwagandha" es ashwagandha), nunca por subcadena (data/botanicals.json). Con medications, los pares botánico-medicamento que los NIH nombran (hierba de San Juan con anticonceptivos, warfarina o ISRS; ginkgo con anticoagulantes; kava y valeriana con sedantes; arroz de levadura roja con estatinas; sello de oro con metformina) se convierten en hallazgos de interacción.
• conditions: smoker (actual o anterior, o exposición a asbesto: beta-caroteno desde 20 mg al día, contando vitamina A declarada como beta-caroteno), kidney_disease (potasio, magnesio, fósforo), hemochromatosis (hierro; vitamina C desde 500 mg), lab_test_soon (biotina desde 1 mg sesga pruebas de tiroides, troponina y otras), cancer_treatment (vitamina C y E en dosis altas).
• foods (hasta 30) lista lo que la persona come en un día: {"query": "spinach cooked", "amount": 1, "unit": "cup"} o {"query": "whole milk", "grams": 488} o {"ndb_number": "11458", "grams": 180}. Los alimentos se comparan sin conexión contra los 8,789 alimentos de USDA SR28 (FoodData Central's "SR Legacy"), usando palabras completas y las porciones domésticas del USDA, y se añaden a los totales de suplementos en nutrient_totals[].with_foods. Los nutrientes que solo los alimentos aportan se verifican en foods.totals. Los alimentos cuentan para un UL solo donde el UL cubre alimentos, como para diet. Los nutrientes que el USDA no analizó para un alimento se listan, no se asumen como cero; tres valores de manganeso de SR28 que están fuera de rango por órdenes de magnitud se excluyen y se reportan. Usa foods o diet: "typical", no ambos.
• timing lista las declaraciones de tiempo de los NIH que aplican al stack, cada una nombrando sus productos y hoja informativa: calcio en dosis de 500 mg o menos, carbonato de calcio con una comida, suplementos de calcio y hierro separados, 25 mg+ de hierro aparte del zinc, hierro con alimentos en dosis altas, vitamina D con algo de grasa, extracto de té verde con alimentos, y espaciamiento de medicamentos para interacciones dentro del stack. La primera también aparece en agent_summary.
• lang: "es" escribe agent_summary en español, con el texto en inglés conservado en agent_summary_en. Cada frase de los NIH que puede aparecer en un resumen tiene una traducción al español revisada (data/i18n-es.json); otros campos permanecen en inglés. Los nombres de medicamentos se pueden dar en español (warfarina, levotiroxina, omeprazol) o como marcas españolas y latinoamericanas (Sintrom, Eutirox), con o sin acentos.
• detail: "summary" devuelve solo lo que un agente necesita para responder (agent_summary, nutrientes flagged, suggestions, resolutions, veredictos candidatos, data_gap_codes, provenance), típicamente 1–3 KB en lugar de 20–40 KB.
• Candidatos (hasta 5) son productos que el usuario está considerando. Cada uno se evalúa como una adición al stack en candidate_results[] y no se cuenta en los totales.
• servings_per_day por defecto es el máximo de porciones diarias de la etiqueta, o 1 si la etiqueta no lo dice. Cada valor por defecto se lista en assumptions.
• age y sex son opcionales. Sin ellos obtienes totales y superposiciones, pero sin comparaciones de referencia.
• life_stage ("pregnancy" o "lactation", femenino, edades 14–50) cambia a los valores de referencia de embarazo o lactancia; "pregnant": true y "breastfeeding": true también funcionan. Para bebés, da la edad como fracción de año (0.25 es 3 meses): aplican los valores de 0–6 y 7–12 meses.

La respuesta contiene, en este orden: profile, summary, agent_summary, resolutions (cuando se dieron nombres o códigos de barras), assumptions, suggestions, candidate_results (cuando se dieron candidatos), botanicals (cuando el stack tiene alguno con señales de NIH), interactions (cuando se dieron medicamentos o condiciones), nutrient_totals, overlaps, unrecognized_ingredients, data_gaps, products, sources y disclaimer.

• agent_summary son de dos a cinco oraciones simples, generadas determinísticamente a partir de los números a continuación, que un agente puede transmitir tal cual.
• suggestions lista, para cada nutriente por encima del UL, hasta tres cambios de un solo producto (reduce_servings o remove_product) con la cantidad resultante, si eso solo lleva al nutriente al UL o por debajo (resolves), qué otros nutrientes por encima del UL también corrige, y qué otros nutrientes bajaría una eliminación. Son aritméticos, no consejos.
• candidate_results da a cada candidato un verdict (adds_above_ul, increases_above_ul, adds_near_ul o no_new_flags), las nuevas banderas y los totales antes y después.

Cada total de nutriente incluye:

Campo	Significado
daily_total	Suma entre productos, en la unidad canónica del nutriente (mcg RAE, mcg DFE, mg, mcg)
complete	false cuando algunas filas de la etiqueta no pudieron contarse (ver data_gaps); el total es entonces un límite inferior
reference	RDA, EAR, AI y UL para el perfil, con ul_scope, ul_note y ul_basis (contra qué protege el UL, por ejemplo "Estado reducido de cobre" para zinc)
amount_toward_ul	La parte a la que aplica el UL: solo ácido fólico para folato, solo vitamina A preformada para vitamina A
percent_of_ul, percent_of_rda, percent_of_ai	Porcentaje de cada valor de referencia. percent_of_ul se omite cuando la porción del UL solo se conoce parcialmente y el UL aún no se excede
coverage	Porcentaje de la RDA (o AI) que estos suplementos solos aportan. Informativo: la dieta normalmente aporta gran parte, así que una cobertura baja no es una deficiencia
flags	above_ul (sobre el UL) o near_ul (90–100% del UL). Sin bandera significa que no hay nada que reportar, no un juicio sobre el stack
severity	high (dos veces el UL o más), moderate (por encima del UL), low (cerca del UL), o null
contributions	Cantidad de la etiqueta de cada producto, cantidad convertida, porciones por día y cantidad diaria
with_typical_diet	Con "diet": "typical": food, estimated_total, amount_toward_ul, percent_of_ul, coverage y flags con la ingesta promedio de alimentos de EE. UU. añadida

Errores

{ "error": { "code": "INVALID_INPUT", "message": "products: ...", "retryable": false, "field": "products" } }

Código	Estado	Cuándo
INVALID_INPUT	400	Entrada malformada o fuera de rango
NOT_FOUND	404	ID de DSLD, nutriente o ruta desconocidos
UNSUPPORTED	422	Embarazo o lactancia fuera de edades 14–50
UPSTREAM_UNAVAILABLE	424	DSLD no se puede alcanzar y nada está en caché (retryable: true)
INTERNAL_ERROR	422	Fallo inesperado. Se devuelve como 4xx porque las puertas de enlace Pocket tratan 5xx como una falla del proveedor

Códigos de brechas de datos

Código	Significado
BLEND_UNQUANTIFIED	Una mezcla propietaria lista ingredientes sin sus propias cantidades; el peso de la mezcla no se divide entre ellos
QUANTITY_MISSING	Una fila de nutriente reconocida no tiene cantidad
UNIT_NOT_CONVERTIBLE	La unidad no se puede convertir sin ambigüedad, por ejemplo vitamina A en IU con una forma desconocida
COMPOUND_WEIGHT	La cantidad puede ser peso del compuesto, no mineral elemental
AMBIGUOUS_BASIS	Un ingrediente personalizado nombrado por un compuesto carece de nutrient_basis
UL_PARTIAL	El UL aplica solo a una forma (ácido fólico, vitamina A preformada) y algunas formas no están especificadas
PROFILE_MISSING	Sin edad y sexo, así que no hay comparación de referencia
PRODUCT_NOT_RESOLVED	Un nombre de producto o código de barras no pudo coincidir con una etiqueta de DSLD; no se cuenta
DATA_SUSPECT	El registro de etiqueta de los NIH parece inconsistente; la cantidad aún se cuenta. check dice qué prueba falló: duplicate_row (el mismo ingrediente dos veces bajo un encabezado, como EPA ingresado como DHA), nested_exceeds_parent (las filas suman más que su total declarado), percent_dv_mismatch (el %DV impreso contradice la cantidad bajo tanto el Valor Diario actual como el anterior a 2016), implausible_amount (más de 50 veces el UL adulto más alto, típicamente mg escrito por mcg)
INTERACTIONS_NOT_ASSESSED	No se dieron medications, así que las interacciones medicamentosas no se verificaron. Las interacciones suplemento-suplemento nunca se evalúan
INTERACTIONS_PARTIAL	Los medicamentos se verificaron, pero solo contra las interacciones nombradas en las hojas informativas de NIH ODS; la lista no es exhaustiva
FOOD_NOT_RESOLVED	Un alimento en foods no coincidió con ningún alimento de USDA SR28 y no se cuenta
FOOD_PORTION_UNKNOWN	USDA no lista una porción para la unidad dada para ese alimento; las porciones listadas están en foods.items[].portions (da gramos en su lugar)
FDA_UNAVAILABLE	Solo /v1/products/fda: openFDA no se pudo alcanzar para retiros o eventos adversos; el resto de la respuesta se mantiene
MEDICATION_NOT_RECOGNIZED	Un nombre de medicamento no coincidió con ninguna clase en la lista de interacciones de las hojas informativas de NIH (directamente o mediante RxNorm), así que no se verificó nada para él

Cómo se producen los números

La precisión se verifica contra 56 casos trabajados a mano; ver EVAL.md.

• Lectura de etiquetas DSLD:
  • DSLD a menudo almacena la vitamina A como mcg o mg simples. Se lee como mcg RAE solo cuando el %VD de la etiqueta coincide con el Valor Diario de 900 mcg RAE.
  • Cuando DSLD omite una unidad (por ejemplo, "6 NP"), se infiere solo si el %VD de la etiqueta coincide con el Valor Diario de la FDA; de lo contrario, es una brecha.
  • Las filas anidadas bajo un nutriente lo desglosan por forma (folato 800 mcg DFE = ácido fólico 480 mcg). Proporcionan la porción exacta de UL y nunca se cuentan dos veces.
  • Las declaraciones de forma compartida ("40% como betacaroteno") dividen las conversiones de IU exactamente cuando cubren el 100%. Cuando cubren menos, el resto se trata como una forma desconocida.
  • Los gamma y delta tocoferoles y tocotrienoles no se cuentan como vitamina E.
• La coincidencia de un ingrediente con un nutriente intenta, en orden: el ingredientGroup de DSLD, el código UNII, un sinónimo exacto, y luego un nombre de forma exacto que pertenezca a exactamente un nutriente. No hay coincidencia por subcadena o difusa, por lo que "Vitamina B" nunca coincide con "Vitamina B12". Cualquier otra cosa va a unrecognized_ingredients.
• La conversión de unidades ocurre solo cuando el resultado no es ambiguo:
  • Vitamina D: 1 mcg = 40 UI.
  • Vitamina E: forma natural 0,67 mg por UI, forma sintética 0,45 mg por UI. Una forma desconocida se convierte en una brecha de datos.
  • Vitamina A: la UI se convierte solo para retinol (0,3 mcg RAE por UI) o betacaroteno suplementario (0,3 mcg RAE por UI).
  • Folato: mcg simples de ácido fólico × 1,7 = mcg DFE.
  • El porcentaje de VD se muestra exactamente como en la etiqueta y nunca se usa en los totales.
• El alcance del UL se almacena para cada nutriente y se explica en la respuesta:
  • Magnesio: solo suplementos y medicamentos.
  • Folato: solo ácido fólico.
  • Vitamina A: solo preformada.
  • Niacina y vitamina E: ingesta suplementaria.
  • Todo lo demás es un UL de ingesta total. Un total de suplemento por debajo de uno de esos no muestra que la ingesta total esté por debajo, y assumptions lo dice.
• Los datos de referencia viven en data/source/manual.json. scripts/build-nutrients.ts construye data/nutrients.json a partir de ellos, y desde la exportación de global_compounds de SuppleTracker si está presente. La compilación valida unidades, fuentes, rangos de edad y colisiones de sinónimos. Cubre 26 vitaminas y minerales con DRI, más EPA, DHA, melatonina, CoQ10 y betacaroteno, que se reconocen pero no tienen valores de referencia.

Ejecución local

npm ci
npm run dev                   # http://localhost:8080 (live DSLD)
DSLD_FIXTURES_DIR=test/fixtures/dsld npm run dev   # offline, synthetic fixture labels 900001-900005
npm run check                 # data + OpenAPI freshness, lint, typecheck, tests
docker compose up --build     # container on 127.0.0.1:8080

Variable de entorno	Predeterminado	Propósito
PORT / HOST	8080 / 0.0.0.0	Dirección de escucha
DSLD_API_KEY	ninguno	Una clave de api.data.gov, enviada a DSLD como X-Api-Key (aumenta el límite de NIH de 1,000 a 10,000 solicitudes por hora)
OPENFDA_API_KEY	ninguno	La misma clave de api.data.gov, para openFDA
OPENFDA / RXNORM	activado	off detiene las llamadas a openFDA o RxNorm (la coincidencia de medicamentos usa entonces solo los nombres en data/interactions.json)
FREE_TIER_HOSTS	ninguno	Nombres de host que obtienen las cuotas de prueba gratuita (la demo usa agents.trackmysupplement.com); las solicitudes en otros hosts, como los relays de Pocket, nunca se miden. FREE_TIER_PER_SESSION, FREE_TIER_PER_IP, FREE_TIER_PER_IP_MCP y FREE_TIER_GLOBAL cambian las cuotas
DSLD_BASE_URL	https://api.ods.od.nih.gov/dsld/v9	Base de la API de DSLD
DSLD_PREWARM_IDS	ninguno	IDs de etiquetas separados por comas para almacenar en caché al inicio
DSLD_STORE_PATH	/data/dsld.sqlite en el contenedor, desactivado en otros casos	Almacén de etiquetas persistente (SQLite). Cada etiqueta obtenida se conserva; cuando NIH no está disponible, las etiquetas, códigos de barras y búsquedas se responden desde él. Vacío lo desactiva
DSLD_WARM	1	Con el almacén activado, un trabajo en segundo plano obtiene productos populares a aproximadamente una solicitud por segundo (consultas en data/warm-queries.json). 0 lo desactiva
DSLD_FIXTURES_DIR	ninguno	Servir DSLD desde archivos label-<id>.json locales (solo desarrollo; test/fixtures/dsld/real contiene 12 etiquetas reales)
UPSTREAM_BUDGET_MS	8000	Tiempo total que una solicitud puede esperar en DSLD antes de responder 424
LOG_LEVEL	info	Los registros registran método, ruta, estado y duración solamente, nunca cuerpos de solicitud

Límites

• Hasta 15 productos y 5 candidatos por llamada de análisis, 10 IDs por llamada de obtención y 10 resultados de búsqueda.
• La descarga completa de DSLD de NIH (214,782 etiquetas) se refleja en el almacén de etiquetas y se actualiza semanalmente cuando NIH publica una nueva. Las etiquetas y códigos de barras en el espejo se responden sin llamar a NIH. Las búsquedas de nombres usan la API en vivo (con una clave de api.data.gov) y recurren al espejo, cambiando automáticamente a él durante 10 minutos cada vez que NIH limita la tasa. GET /v1/provenance muestra la versión reflejada.
• Las llamadas a DSLD se ejecutan como máximo 4 a la vez, con un plazo de 6 s cada una y un presupuesto de 8 s por solicitud. Las etiquetas se almacenan en caché en memoria durante 7 días y las búsquedas durante 24 horas, y las etiquetas también se conservan en el almacén de etiquetas persistente (actualizado después de 30 días). Si DSLD está caído, las copias obsoletas y el almacén de etiquetas responden en su lugar; los resultados de búsqueda del almacén dicen "search_source": "local". Medido contra DSLD en vivo: un análisis en frío de 15 productos toma 1,5 s y uno en caliente 17 ms.
• El texto que las puertas de enlace de Pocket tratan como señal de error ("timeout", "block not found" y otros) se escapa con \u en las respuestas. Se decodifica a la misma cadena.
• Edades desde el nacimiento hasta 120, más embarazo y lactancia (14–50). La cafeína se verifica contra las pautas de la FDA (400 mg al día para adultos sanos, menos de 200 mg en el embarazo) y el sodio contra la Ingesta de Reducción de Riesgo de Enfermedad Crónica de 2019 (2,300 mg), ninguna de las cuales es un UL de DRI; la respuesta lo dice en ul_note.
• El endpoint público de demostración es una prueba gratuita. Permite 30 solicitudes por minuto por cliente, más cuotas diarias que se restablecen a las 00:00 UTC:
  • 25 llamadas de herramientas por conexión MCP (cada conexión obtiene su propio Mcp-Session-Id), como máximo 20 por minuto;
  • 100 llamadas REST por IP;
  • 1,000 llamadas MCP por IP (los clientes alojados como claude.ai comparten direcciones de salida);
  • 5,000 llamadas gratuitas en total. El descubrimiento (rutas GET, initialize, tools/list) es gratuito. Los resultados nunca se degradan. Las respuestas REST llevan los encabezados X-Free-Tier-Remaining, X-Free-Tier-Limit y X-Free-Tier-Reset, y los resultados MCP llevan lo mismo en _meta.free_tier. Pasada una cuota, REST responde 429 RATE_LIMITED, y MCP devuelve un resultado de herramienta legible que dice cuándo se restablece la cuota y cómo cambiar a la ruta de pago de Pocket.
  • Los contadores son hashes con sal, conservados durante dos días.
  • Los relays a través de Pocket Network nunca se miden.

Descargo de responsabilidad, términos y licencias

Solo información, no consejo médico. El servicio informa lo que declaran las etiquetas de suplementos y cómo los totales se comparan con valores de referencia, interacciones y declaraciones de seguridad publicadas por NIH y FDA. No es un diagnóstico ni una recomendación de tratamiento, no sustituye a un médico o farmacéutico, y no está destinado a diagnosticar, tratar, curar o prevenir ninguna enfermedad. Las etiquetas y los datos públicos pueden ser incorrectos o estar desactualizados, la lista de interacciones cubre solo lo que NIH nombra, y ninguna bandera no es una señal de todo claro. Consulte con un profesional de la salud antes de comenzar, detener o cambiar un suplemento o medicamento; en una emergencia, llame al 911 o al Centro de Control de Envenenamientos (1-800-222-1222) en los EE. UU. Cada respuesta lleva esto en su campo disclaimer y en la última oración de agent_summary, y las aplicaciones y agentes que retransmiten resultados aceptan transmitirlo.

El uso del servicio alojado se rige por los términos de uso. NIH, FDA y USDA no respaldan este servicio, y los nombres de marcas se usan solo para identificar productos.

El código está bajo la Licencia MIT. Los datos que sirve de DSLD, ODS, NCCIH, RxNorm, openFDA y USDA son trabajo del Gobierno de los EE. UU. en el dominio público; los archivos curados de interacciones y hierbas en data/ citan sus fuentes de NIH.