mise-en-place

명명된 재료를 명명된 수량으로 입력했을 때 신뢰할 수 있는 매크로영양소 데이터를 반환하는 MCP 서버로, USDA FoodData Central에서 데이터를 가져옵니다.

이 서버의 역할은 단 하나입니다. LLM이 식사를 계획하거나 레시피를 만들 때, 실제 음식과 실제 수량에 대한 실제 칼로리/단백질/탄수화물/지방을 제공하고, 그럴듯해 보이는 추측값은 절대 제공하지 않는 것입니다. 구성, 레시피 설계, 산술 계산은 호출하는 모델의 몫입니다. 올바른 입력을 처리하는 것이 이 서버의 유일한 임무입니다.

무엇인가

mise-en-place는 자체 영양 데이터베이스가 아닙니다. USDA FoodData Central 앞에 놓인 조회 계층으로, LLM이 음식을 검색하고 수량("중간 크기 양파 1개", "테이블스푼 2개", "6 oz")을 그램으로 변환한 뒤, 추측 대신 실제 출처가 있는 매크로를 받아오도록 만들어졌습니다. MCP(stdio)로 실행되므로 MCP를 지원하는 모든 클라이언트(Claude Code, Claude Desktop, 또는 프로토콜을 말하는 다른 어떤 것)가 직접 연결할 수 있습니다.

여덟 가지 도구: search_foods, get_nutrition, get_nutrition_batch, save_override, save_recipe, get_recipe, get_recipe_history, list_recipes. 전체 시그니처와 스키마는 INTERFACES.md에 있습니다.

Related MCP server: Food Data Central MCP Server

사용 방법

요구 사항: Python 3.11+, 무료 USDA FoodData Central API 키(즉시 가입).

git clone <this repo>
cd mise-en-place
uv sync   # or: pip install -e .
export USDA_API_KEY=<your key>

MCP 클라이언트(예: Claude Code)에 등록합니다:

claude mcp add mise-en-place -s local -e USDA_API_KEY=<your key> -- \
  uv run --directory /path/to/mise-en-place mise-en-place

클라이언트를 다시 시작하여 새 연결을 인식하게 한 다음, 요리할 것을 그냥 요청하면 됩니다. 서버 자체의 instructions(server.py의 _SERVER_INSTRUCTIONS에 표시됨)는 연결과 함께 전달되어 모델에게 도구를 올바르게 사용하는 방법을 알려주므로, 채팅에 수동으로 붙여넣을 필요가 없습니다. 자체 매크로 목표로 반복적인 식사 계획 세션을 실행하는 경우 MEAL_PLANNING_PROMPT.md를 참조하세요. 목표는 사람별, 식사별로 설정되므로 서버는 이를 저장하지 않습니다. 그 파일 하나에만 존재합니다.

개인 수정 사항과 저장된 레시피는 ~/.mise-en-place/(MISE_HOME)에 저장되며, 커밋되지 않습니다. 저장소 루트의 masses.toml은 일반적인 가정용 계량 단위 무게(중간 양파, 큰 달걀)의 기본 테이블로, 사람이 작성하고 출처가 명시되어 있으며, 편집하여 반대할 수 있습니다.

왜 사용하는가

"칼로리 알려줘" 도구 중 상당수는 실제로 답을 모르는 질문에 답합니다. 이 도구는 그렇지 않습니다:

• 영양소 값을 절대 지어내지 않습니다. USDA에 해당 수치가 없으면, 도구는 오류를 발생시키거나 명시적으로 부재로 보고합니다. 0으로 처리하거나 추정치를 사실인 것처럼 대체하지 않습니다.

• 반올림된 숫자로 대체하지 않습니다. 질량으로 변환할 수 없는 수량(USDA 자체의 포션 데이터, 사용자의 저장된 수정 사항, 또는 제공된 masses.toml 기본값을 통해)은 100g으로 기본 설정하거나 밀도를 추측하는 대신 오류를 발생시킵니다.

• 불확실한 모든 값은 명시적으로 말합니다. 신뢰도가 낮은 일치, 도구가 확신하지 못한 후보, 가정된 질량: 모든 것이 구조화된 주의 사항으로 호출 모델에 전달되며, 검증된 값과 똑같이 확신하는 것처럼 보이는 숫자가 아닙니다.

• 수정 사항은 도구를 영구적으로 개선합니다. save_override와 save_recipe는 실수를 한 번 수정하면, 같은 재료를 나중에 조회할 때마다 다시 추측하지 않도록 합니다.

• 모델이 스스로 추측하는 것보다 측정 가능하게 더 정확합니다. 수기 검증된 라벨 데이터에 대한 10개 레시피 벤치마크에서 이 도구의 평균 오차는 4.99%였고, 도구 접근이 없는 동일 모델은 8.26%였습니다. 방법론과 현재 수치는 아래에 있습니다.

이것이 실제로 사실인지 어떻게 테스트하는가

"값을 지어내지 않는다"는 규칙은 주장하기 쉽고 조용히 위반하기 쉽습니다. 두 가지가 이를 뒷받침합니다.

실시간 재검증 테스트 데이터. 이 프로젝트가 인용하는 모든 USDA ID(masses.toml 및 테스트 스위트의 골든 값)는 실행할 때마다 실제 API에서 다시 가져와서 주장된 내용과 일치하는지 확인합니다(tests/test_golden_values.py, tests/test_masses_toml.py). 오래된 인용은 권위적으로 보이는 대신 크게 실패합니다.

다른 레시피 사이트의 의견이 아닌 실제 제품 데이터로 정확성 검증. 초기 정확성 검증에서 이 도구의 출력을 인기 있는 건강 레시피 사이트의 공개된 영양 수치와 비교했을 때, 일부 레시피에서 도구가 크게 차이가 나는 것을 발견했습니다. 자세히 살펴보니 차이는 반대 방향이었습니다. 최악의 사례를 실제 제품 영양 라벨과 수기로 확인한 결과, 이 도구의 수치가 실제에 가까웠고, 제3자 사이트의 수치가 이상치였습니다. 어떤 레시피 사이트와 비교하는 것은 잘못된 테스트였습니다. 그 사이트의 방법론은 불투명하고, 어떤 제품을 가격했는지, 어떤 서빙 수율 규칙을 사용했는지, 어떤 영양 데이터베이스가 뒤에 있는지 알 수 없기 때문입니다.

이것이 가리키는 실제 정확성 벤치마크(tests/golden_recipes/)는 의도적으로 분리된 두 가지 소스로 구성됩니다: 진짜 상품 재료에 대한 USDA 데이터(감자, 과립 설탕: 브랜드가 없는 것), 그리고 특정 상업 제품이 의미하는 것에 대한 실제 제품 영양 라벨(토르티야 브랜드, 포장된 두부). USDA 데이터를 사용하여 USDA 기반 도구의 일반 매칭을 검증하는 것은 스스로와 일치하는지 확인하는 것일 뿐입니다. 라벨 데이터는 브랜드 형태의 재료에 대해 실제로 의미 있는 유일한 독립적 확인입니다. 여러 레시피는 의도적으로 동일한 재료를 두 가지 방식으로 표현합니다: 일반 이름("토르티야 칩")과 특정 이름("Mission 토르티야 칩")으로, 벤치마크는 도구의 기본 일반 매칭과 레시피가 이름으로 요청할 때 명명된 제품을 올바르게 찾고 선호하는지 모두 확인합니다.

최신 결과 (10개 레시피, 도구 장착 에이전트 vs. 순수 LLM 회상 에이전트, 둘 다 동일한 수기 검증 라벨 데이터로 점수화, 2026-08-21): 도구 장착 에이전트의 칼로리/단백질/탄수화물/지방 평균 절대 오차는 **4.99%**였고, 도구 접근 없는 동일 에이전트는 **8.26%**였습니다. 도구는 10개 레시피 중 7개에서 완전히 승리했으며, 진짜 어려운 브랜드 재료나 지방 함량을 잘못 기억하기 쉬운 고기 부위(닭다리, 스커트 스테이크)가 있는 레시피에서 결정적으로 승리했습니다. 순수 회상이 동일하거나 더 잘한 세 개의 레시피는 도구 자체의 매칭이 약하다는 증거가 아닙니다. 이는 레시피 자체가 수량을 셀 수 없게 남겨둔 경우(명시된 무게가 없는 가니시)로, 두 조건이 독립적으로 추측해야 했고 벤치마크가 측정하려는 것과 무관한 노이즈를 추가했습니다. 점수를 신뢰하기 전에 수정할 가치가 있는 한 가지 사례는 tests/golden_recipes/eval_prompts.json의 note_on_TC10을 참고하세요. 이 수치는 픽스처와 도구가 계속 변경됨에 따라 변동될 수 있습니다. 영구적인 주장이 아닌 가장 최근의 측정값으로 취급하세요.

더 읽을 곳