usda-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['fdcIds'], 'properties': {'unit': {'enum': ['g', 'oz', 'lb', 'kg'], 'type': 'string', 'default': 'g', 'description': 'Unit for quantity. Default "g". Does not support "serving" (use a fixed gram basis for consistent comparison).'}, 'fdcIds': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1}, 'maxItems': 5, 'minItems': 2, 'description': 'FDC IDs to compare â\x80\x94 2 to 5 foods. Use usda_search_foods to discover IDs.'}, 'quantity': {'type': 'number', 'default': 100, 'description': 'Gram basis for comparison. All values scaled to this amount. Must be positive. Default 100.', 'exclusiveMinimum': 0}, 'nutrients': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1}, 'description': 'Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Use usda_list_nutrients to look up other IDs.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['basis', 'foods', 'nutrients']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'basis': {'type': 'object', 'required': ['quantity', 'unit', 'gramWeight'], 'properties': {'unit': {'type': 'string', 'description': 'Unit provided in the request (g, oz, lb, or kg).'}, 'quantity': {'type': 'number', 'description': 'Numeric quantity provided in the request.'}, 'gramWeight': {'type': 'number', 'description': 'Gram weight resolved from quantity+unit â\x80\x94 all nutrient values are per this many grams.'}}, 'description': 'The common scaling basis applied to all nutrient values.', 'additionalProperties': False}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['too_few_foods'], 'description': 'Machine-readable failure mode. Declared by this tool: `too_few_foods`: Fewer than 2 of the provided FDC IDs returned data, making comparison impossible. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'foods': {'type': 'array', 'items': {'type': 'object', 'required': ['fdcId', 'description', 'dataType'], 'properties': {'fdcId': {'type': 'number', 'description': 'FDC ID.'}, 'dataType': {'type': 'string', 'description': 'FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded.'}, 'description': {'type': 'string', 'description': 'Full USDA food name (e.g. "Spinach, raw").'}}, 'description': 'One of the compared foods.', 'additionalProperties': False}, 'description': 'The compared foods, in the same order as the values arrays below.'}, 'nutrients': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'unit', 'values'], 'properties': {'id': {'type': 'number', 'description': 'FDC nutrient ID.'}, 'name': {'type': 'string', 'description': 'Nutrient name (e.g. "Protein", "Energy").'}, 'unit': {'type': 'string', 'description': 'Measurement unit (e.g. "G", "MG", "KCAL").'}, 'values': {'type': 'array', 'items': {'type': ['number', 'null']}, 'description': 'One value per food in the same order as foods[]. null when data is unavailable for that food.'}}, 'description': 'One nutrient row with per-food values.', 'additionalProperties': False}, 'description': 'Nutrient rows â\x80\x94 one entry per requested nutrient, with per-food values in the values[] array.'}, 'missingData': {'type': 'array', 'items': {'type': 'object', 'required': ['fdcId', 'nutrientId'], 'properties': {'fdcId': {'type': 'number', 'description': 'FDC ID that had missing data.'}, 'nutrientId': {'type': ['number', 'null'], 'description': 'Nutrient ID that was missing, or null when the entire food was not found.'}}, 'description': 'A food or food+nutrient pair where data was unavailable.', 'additionalProperties': False}, 'description': 'Foods or food+nutrient pairs where data was unavailable. Absent when all data was present.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['fdcId'], 'properties': {'unit': {'enum': ['g', 'oz', 'lb', 'kg', 'serving'], 'type': 'string', 'description': 'Unit for quantity. "serving" uses the food\'s first defined portion weight. Required when quantity is provided.'}, 'fdcId': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1, 'description': 'FDC ID of the food. Use usda_search_foods to discover IDs.'}, 'quantity': {'type': 'number', 'description': 'Amount of food to scale nutrient values to. Must be positive. When provided, unit is required. Omit for per-100g values (FDC database native basis).', 'exclusiveMinimum': 0}, 'nutrients': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1}, 'description': 'Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008] for protein, fat, carbs, energy). Use usda_list_nutrients to look up IDs. Omit to return all available nutrients.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['fdcId', 'description', 'dataType', 'nutrients']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'quantity_without_unit', 'no_portion_data'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The FDC ID does not exist in the database. `quantity_without_unit`: quantity is provided but unit is omitted. `no_portion_data`: unit="serving" was requested but the food has no portion data. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'fdcId': {'type': 'number', 'description': 'FDC ID of the food.'}, 'dataType': {'type': 'string', 'description': 'FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded.'}, 'scaledTo': {'type': 'object', 'required': ['quantity', 'unit', 'gramWeight'], 'properties': {'unit': {'type': 'string', 'description': 'Unit provided in the request (g, oz, lb, kg, or serving).'}, 'quantity': {'type': 'number', 'description': 'Numeric quantity provided in the request.'}, 'gramWeight': {'type': 'number', 'description': 'Gram weight resolved from quantity+unit â\x80\x94 all nutrient values are per this many grams.'}}, 'description': 'Scaling basis when quantity+unit were provided. Absent when returning per-100g values.', 'additionalProperties': False}, 'brandName': {'type': 'string', 'description': 'Brand name. Branded items only.'}, 'nutrients': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'number', 'amount', 'unit'], 'properties': {'id': {'type': 'number', 'description': 'FDC nutrient ID.'}, 'name': {'type': 'string', 'description': 'Nutrient name (e.g. "Protein", "Energy", "Iron, Fe").'}, 'unit': {'type': 'string', 'description': 'Measurement unit (e.g. "G", "MG", "KCAL").'}, 'amount': {'type': 'number', 'description': 'Nutrient amount â\x80\x94 per 100g, or scaled to quantity+unit if provided.'}, 'number': {'type': 'string', 'description': 'SR reference number (legacy identifier).'}, 'percentDailyValue': {'type': 'number', 'description': 'Percent daily value from product label. Branded items only.'}}, 'description': 'A single nutrient entry with ID, name, amount, and unit.', 'additionalProperties': False}, 'description': 'Nutrient values for this food, per 100g or scaled to the requested quantity.'}, 'brandOwner': {'type': 'string', 'description': 'Brand owner. Branded items only.'}, 'allPortions': {'type': 'array', 'items': {'type': 'object', 'required': ['description', 'gramWeight'], 'properties': {'gramWeight': {'type': 'number', 'description': 'Gram weight of this portion.'}, 'description': {'type': 'string', 'description': 'Portion description.'}}, 'description': 'A named portion for this food.', 'additionalProperties': False}, 'description': 'All named portions for this food.'}, 'description': {'type': 'string', 'description': 'Full USDA food name (e.g. "Chicken, broilers or fryers, breast, meat only, raw").'}, 'ingredients': {'type': 'string', 'description': 'Ingredient list from label. Branded items only.'}, 'servingInfo': {'type': 'object', 'required': ['description', 'gramWeight'], 'properties': {'gramWeight': {'type': 'number', 'description': 'Gram weight of this portion.'}, 'description': {'type': 'string', 'description': 'Portion description (e.g. "1 cup", "4 oz").'}}, 'description': 'First available portion definition, if present.', 'additionalProperties': False}, 'foodCategory': {'type': 'string', 'description': 'USDA food category (e.g. "Poultry Products"). Absent for some branded items.'}, 'publicationDate': {'type': 'string', 'description': 'Date this food entry was published in FDC.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['fdcIds'], 'properties': {'fdcIds': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1}, 'maxItems': 20, 'minItems': 2, 'description': 'FDC IDs to fetch â\x80\x94 2 to 20 IDs. Use usda_search_foods to discover IDs.'}, 'nutrients': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 1}, 'description': 'Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended â\x80\x94 full profiles can be large. Use usda_list_nutrients to look up IDs.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['foods', 'failed']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'foods': {'type': 'array', 'items': {'type': 'object', 'required': ['fdcId', 'description', 'dataType', 'nutrients'], 'properties': {'fdcId': {'type': 'number', 'description': 'FDC ID of this food.'}, 'dataType': {'type': 'string', 'description': 'FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded.'}, 'nutrients': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'number', 'amount', 'unit'], 'properties': {'id': {'type': 'number', 'description': 'FDC nutrient ID.'}, 'name': {'type': 'string', 'description': 'Nutrient name.'}, 'unit': {'type': 'string', 'description': 'Measurement unit (e.g. "G", "MG", "KCAL").'}, 'amount': {'type': 'number', 'description': 'Amount per 100g.'}, 'number': {'type': 'string', 'description': 'SR reference number.'}}, 'description': 'A nutrient entry with ID, name, amount, and unit.', 'additionalProperties': False}, 'description': 'Nutrient values per 100g.'}, 'description': {'type': 'string', 'description': 'Full USDA food name (e.g. "Chicken, broilers or fryers, breast, meat only, raw").'}}, 'description': 'Nutrient profile for one food.', 'additionalProperties': False}, 'description': 'Successfully fetched foods.'}, 'failed': {'type': 'array', 'items': {'type': 'object', 'required': ['fdcId', 'error'], 'properties': {'error': {'type': 'string', 'description': 'Why this ID failed â\x80\x94 not found, no data returned, etc.'}, 'fdcId': {'type': 'number', 'description': 'FDC ID that could not be fetched.'}}, 'description': 'A failed food fetch with the FDC ID and error reason.', 'additionalProperties': False}, 'description': 'IDs that returned no data. Check these with usda_search_foods to verify they exist.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'category': {'enum': ['macronutrients', 'vitamins', 'minerals', 'lipids', 'amino_acids', 'other'], 'type': 'string', 'description': 'Filter to a nutrient category. Omit to return all ~150 tracked nutrients. Options: macronutrients, vitamins, minerals, lipids, amino_acids, other.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['nutrients']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'nutrients': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'number', 'unit', 'category'], 'properties': {'id': {'type': 'number', 'description': 'FDC nutrient ID â\x80\x94 pass this to nutrients[] params on other tools.'}, 'name': {'type': 'string', 'description': 'Human-readable nutrient name (e.g. "Protein", "Iron, Fe").'}, 'unit': {'type': 'string', 'description': 'Measurement unit (e.g. "G", "MG", "UG", "KCAL").'}, 'number': {'type': 'string', 'description': 'SR reference number (legacy identifier, e.g. "203").'}, 'category': {'type': 'string', 'description': 'Nutrient category grouping.'}}, 'description': 'A nutrient reference entry with ID, name, unit, and category.', 'additionalProperties': False}, 'description': 'Nutrient reference entries matching the requested category, or all if category is omitted.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['query'], 'properties': {'query': {'type': 'string', 'minLength': 1, 'description': 'Search terms â\x80\x94 food name, ingredient, or UPC/GTIN code for branded products. Examples: "chicken breast raw", "banana", "012345678901".'}, 'dataType': {'type': 'array', 'items': {'enum': ['SR Legacy', 'Foundation', 'Survey (FNDDS)', 'Branded'], 'type': 'string'}, 'description': 'FDC data sources to search. Omitting this defaults to ["SR Legacy"] (common whole foods, complete nutrient profiles), or to ["Branded"] when brandOwner is set. Include "Branded" for packaged products. Multiple values allowed.'}, 'pageSize': {'type': 'integer', 'default': 10, 'maximum': 50, 'minimum': 1, 'description': 'Number of results per page. Default 10, maximum 50.'}, 'brandOwner': {'type': 'string', 'description': 'Filter branded results by brand owner name (e.g. "General Mills", "Kraft"). Only Branded records carry one, so setting this defaults dataType to ["Branded"] unless dataType is given explicitly.'}, 'pageNumber': {'type': 'integer', 'default': 1, 'maximum': 9007199254740991, 'minimum': 1, 'description': 'Page number (1-based). Use with totalPages to paginate.'}, 'foodCategory': {'type': 'string', 'description': 'Filter by USDA food category (e.g. "Poultry Products", "Vegetables and Vegetable Products"). Case-sensitive.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['totalHits', 'currentPage', 'totalPages', 'foods', 'totalCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['query_empty', 'no_results'], 'description': 'Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'foods': {'type': 'array', 'items': {'type': 'object', 'required': ['fdcId', 'description', 'dataType', 'nutrients'], 'properties': {'fdcId': {'type': 'number', 'description': 'FDC ID â\x80\x94 pass to usda_get_food, usda_get_foods, or usda_compare_foods.'}, 'dataType': {'type': 'string', 'description': 'FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded.'}, 'brandName': {'type': 'string', 'description': 'Brand name. Present for Branded items only.'}, 'nutrients': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'amount', 'unit'], 'properties': {'id': {'type': 'number', 'description': 'FDC nutrient ID.'}, 'name': {'type': 'string', 'description': 'Nutrient name.'}, 'unit': {'type': 'string', 'description': 'Unit (e.g. "G", "MG", "KCAL").'}, 'amount': {'type': 'number', 'description': 'Amount per 100g.'}}, 'description': 'A preview nutrient entry with ID, name, and amount per 100g.', 'additionalProperties': False}, 'description': 'Preview nutrients per 100g â\x80\x94 typically energy, protein, fat, carbs for SR Legacy. Not a complete profile; use usda_get_food for the full set.'}, 'brandOwner': {'type': 'string', 'description': 'Brand owner name. Present for Branded items only.'}, 'description': {'type': 'string', 'description': 'USDA food description (e.g. "Chicken, broilers or fryers, breast, meat only, raw").'}, 'servingSize': {'type': 'number', 'description': 'Serving size in grams from the product label. Branded only.'}, 'foodCategory': {'type': 'string', 'description': 'USDA food category (e.g. "Poultry Products"). Absent for some branded items.'}, 'publishedDate': {'type': 'string', 'description': 'Date the food entry was published in FDC.'}, 'servingSizeUnit': {'type': 'string', 'description': 'Unit for servingSize (usually "g"). Branded only.'}, 'householdServingFullText': {'type': 'string', 'description': 'Serving description as it appears on the label (e.g. "1 cup", "1 oz"). Branded only.'}}, 'description': 'A food item matching the search query.', 'additionalProperties': False}, 'description': 'Foods matching the search query.'}, 'totalHits': {'type': 'number', 'description': 'Total number of foods matching the query across all pages.'}, 'totalCount': {'type': 'number', 'description': 'Total foods matching the query across all pages.'}, 'totalPages': {'type': 'number', 'description': 'Total number of pages available.'}, 'currentPage': {'type': 'number', 'description': 'Current page number (1-based).'}}, 'additionalProperties': False}