Dietary Supplement Analysis (NIH data)

Verifica uma rotina de suplementos contra dados do NIH: encontra o rótulo de cada produto (por nome, código de barras ou ID do NIH), totaliza cada vitamina e mineral por dia, e sinaliza quantidades acima dos limites superiores do NIH, interações medicamentosas das fichas informativas do NIH, ervas com sinais de segurança do NIH e recalls da FDA, com um resumo em linguagem simples (inglês ou espanhol) e uma fonte para cada número. Teste gratuito, sem necessidade de chave.

GitHub

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Análise de Rótulos de Suplementos Alimentares e Ingestão de Nutrientes

Assistentes de IA chamam este serviço quando alguém pergunta "minha rotina de suplementos está OK?". Forneça os produtos da forma como a pessoa os nomeia (nome do produto, código de barras ou ID de rótulo do NIH), com idade e sexo, e opcionalmente seus medicamentos, condições e o que ela come. O serviço encontra cada rótulo no Banco de Dados de Rótulos de Suplementos Alimentares do NIH, soma todas as vitaminas e minerais por dia em todos eles, e compara os totais com as ingestões de referência e limites superiores do NIH. Também relata as interações medicamentosas citadas nas fichas técnicas do NIH, ervas com sinais de segurança do NIH, e recalls da FDA e relatos de eventos adversos. Toda resposta começa com um resumo em linguagem simples que um assistente pode transmitir (inglês ou espanhol), e todo número remonta ao seu rótulo ou fonte do NIH.

Ele roda na Pocket Network Beta TestNet como o serviço pago dietary-supplement-analysis, e como um servidor MCP remoto com teste gratuito.


Experimente	Para avaliadores: experimente em um minuto
Pocket Network	ID do serviço `dietary-supplement-analysis` na Beta TestNet, endpoint de relay `https://pokt-beta.trackmysupplement.com`. Passa em todas as 9 regras de aceitação do portal Pocket, com um relay pago liquidado on-chain (registro)
Servidor MCP	`https://agents.trackmysupplement.com/mcp`, listado no Registro MCP oficial e no Smithery. Veja mcp/README.md
Precisão	56 casos trabalhados manualmente, todos aprovados (EVAL.md)
Versão em execução	`/v1/version`; cada versão está em CHANGELOG.md
Execute um fornecedor ou gateway	OPERATORS.md: uma imagem multi-arquitetura é publicada para cada versão

Fontes de dados, todas públicas:

Rótulos: Banco de Dados de Rótulos de Suplementos Alimentares do NIH (DSLD), API v9 mais um espelho semanal do download completo do NIH (214.782 rótulos).
Valores de referência: DRIs do Food and Nutrition Board, conforme publicados nas fichas técnicas do NIH Office of Dietary Supplements.
Interações e ervas: fichas técnicas do NIH ODS e NCCIH; nomes de medicamentos são normalizados com o NIH RxNorm.
Recalls e eventos adversos: openFDA.
Alimentos: USDA SR28 (FoodData Central "SR Legacy"); ingestão típica dos EUA de What We Eat in America, NHANES 2017–março de 2020.

O que não é: aconselhamento médico ou diagnóstico. Relata o que os rótulos declaram, compara os totais com valores de referência publicados e transmite as interações e declarações de segurança que o NIH publica. A lista de interações não é exaustiva, e nenhum alerta significa que nada foi encontrado para relatar, não um sinal de tudo limpo.

Para avaliadores: experimente em um minuto


ID do serviço	`dietary-supplement-analysis` (Pocket Network Beta TestNet, `rpc_type: REST`, 500 unidades de computação por relay)
Endpoint de relay (fornecedor com stake)	`https://pokt-beta.trackmysupplement.com`. Aceita apenas relays Pocket assinados.
Endpoint de demonstração (direto, teste gratuito)	`https://agents.trackmysupplement.com`. O mesmo backend sem a camada de relay, para que você possa usar `curl`. Até 30 solicitações por minuto e 100 chamadas por dia por cliente (detalhes); acima do limite, retorna `429` com `"code":"RATE_LIMITED"` e um cabeçalho `Retry-After`.

Agentes pagantes chamam o serviço pela Pocket Network: com um aplicativo com stake para dietary-supplement-analysis na Beta, faça relay com pocket-ap conforme mostrado em Através da Pocket Network. Os caminhos e corpos de solicitação abaixo são os mesmos de qualquer forma; o endpoint de demonstração apenas pula a camada de relay para que você possa usar curl sem fazer stake.

Cada exemplo é uma chamada, feita da forma que um assistente faria depois que um usuário descreve sua rotina em palavras simples. jq -r .agent_summary imprime a resposta que o assistente transmite; uma cópia reduzida da resposta ao vivo é mostrada abaixo de cada uma.

1. "Tenho 74 anos e tomo Coumadin. Tomo Centrum Silver, óleo de peixe e 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 (em Nutricost Ginkgo Biloba 120 mg): NCCIH: ginkgo pode aumentar o risco de sangramento em pessoas que tomam anticoagulantes como varfarina. Coumadin com Vitamina K neste conjunto: A vitamina K neutraliza a varfarina; o NIH descreve uma interação séria e potencialmente perigosa. Coumadin com Vitamina E neste conjunto: … Coumadin com EPA/DHA neste conjunto: Óleo de peixe em alta dose pode prolongar o tempo de coagulação e aumentar o INR … Mais 1 achado de interação em interações.descobertas.

O nome da marca é reconhecido como varfarina, três produtos são encontrados pelo nome no banco de dados de rótulos do NIH, e cada aviso cita sua ficha técnica do NIH ou NCCIH.

2. "Estou grávida. Tomo um pré-natal, vitamina A 25.000 UI para minha pele e ashwagandha para o estresse."

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: 7.500 mcg por dia vs. um UL de 3.000 mcg (250%) … O UL protege contra danos ao fígado e defeitos congênitos quando tomado na gravidez (somente vitamina A pré-formada). Deixar de fora … Vitamina A 25.000 UI traria a Vitamina A para 0 mcg. Ashwagandha: … NCCIH: evite ashwagandha durante a gravidez e amamentação.

3. "Tenho 62 anos: Centrum Silver, óleo de peixe, magnésio e zinco. Devo adicionar vitamina D 5.000?" Com "diet": "typical", alimentos também são contados.

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

Zinco: 65 mg por dia vs. um UL de 40 mg (163%), principalmente de Thompson Zinc 50 mg. O UL protege contra status reduzido de cobre … Magnésio: 500 mg por dia vs. um UL de 350 mg (143%) … Deixar de fora Thompson Zinc 50 mg traria o zinco para 15 mg (37,5% do UL). … Adicionar … Vitamina D3 5.000 UI colocaria a Vitamina D (150% do UL) acima do limite superior.

A resposta dá a única mudança que resolve o problema, e o "e se" responde à pergunta que o usuário realmente fez.

4. Em espanhol: "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. Escaneie um frasco: um código de barras encontra o rótulo, e o mesmo código de barras encontra recalls da FDA e relatos 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 um produto com recalls, tente {"query":"Nature Made Vitamin D3 1000 IU"}: a FDA lista 4 recalls correspondentes.

6. Agente para agente: grande parte do uso deve vir de outros agentes fazendo um trabalho maior, sem nenhuma pessoa digitando: um agente de farmácia verificando uma nova prescrição contra os suplementos registrados, um agente de compras verificando um carrinho antes do checkout, um agente de visão repassando um rótulo que leu de uma foto, a verificação semanal de um agente de coaching e um agente de revisão de medicamentos combinando este serviço com serviços de interação medicamentosa. examples/ tem todos os cinco como um único script (bash examples/agent-flows.sh), além de um assistente de 50 linhas que carrega as ferramentas de GET /v1/tools e permite que um modelo as chame (agent_loop.py).

Mais chamadas: POST /v1/nutrients/reference (RDA e UL para um nutriente, offline), POST /v1/products/search (encontrar rótulos), POST /v1/interactions/check (medicamentos sem um conjunto) e GET /v1/tools, GET /v1/guide e GET /openapi.json para frameworks de agentes. Todos estão listados em Endpoints.

Através da Pocket Network (relay pago)

Você precisa de um aplicativo com stake para dietary-supplement-analysis na Beta TestNet. Financie um endereço pelo faucet da Beta e faça stake como aplicativo com pelo menos 1.000 POKT. Depois instale pocket-ap e faça relay com a configuração de cliente deste repositório:

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 on-chain (Beta TestNet)

Etapa	Hash da tx	Bloco
Serviço registrado, com o cartão de card/card.json	`BC01B11F…7DD5`	722359
Fornecedor com stake, 60.000 POKT	`9CBCBAAF…51FA`	722747
Aplicativo de teste com stake, 1.100 POKT	`6734D5F4…05EE`	722744
Reivindicação do primeiro relay pago (liquidado no bloco 722813)	`F3D81B3F…88EB`	722793
Reivindicação de um relay do exemplo A dos avaliadores na v0.12.6, enviado com `pocket-ap` do Mac do proprietário em 2026-10-11 (liquidado; 500 unidades de computação debitadas do stake do aplicativo)	`A9A5B384…3DA5`	724433

Detalhes e a configuração do servidor estão em deploy/PHASE4_READINESS.md.

Por que isso importa para a Pocket Network

Uma pergunta que milhões de pessoas têm. 60,2% dos adultos dos EUA tomaram um suplemento alimentar nos últimos 30 dias, 38,7% tomaram dois ou mais, e 75,9% dos adultos com 60 anos ou mais tomaram pelo menos um (CDC NCHS, 2021–2023). Assistentes de saúde, farmácia, supermercado e fitness recebem perguntas sobre se uma rotina está OK, e uma boa resposta precisa das quantidades exatas em cada rótulo e dos limites do NIH para aquela pessoa, que um modelo sozinho não tem.
Chamadas repetidas, muitas de outros agentes. Cada chamada é um relay (500 unidades de computação). Agentes de farmácia, compras, coaching e revisão de medicamentos chamam a cada nova prescrição, carrinho, foto ou verificação semanal, sem nenhuma pessoa no loop (exemplos).
Preenche uma lacuna ao lado dos próprios serviços de saúde da Pocket. O catálogo da Pocket tem serviços de medicamentos (fda, med-safety, clinical-trials), mas nada para suplementos, que a maioria desses usuários também toma. Um agente que já chama esses serviços para prescrições pode chamar este para tudo o mais no armário.
Um teste gratuito que leva a relays pagos. O servidor MCP está listado no Registro MCP oficial, no Smithery e no mcpservers.org. Seu teste gratuito (25 verificações por dia por conexão) é suficiente para uma pessoa experimentar, e toda mensagem de limite aponta agentes com volume real para a rota Pocket, que nunca é medida.
Pronto para mais fornecedores. Uma imagem multi-arquitetura é publicada para cada versão, OPERATORS.md configura um fornecedor em cerca de 5 minutos, e as respostas nunca usam 5xx, então os gateways não confundem uma entrada ruim com um fornecedor com defeito.
Verificado. 56 casos trabalhados manualmente passam em cada versão (EVAL.md), e o serviço ao vivo é testado a cada 30 minutos contra o endpoint público e a auditoria do portal Pocket.

Endpoints

Todas as entradas vêm do corpo da solicitação JSON. Todas as respostas são objetos JSON, incluindo erros.

Método	Caminho	Finalidade
GET/HEAD	`/`	Identidade do serviço
GET	`/v1/version`	`{"service":"dietary-supplement-analysis","version":"0.12.7"}`
GET	`/v1/health`	`{"status":"ok"}`
GET	`/openapi.json`	Especificação OpenAPI 3.1 (também em openapi/openapi.json)
POST	`/mcp`	Servidor MCP remoto (HTTP Streamable, sem estado): as mesmas ferramentas para clientes MCP
GET	`/v1/provenance`	Versão do código, commit do git e a edição de cada fonte de dados
GET	`/v1/tools`	Definições de ferramentas (`name`, `description`, JSON Schema `input_schema`) para chamada de função
GET	`/v1/guide`	Guia de uso para agentes, como markdown dentro de JSON (mesmo texto de llms.txt)
POST	`/v1/stack/analyze`	Uma chamada: totais por nutriente em 1–15 produtos (nomes, códigos de barras, IDs ou personalizados), alertas, correções, candidatos "e se"
POST	`/v1/interactions/check`	Interações de nutrientes listadas pelo NIH para medicamentos ou condições, sem necessidade de conjunto: `{"medications":["Synthroid"],"nutrients":["calcium"]}`
POST	`/v1/products/search`	Encontrar produtos no DSLD: `{"query":"vitamin d3 5000","brand":"NOW","limit":5}`; versões de rótulos recolhidas
POST	`/v1/products/lookup`	Rótulo para um código de barras: `{"upc":"031604026974"}`
POST	`/v1/products/fda`	Recalls da FDA e relatos de eventos adversos (openFDA) para um produto: `{"query":"Nature Made D3 1000 IU"}`, `{"upc":...}`, `{"dsld_id":...}` ou `{"brand":...,"name":...}`
POST	`/v1/products/get`	Rótulos normalizados: `{"dsld_id":12345}` ou `{"dsld_ids":[...]}` (máx. 10)
POST	`/v1/nutrients/reference`	RDA/EAR/AI/UL e base do UL para um nutriente: `{"nutrient":"vitamin d","age":34,"sex":"female"}` (offline)
POST	`/v1/tool`	Despachante 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" } ]
}

Produtos (1–15) podem ser um nome de produto (query, opcionalmente com brand), um código de barras (upc), um ID DSLD ou um produto personalizado com ingredientes explícitos. Ingredientes personalizados podem fornecer um form (por exemplo, "folic acid" ou "d-alpha tocopherol") para que conversões de UI e DFE possam ser aplicadas.
Nomes e códigos de barras são resolvidos no servidor. Um nome é comparado aos resultados da busca DSLD pela proporção de suas palavras encontradas no nome da marca e do produto; versões de rótulo do mesmo produto são agrupadas e a versão mais recente no mercado é usada. resolutions[] registra cada correspondência com confidence (high: cada palavra correspondeu a um produto; medium: cada palavra correspondeu, mas outros produtos também corresponderam, ou a maioria das palavras correspondeu; low: abaixo de 60%) e até três alternativas. Um produto que não pode ser identificado é relatado (PRODUCT_NOT_RESOLVED) e deixado de fora; a chamada falha com 404 somente quando nada pôde ser identificado.
diet: "typical" adiciona a ingestão média diária dos EUA proveniente de alimentos e bebidas para a idade e sexo (What We Eat in America, NHANES 2017–março de 2020) e repete as comparações em with_typical_diet. Alimentos contam para um UL somente onde o UL os cobre: tudo para ULs de ingestão total, ácido fólico dos alimentos para folato, retinol para vitamina A, vitamina E adicionada para vitamina E, nada para magnésio. Não é aplicado abaixo de 2 anos ou na gravidez e lactação.
medications (até 30, nomes genéricos ou de marca conforme fornecidos pelo usuário) são comparados a 46 classes de medicamentos e verificados contra as 55 interações medicamentosas listadas nas fichas técnicas do NIH Office of Dietary Supplements (data/interactions.json). Nomes que a lista não conhece são normalizados para seu ingrediente com o NIH RxNorm (RxNav) quando o serviço consegue alcançá-lo; a correspondência é por palavra inteira, nunca difusa. interactions.findings[] fornece o tipo de cada interação (supplement_changes_drug, drug_lowers_nutrient, drug_raises_nutrient, additive_risk, two_way), a orientação de horário do NIH quando fornecida, a ficha técnica e in_stack com os produtos envolvidos; descobertas no conjunto vêm primeiro e lideram agent_summary. A lista não é exaustiva (INTERACTIONS_PARTIAL), e nomes de medicamentos nunca são registrados.
Botânicos. Ervas e outros ingredientes não nutritivos com sinais de segurança do NIH (16 até agora: ashwagandha, kava, erva-de-são-joão, ginkgo, extrato de chá verde, cúrcuma/curcumina, black cohosh, garcinia cambogia, arroz de levedura vermelha, goldenseal, berberina, yohimbe, efedra, valeriana, equinácea, creatina) são relatados em botanicals[] com a declaração do NCCIH ou ODS, a declaração sobre gravidez e verificações de dose onde o NIH cita doses (creatina acima de 5 g e 25 g por dia, EGCG a 843 mg por dia, valeriana acima de 600 mg por dia). Eles são correspondidos no grupo de ingredientes do DSLD ou no nome exato após remover palavras de parte da planta e preparação ("Extrato de Raiz de Ashwagandha" é ashwagandha), nunca por substring (data/botanicals.json). Com medications, pares botânico-medicamento que o NIH nomeia (erva-de-são-joão com anticoncepcionais, varfarina ou ISRS; ginkgo com anticoagulantes; kava e valeriana com sedativos; arroz de levedura vermelha com estatinas; goldenseal com metformina) tornam-se descobertas de interação.
conditions: smoker (atual ou ex-fumante, ou exposição a amianto: beta-caroteno a partir de 20 mg por dia, contando vitamina A declarada como beta-caroteno), kidney_disease (potássio, magnésio, fósforo), hemochromatosis (ferro; vitamina C a partir de 500 mg), lab_test_soon (biotina a partir de 1 mg distorce tireoide, troponina e outros testes), cancer_treatment (vitamina C e E em altas doses).
foods (até 30) lista o que a pessoa come em um dia: {"query": "spinach cooked", "amount": 1, "unit": "cup"} ou {"query": "whole milk", "grams": 488} ou {"ndb_number": "11458", "grams": 180}. Alimentos são correspondidos offline contra os 8.789 alimentos do USDA SR28 (FoodData Central's "SR Legacy"), usando palavras inteiras e as porções domésticas do USDA, e adicionados aos totais de suplementos em nutrient_totals[].with_foods. Nutrientes fornecidos apenas pelos alimentos são verificados em foods.totals. Alimentos contam para um UL somente onde o UL cobre alimentos, como para diet. Nutrientes que o USDA não analisou para um alimento são listados, não assumidos como zero; três valores de manganês do SR28 que estão fora de ordem de magnitude são excluídos e relatados. Use foods ou diet: "typical", não ambos.
timing lista as declarações de horário do NIH que se aplicam ao conjunto, cada uma nomeando seus produtos e ficha técnica: cálcio em doses de 500 mg ou menos, carbonato de cálcio com uma refeição, suplementos separados de cálcio e ferro, 25 mg+ de ferro separado do zinco, ferro com alimentos em altas doses, vitamina D com alguma gordura, extrato de chá verde com alimentos e espaçamento de medicamentos para interações no conjunto. A primeira também aparece em agent_summary.
lang: "es" escreve agent_summary em espanhol, com o texto em inglês mantido em agent_summary_en. Cada frase do NIH que pode aparecer em um resumo tem uma tradução revisada para o espanhol (data/i18n-es.json); outros campos permanecem em inglês. Nomes de medicamentos podem ser fornecidos em espanhol (warfarina, levotiroxina, omeprazol) ou como marcas espanholas e latino-americanas (Sintrom, Eutirox), com ou sem acentos.
detail: "summary" retorna apenas o que um agente precisa para responder (agent_summary, nutrientes flagged, suggestions, resolutions, vereditos candidatos, data_gap_codes, provenance), tipicamente 1–3 KB em vez de 20–40 KB.
Candidatos (até 5) são produtos que o usuário está considerando. Cada um é avaliado como uma adição ao conjunto em candidate_results[] e não é contado nos totais.
servings_per_day assume como padrão as porções diárias máximas do rótulo, ou 1 se o rótulo não disser. Cada padrão é listado em assumptions.
age e sex são opcionais. Sem eles, você obtém totais e sobreposições, mas nenhuma comparação de referência.
life_stage ("pregnancy" ou "lactation", feminino, idades 14–50) alterna para os valores de referência de gravidez ou lactação; "pregnant": true e "breastfeeding": true também funcionam. Para bebês, forneça a idade como uma fração de ano (0.25 é 3 meses): os valores de 0–6 e 7–12 meses se aplicam.

A resposta contém, nesta ordem: profile, summary, agent_summary, resolutions (quando nomes ou códigos de barras foram fornecidos), assumptions, suggestions, candidate_results (quando candidatos foram fornecidos), botanicals (quando o conjunto tem algum com sinais do NIH), interactions (quando medicamentos ou condições foram fornecidos), nutrient_totals, overlaps, unrecognized_ingredients, data_gaps, products, sources e disclaimer.

agent_summary são duas a cinco frases simples, geradas deterministicamente a partir dos números abaixo, que um agente pode transmitir como escritas.
suggestions lista, para cada nutriente acima do UL, até três mudanças de produto único (reduce_servings ou remove_product) com a quantidade resultante, se isso sozinho traz o nutriente para ou abaixo do UL (resolves), quais outros nutrientes acima do UL também corrige e quais outros nutrientes uma remoção reduziria. São aritméticos, não conselhos.
candidate_results dá a cada candidato um verdict (adds_above_ul, increases_above_ul, adds_near_ul ou no_new_flags), os novos sinalizadores e os totais antes e depois.

Cada total de nutriente inclui:

Campo	Significado
`daily_total`	Soma entre produtos, na unidade canônica do nutriente (mcg RAE, mcg DFE, mg, mcg)
`complete`	`false` quando algumas linhas do rótulo não puderam ser contadas (veja `data_gaps`); o total é então um limite inferior
`reference`	RDA, EAR, AI e UL para o perfil, com `ul_scope`, `ul_note` e `ul_basis` (contra o que o UL protege, por exemplo "Status reduzido de cobre" para zinco)
`amount_toward_ul`	A parte à qual o UL se aplica: apenas ácido fólico para folato, apenas vitamina A pré-formada para vitamina A
`percent_of_ul`, `percent_of_rda`, `percent_of_ai`	Percentual de cada valor de referência. `percent_of_ul` é omitido quando a porção do UL é apenas parcialmente conhecida e o UL ainda não foi excedido
`coverage`	Percentual da RDA (ou AI) que esses suplementos sozinhos fornecem. Informativo: a dieta normalmente fornece grande parte, então baixa cobertura não é uma deficiência
`flags`	`above_ul` (acima do UL) ou `near_ul` (90–100% do UL). Sem sinalizador significa nada a relatar, não um julgamento sobre o conjunto
`severity`	`high` (duas vezes o UL ou mais), `moderate` (acima do UL), `low` (perto do UL) ou `null`
`contributions`	Quantidade do rótulo de cada produto, quantidade convertida, porções por dia e quantidade diária
`with_typical_diet`	Com `"diet": "typical"`: `food`, `estimated_total`, `amount_toward_ul`, `percent_of_ul`, `coverage` e `flags` com a ingestão média de alimentos dos EUA adicionada

Erros

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

Código	Status	Quando
`INVALID_INPUT`	400	Entrada malformada ou fora do intervalo
`NOT_FOUND`	404	ID DSLD, nutriente ou rota desconhecidos
`UNSUPPORTED`	422	Gravidez ou lactação fora das idades 14–50
`UPSTREAM_UNAVAILABLE`	424	DSLD não pode ser alcançado e nada está em cache (`retryable: true`)
`INTERNAL_ERROR`	422	Falha inesperada. Retornado como 4xx porque gateways Pocket tratam 5xx como falha do fornecedor

Códigos de lacuna de dados

Código	Significado
`BLEND_UNQUANTIFIED`	Uma mistura proprietária lista ingredientes sem suas próprias quantidades; o peso da mistura não é dividido entre eles
`QUANTITY_MISSING`	Uma linha de nutriente reconhecida não tem quantidade
`UNIT_NOT_CONVERTIBLE`	A unidade não pode ser convertida sem ambiguidade, por exemplo vitamina A em UI com forma desconhecida
`COMPOUND_WEIGHT`	A quantidade pode ser peso do composto, não mineral elementar
`AMBIGUOUS_BASIS`	Um ingrediente personalizado nomeado para um composto carece de `nutrient_basis`
`UL_PARTIAL`	O UL se aplica a apenas uma forma (ácido fólico, vitamina A pré-formada) e algumas formas são não especificadas
`PROFILE_MISSING`	Sem idade e sexo, então sem comparação de referência
`PRODUCT_NOT_RESOLVED`	Um nome de produto ou código de barras não pôde ser correspondido a um rótulo DSLD; não é contado
`DATA_SUSPECT`	O registro de rótulo do NIH parece inconsistente; a quantidade ainda é contada. `check` diz qual teste falhou: `duplicate_row` (o mesmo ingrediente duas vezes sob um título, como EPA inserido como DHA), `nested_exceeds_parent` (linhas somam mais do que seu total declarado), `percent_dv_mismatch` (o %VD impresso contradiz a quantidade sob ambos o Valor Diário atual e o pré-2016), `implausible_amount` (mais de 50 vezes o UL adulto mais alto, tipicamente mg digitado para mcg)
`INTERACTIONS_NOT_ASSESSED`	Nenhum `medications` foi fornecido, então interações medicamentosas não foram verificadas. Interações suplemento-suplemento nunca são avaliadas
`INTERACTIONS_PARTIAL`	Medicamentos foram verificados, mas apenas contra as interações nomeadas nas fichas técnicas do NIH ODS; a lista não é exaustiva
`FOOD_NOT_RESOLVED`	Um alimento em `foods` não correspondeu a nenhum alimento USDA SR28 e não é contado
`FOOD_PORTION_UNKNOWN`	O USDA não lista porção para a unidade fornecida para aquele alimento; as porções listadas estão em `foods.items[].portions` (forneça gramas em vez disso)
`FDA_UNAVAILABLE`	`/v1/products/fda` apenas: openFDA não pôde ser alcançado para recalls ou eventos adversos; o resto da resposta permanece
`MEDICATION_NOT_RECOGNIZED`	Um nome de medicamento não correspondeu a nenhuma classe na lista de interações da ficha técnica do NIH (diretamente ou via RxNorm), então nada foi verificado para ele

Como os números são produzidos

A precisão é verificada contra 56 casos trabalhados manualmente; veja EVAL.md.

Leitura de rótulos DSLD:
- O DSLD frequentemente armazena vitamina A como mcg ou mg simples. É lido como mcg RAE somente quando o %VD do rótulo corresponde ao Valor Diário de 900 mcg RAE.
- Quando o DSLD omite uma unidade (por exemplo, "6 NP"), ela é inferida somente se o %VD do rótulo corresponder ao Valor Diário da FDA; caso contrário, é uma lacuna.
- Linhas aninhadas sob um nutriente o detalham por forma (folato 800 mcg DFE = ácido fólico 480 mcg). Elas fornecem a porção exata do UL e nunca são contadas duas vezes.
- Declarações de forma compartilhada ("40% como beta-caroteno") dividem conversões de IU exatamente quando cobrem 100%. Quando cobrem menos, o restante é tratado como forma desconhecida.
- Gama e delta tocoferóis e tocotrienóis não são contados como vitamina E.
Correspondência de um ingrediente a um nutriente tenta, em ordem: o ingredientGroup do DSLD, o código UNII, um sinônimo exato e, em seguida, um nome de forma exato que pertença a exatamente um nutriente. Não há correspondência por substring ou difusa, então "Vitamina B" nunca corresponde a "Vitamina B12". Qualquer outra coisa vai para unrecognized_ingredients.
Conversão de unidades ocorre somente quando o resultado é inequívoco:
- Vitamina D: 1 mcg = 40 UI.
- Vitamina E: forma natural 0,67 mg por UI, forma sintética 0,45 mg por UI. Uma forma desconhecida se torna uma lacuna de dados.
- Vitamina A: UI converte somente para retinol (0,3 mcg RAE por UI) ou beta-caroteno suplementar (0,3 mcg RAE por UI).
- Folato: mcg simples de ácido fólico × 1,7 = mcg DFE.
- O %VD é exibido exatamente como no rótulo e nunca é usado nos totais.
Escopo do UL é armazenado para cada nutriente e explicado na resposta:
- Magnésio: somente suplementos e medicamentos.
- Folato: somente ácido fólico.
- Vitamina A: somente pré-formada.
- Niacina e vitamina E: ingestão suplementar.
- Todo o resto é um UL de ingestão total. Um total de suplemento abaixo de um desses não mostra que a ingestão total está abaixo dele, e assumptions diz isso.
Dados de referência vivem em data/source/manual.json. scripts/build-nutrients.ts constrói data/nutrients.json a partir dele e da exportação global_compounds do SuppleTracker, se presente. A construção valida unidades, fontes, faixas etárias e colisões de sinônimos. Ela cobre 26 vitaminas e minerais com DRIs, além de EPA, DHA, melatonina, CoQ10 e beta-caroteno, que são reconhecidos, mas não têm valores de referência.

Executando localmente

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

Variável de ambiente	Padrão	Finalidade
`PORT` / `HOST`	`8080` / `0.0.0.0`	Endereço de escuta
`DSLD_API_KEY`	nenhum	Uma chave api.data.gov, enviada ao DSLD como `X-Api-Key` (aumenta o limite do NIH de 1.000 para 10.000 solicitações por hora)
`OPENFDA_API_KEY`	nenhum	A mesma chave api.data.gov, para openFDA
`OPENFDA` / `RXNORM`	ativado	`off` interrompe chamadas para openFDA ou RxNorm (a correspondência de medicamentos então usa apenas os nomes em data/interactions.json)
`FREE_TIER_HOSTS`	nenhum	Nomes de host que recebem as cotas de teste gratuito (a demonstração usa `agents.trackmysupplement.com`); solicitações em outros hosts, como relays Pocket, nunca são medidas. `FREE_TIER_PER_SESSION`, `FREE_TIER_PER_IP`, `FREE_TIER_PER_IP_MCP` e `FREE_TIER_GLOBAL` alteram as cotas
`DSLD_BASE_URL`	`https://api.ods.od.nih.gov/dsld/v9`	Base da API DSLD
`DSLD_PREWARM_IDS`	nenhum	IDs de rótulos separados por vírgula para cache na inicialização
`DSLD_STORE_PATH`	`/data/dsld.sqlite` no contêiner, desativado caso contrário	Armazenamento persistente de rótulos (SQLite). Cada rótulo buscado é mantido; quando o NIH está inacessível, rótulos, códigos de barras e pesquisas são respondidos a partir dele. Vazio o desativa
`DSLD_WARM`	`1`	Com o armazenamento ativado, um trabalho em segundo plano busca produtos populares a cerca de uma solicitação por segundo (consultas em data/warm-queries.json). `0` o desativa
`DSLD_FIXTURES_DIR`	nenhum	Servir DSLD de arquivos `label-<id>.json` locais (somente desenvolvimento; `test/fixtures/dsld/real` contém 12 rótulos reais)
`UPSTREAM_BUDGET_MS`	`8000`	Tempo total que uma solicitação pode gastar esperando o DSLD antes de responder `424`
`LOG_LEVEL`	`info`	Os logs registram apenas método, caminho, status e duração, nunca corpos de solicitação

Limites

Até 15 produtos e 5 candidatos por chamada de análise, 10 IDs por chamada get e 10 resultados de pesquisa.
O download completo do DSLD do NIH (214.782 rótulos) é espelhado no armazenamento de rótulos e atualizado semanalmente quando o NIH publica um novo. Rótulos e códigos de barras no espelho são respondidos sem chamar o NIH. Pesquisas de nome usam a API ao vivo (com uma chave api.data.gov) e recorrem ao espelho, alternando automaticamente para ele por 10 minutos sempre que o NIH limita a taxa. GET /v1/provenance mostra a versão espelhada.
Chamadas DSLD são executadas no máximo 4 por vez, com prazo de 6 s cada e orçamento de 8 s por solicitação. Rótulos são armazenados em cache na memória por 7 dias e pesquisas por 24 horas, e rótulos também são mantidos no armazenamento persistente (atualizados após 30 dias). Se o DSLD estiver inativo, cópias obsoletas e o armazenamento de rótulos respondem; resultados de pesquisa do armazenamento dizem "search_source": "local". Medido contra o DSLD ao vivo: uma análise fria de 15 produtos leva 1,5 s e uma quente 17 ms.
Texto que gateways Pocket tratam como sinal de erro ("timeout", "block not found" e outros) é escapado com \u nas respostas. Ele decodifica para a mesma string.
Idades de nascimento a 120, além de gravidez e lactação (14–50). A cafeína é verificada contra as diretrizes da FDA (400 mg por dia para adultos saudáveis, menos de 200 mg na gravidez) e o sódio contra a Ingestão de Redução de Risco de Doença Crônica de 2019 (2.300 mg), nenhum dos quais é um UL de DRI; a resposta diz isso em ul_note.
O endpoint público de demonstração é um teste gratuito. Ele permite 30 solicitações por minuto por cliente, além de cotas diárias que redefinem às 00:00 UTC:
- 25 chamadas de ferramenta por conexão MCP (cada conexão recebe seu próprio Mcp-Session-Id), no máximo 20 por minuto;
- 100 chamadas REST por IP;
- 1.000 chamadas MCP por IP (clientes hospedados, como claude.ai, compartilham endereços de saída);
- 5.000 chamadas gratuitas no total. Descoberta (rotas GET, initialize, tools/list) é gratuita. Resultados nunca são degradados. Respostas REST carregam cabeçalhos X-Free-Tier-Remaining, X-Free-Tier-Limit e X-Free-Tier-Reset, e resultados MCP carregam o mesmo em _meta.free_tier. Além de uma cota, REST responde 429 RATE_LIMITED, e MCP retorna um resultado de ferramenta legível dizendo quando a cota redefine e como mudar para a rota Pocket paga.
- Contadores são hashes com sal, mantidos por dois dias.
- Relays através da Pocket Network nunca são medidos.

Aviso legal, termos e licenças

Somente informações, não aconselhamento médico. O serviço relata o que os rótulos de suplementos declaram e como os totais se comparam com valores de referência, interações e declarações de segurança publicadas pelo NIH e FDA. Não é um diagnóstico ou recomendação de tratamento, não substitui um médico ou farmacêutico e não se destina a diagnosticar, tratar, curar ou prevenir qualquer doença. Rótulos e dados públicos podem estar errados ou desatualizados, a lista de interações cobre apenas o que o NIH nomeia, e nenhum sinalizador não é um sinal de tudo limpo. Consulte um profissional de saúde antes de iniciar, interromper ou alterar um suplemento ou medicamento; em emergência, ligue para 911 ou Controle de Intoxicações (1-800-222-1222) nos EUA. Cada resposta carrega isso em seu campo disclaimer e na última frase de agent_summary, e aplicativos e agentes que retransmitem resultados concordam em repassar isso.

O uso do serviço hospedado é regido pelos termos de uso. NIH, FDA e USDA não endossam este serviço, e nomes de marcas são usados apenas para identificar produtos.

O código está sob a Licença MIT. Os dados servidos de DSLD, ODS, NCCIH, RxNorm, openFDA e USDA são trabalho do Governo dos EUA em domínio público; os arquivos curados de interações e ervas em data/ citam suas fontes do NIH.