recipal-mcp-unofficial

ReciPal 영양성분 라벨 API용 MCP 서버입니다. AI 어시스턴트가 레시피와 재료를 직접 읽고 편집할 수 있게 해주며, 웹 UI에서 몇 시간이 걸릴 대량 작업도 포함합니다.

비공식. ReciPal과 제휴, 보증, 지원 관계가 아닙니다. 제품 사용자들이 공개 API를 대상으로 만든 것입니다.

임시 프로젝트 — 이 저장소는 곧 보관(archive)됩니다. ReciPal이 공식 MCP 서버를 만들고 있습니다. 공식 서버가 출시되면 이 저장소는 해당 서버를 가리키도록 업데이트된 후 보관됩니다. 이 프로젝트에 의존하는 중요한 무언가를 만들지 마세요. 자세한 내용은 SUNSET.md를 참고하세요.

활성 유료 ReciPal 구독이 필요합니다. API 접근은 유료 기능이며, 키는 계정 설정의 API access에서 가져옵니다. 키가 없으면 이 서버는 아무것도 할 수 없습니다.

용도

ReciPal의 웹 UI는 레시피 하나를 편집하기에는 괜찮습니다. 하지만 40개를 한 번에 수정해야 할 때는 고통스럽습니다. 카탈로그 전체의 서빙 사이즈를 고치거나, (copy) 접미사로 들어온 재료 이름을 바꾸거나, 재료 하나만 다른 제품 변형 제품군을 만들 때 말이죠. 이 서버는 API를 노출해서 어시스턴트가 먼저 dry run을 수행한 뒤 반복 작업을 할 수 있게 해줍니다.

가장 유용한 도구는 bulk_clone_and_swap입니다. 완전히 구성된 레시피 하나를 템플릿으로 사용해 N개로 복제하고, 각 복제본에서 단일 재료를 교체합니다. 라벨 설정, 태그, 제공량이 함께 전달되어 복제본이 일관되게 생성됩니다.

Related MCP server: cookwith-mcp

범위와 배포

의도적으로 범위를 좁혔으며, 앞으로도 그럴 것입니다:

• 직접 복제해서 빌드하는 소스입니다. 원클릭 플러그인 번들, npx 패키지, MCP 디렉토리나 마켓플레이스 등록은 없습니다. 이는 ReciPal에 한 약속이며, 미뤄둔 일이나 할 일 목록이 아닙니다.

• npm에 게시하지 않습니다. package.json은 의도적으로 private로 표시되어 있습니다.

• ReciPal의 요청으로 recipal-mcp-unofficial로 명명되었으며, 공식 서버로 오인될 수 없도록 하기 위함입니다.

패키지 배포, 마켓플레이스 등록, 또는 더 쉬운 소비자 설치 경로를 추가하는 Pull Request는 거절됩니다. 어떤 기여가 환영받는지는 CONTRIBUTING.md를 참고하세요.

설치

Node.js 18 이상이 필요합니다.

git clone https://github.com/BlackBlack/recipal-mcp-unofficial.git
cd recipal-mcp-unofficial
npm install
npm run build

그런 다음 MCP 클라이언트에 등록하세요. Claude Code의 경우:

claude mcp add --transport stdio recipal-mcp-unofficial \
  --env RECIPAL_API_KEY=your_key_here \
  -- node /absolute/path/to/recipal-mcp-unofficial/build/index.js

Claude Desktop의 경우 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "recipal-mcp-unofficial": {
      "command": "node",
      "args": ["/absolute/path/to/recipal-mcp-unofficial/build/index.js"],
      "env": { "RECIPAL_API_KEY": "your_key_here" }
    }
  }
}

클라이언트를 재시작한 후, 레시피 목록을 요청해 보세요. 19개의 도구가 표시될 것입니다. 전체 가이드는 docs/SETUP.md를 참고하세요.

⚠️ 중요한 데이터가 있는 카탈로그에 연결하기 전에 읽어보세요

confirm: true 및 dry_run 보호 장치는 사용자가 아니라 모델이 제공합니다. 이는 모호한 프롬프트가 피해를 입히는 것을 막기 위한 것입니다. 단호하거나 혼란에 빠진 에이전트를 막지는 못합니다 — 레시피를 삭제하기로 결정한 어시스턴트는 같은 호출에서 confirm: true를 전달할 것입니다. ReciPal에는 실행 취소가 없습니다.

그렇기 때문에 실제로 파괴적인 도구는 기본적으로 꺼져 있으며, 사용자가 명시적으로 활성화해야 합니다:

Delete 및 raw 도구는 기본적으로 꺼져 있습니다. 켜면 연결한 모든 클라이언트가 삭제를 실행할 수 있으므로, 실제 데이터로 작업하기 전에 먼저 재료(throwaway) 레시피에서 테스트하세요.

모든 쓰기 도구는 dry_run 및 confirm 가드를 지원합니다. 자세한 내용은 docs/TOOLS.md를 참고하세요. MCP 클라이언트가 승격된 도구 호출을 명시적으로 승인하지 않는 한 confirm은 자동으로 전달되지 않습니다.

⚠️ 소중한 카탈로그에 연결하기 전에 읽어보세요

confirm: true 및 dry_run 가드는 사용자가 아닌 모델이 제공합니다. 이 가드는 모호한 프롬프트가 피해를 입히는 것을 막아줍니다. 결단력 있는 또는 혼란스러운 에이전트를 막지는 못합니다 — 레시피를 삭제하기로 결정한 어시스턴트는 같은 호출에서 confirm: true를 전달할 것입니다.

그렇기 때문에 파괴적인 도구는 기본적으로 비활성화되어 있습니다. 활성화하는 것은 대화에 의한 결정이 아니라 서버를 실행하는 사람의 명시적인 결정입니다:

이 두 가지를 제외한 모든 도구는 기본적으로 활성화되어 있고, 읽기 전용 또는 dry-run 안전 모드입니다.

confirm: true와 dry_run 가드는 사용자가 아닌 모델이 공급합니다. 모호한 프롬프트가 피해를 입히는 것을 막아주지만, 결심한(또는 혼란스러운) 에이전트를 막지는 못합니다. 레시피를 삭제하기로 결정한 어시스턴트는 같은 호출에서 confirm: true를 전달할 것입니다. ReciPal에는 휴지통이 없습니다. delete_recipe는 되돌릴 수 없습니다.

안전하게 실험하려면: 아무거나 사용해도 되는 별도의 레시피 카탈로그(문서화된 데모 또는 테스트 카탈로그)에서 이 서버를 실행하고, dry run부터 시작하세요. 권장되는 안전 흐름은 docs/TESTING.md에 있습니다. list_recipes + get_recipe + get_recipe_nutrition 각각에 대해 한 번 시도해 보고, 실제로 라이브 카탈로그에 쓰기 전에 실패 여부를 확인하세요.

이 프로젝트에 익숙해지고 로컬에서 실행하기 위한 좋은 첫 단계는 docs/SETUP.md의 전 과정을 따르는 것입니다.

일반적인 사용 패턴

다음은 실제로 잘 작동하는 프롬프트와 워크플로입니다:

캘린더 기반 변형. 감사 추적에 도움이 되도록 레시피 이름에 날짜가 접미사로 붙은 템플릿 레시피가 있다면:

카탈로그의 모든 레시피를 가져와서, (2025)와 (2024)가 이름에 포함된 것을 찾아주세요. 그런 다음 2024년 레시피 각각에 대해 resting_time_minutes = 45로 업데이트하세요. 하지만 먼저 변경 사항을 표로 알려주고, 승인 전까지는 아무것도 실행하지 마세요.

내부 동작: 어시스턴트는 list_recipes를 호출하고, 일치하는 항목을 필터링한 다음, 각 레시피 ID에 대해 update_recipe를 실행합니다. dry_run: true로 되돌아갈 수 있는 --dry-run 플래그는 없습니다 — 서버는 상태 비저장이므로, 클라이언트가 결정적으로 dry run을 수행할 방법이 없습니다.

반복적인 재료 교체. bulk_clone_and_swap은 동일한 단일 재료가 (약간 다른 이름의) N개 제품에 나타나는 경우를 위해 설계되었습니다:

"반죽" 레시피를 템플릿으로 사용하여 "쿠키" 제품 5개를 만들어 주세요. 각각 base_flour를 rye_flour로 바꾸고, 이름에 제품 이름을 포함시키고, 100개 단위로 스케일링하세요. 먼저 dry run으로, dry_run: false로는 실행하지 마세요.

지원되는 도구

22개 도구 (기본적으로 20개 활성화). 전체 참조는 docs/TOOLS.md를 참조하세요.

읽기:

• list_recipes — 페이지네이션된 레시피 목록

• get_recipe — 전체 레시피 (기본적으로 서브레시피 확장 포함)

• get_recipe_nutrition — 해당 레시피의 영양성분 패널 데이터

• list_recipe_ingredients — 서브레시피 포함 모든 레시피의 재료 줄

• list_ingredients — 계정의 공유 재료 라이브러리

• get_ingredient — 재료 정의 및 영양 데이터

쓰기:

• create_recipe_ingredient — 레시피에 재료 줄 추가

• update_recipe_ingredient — 재료 줄 편집 (수량, 단위, 영양)

• delete_recipe_ingredient — 재료 줄 제거

• update_recipe — 레시피 메타데이터 편집

• update_recipe_calorie_display — 표시 칼로리 모드 전환

• calculate_recipe — ReciPal의 계산 엔진 강제 실행

• create_recipe — 새 레시피 작성

• delete_recipe — 레시피 삭제 (비활성화됨)

• create_ingredient — 공유 재료 라이브러리에 재료 추가

• update_ingredient — 재료 정의 편집

• list_food_databases — 접근 가능한 식품 데이터베이스 나열

• search_foods — USDA, 공개 및 사용자 정의 데이터베이스에서 식품 검색

• create_recipe_shortcut — 지름길(바로가기) 만들기

고급/대량:

• bulk_clone_and_swap — 기본 레시피를 N번 복제하고 각 복제본의 재료 하나를 교체합니다

• bulk_update_recipe_ingredients — 한 번의 호출로 여러 재료 줄을 수정합니다

알려진 제한 사항

ReciPal API에 대해 실제로 검증된 제한 사항, 추측이 아닙니다:

• API에 따르면 라벨 설정은 어떤 "영양성분 계산" 모드(준비/조리, 드립 팬 등)에서도 달라지지 않습니다. nutrition_calculation_method를 변경해도 동일한 결과가 나옵니다. 결과가 캐시될 가능성이 있습니다.

• update_recipe는 서브레시피를 지원하지 않습니다. 서브레시피의 속성을 업데이트해야 한다면 update_recipe_ingredient를 사용하세요.

• /v1/recipes에 대한 PATCH는 존재하지 않습니다. 예상치 못한 404 또는 405 오류가 발생하면 잘못된 HTTP 동사로 호출한 것입니다.

• bulk_clone_and_swap은 배치 잡을 폴링합니다. 지연 시간은 배치 크기에 따라 수 초에서 수 분까지 다양합니다. 클라이언트 시간 초과를 초과하면 상태를 다시 확인하세요.

• HTTP 429 응답은 API가 아닌 프록시 계층에서 나옵니다. retry-after 헤더가 누락되어 재시도가 어렵습니다 — 호출 사이에 지수 백오프를 구현하세요.

• create_recipe_ingredient의 unit 필드는 (옵션인 경우) recipe_ingredient 키 아래가 아니라 recipe 키 아래에 속합니다. API 스키마가 일반적이지 않지만, 확인했습니다.

• get_recipe는 기본적으로 반환하지 않아도 되는 식품 데이터베이스 항목을 포함하지 않을 수 있습니다. 재료 영양 정보가 필요하면 list_recipe_ingredients를 사용하세요.

개발

이것은 로컬 TypeScript 서버입니다:

npm run typecheck   # tsc --noEmit
npm run build       # -> build/index.js
npm test            # offline smoke tests, no API key or network needed
npm run gen:docs    # regenerate docs/TOOLS.md from the running server
npm run verify      # all of the above

GXP5로 테스트하는 중:

GXP6

npm을 사용하세요. 이 저장소는 Yarn/Bun/pnpm과 같은 다른 패키지 매니저와 함께 사용하도록 설계되지 않았습니다.

문서

• docs/SETUP.md — 설치, 구성, 클라이언트 설치, 문제 해결

• docs/TOOLS.md — 생성된 도구 참조 (스키마 및 예시 포함)

• docs/CONTRIBUTING.md — 기여 지침

• docs/TESTING.md — 테스트 계정으로 확인된 동작 및 알려진 제한 사항

• CHANGELOG.md — 버전별 변경 사항

라이선스

Apache-2.0