FoodEx2 Encoder

foodex2-encoder

英語の食品の説明を、EFSA FoodEx2 コード（MTX カタログ）に変換するライブラリ兼 stdio MCP サーバーです。コードには基本用語、ファセット記述子、コードで表現できない内容を示すラベル付きフリーテキストが含まれます。

このリポジトリがコアです。ホスト版は https://foodex2-encoder.foodnotes.org/ で利用できます。

制限事項

使用する前に、コードを必ず確認してください。特に、次の点に注意してください。

• 入力は英語のみです。英語で一般的に使われる外国語の食品名も含みます。
• カタログで複数の用語に分けられているグループ名は、フリーテキストのまま保持されます。 カタログに複数の個別用語としてしか登録されていない名称を使った説明では、その部分はコードではなくフリーテキストになります。たとえば、canned shellfish は、甲殻類と軟体動物から作られた Canned seafood ではなく、フリーテキストに source-commodity=shellfish を付けた Canned seafood としてコード化されます。コードに誤りはありませんが、説明よりも広い範囲を表します。Canned seafood は、ウニなど、ほかの海洋動物も対象とするためです。

必要なもの

• Node.js 20+
• Python 3（ベンダー提供の EFSA .ecf からカタログを一度だけビルドするため）
• OpenAI 互換のモデルエンドポイントと API キー（デフォルトは OpenRouter）

インストール

git clone https://github.com/FoodNotes-org/foodex2-encoder.git
cd foodex2-encoder
git submodule update --init
npm install
npm run build:catalogue
npm run build:embeddings

data/ はローカルで生成され（約 25 MB）、gitignore の対象です。 vendor/efsa-catalogues サブモジュールを更新した後は再ビルドしてください。

src/rules/ のコーディングルール（EFSA ビジネスルール、ファセットの基数、独自のチェック）は、FoodEx2 Atlas バリデーターと共有されています。データは rules/cardinality.yaml、rules/conflicts.yaml、vendor/efsa-business-rules/ にあります。これらを編集した後は、npm run build:rules でコミット対象の src/rules/rules-data.json を再生成してください。ソース、ライセンス、制限事項については rules/efsa-business-rules.md を参照してください。

モデルエンドポイント

.env をコピーするか、同じ変数をエクスポートしてください。OpenRouter ではキーだけが必要です。

FOODEX2_LLM_API_KEY=sk-or-…          # or OPENROUTER_API_KEY
# optional:
# FOODEX2_LLM_BASE_URL=https://openrouter.ai/api/v1
# FOODEX2_MODEL=openai/gpt-5.4

ほかの OpenAI 互換エンドポイントも同様に動作します（FOODEX2_LLM_BASE_URL、FOODEX2_LLM_API_KEY、FOODEX2_MODEL）。サーバーは分類／選択／残余の各ステップでそのエンドポイントを呼び出します。チャットクライアントのサブスクリプションは別途必要です。

試してみる（CLI）

npm run cli -- encode "orange juice"
npm run cli -- encode "fried rice with chicken"
npm run cli -- traverse "eggplant"    # walk only (debug)

語彙の一致が見つかった場合は、約 1 秒で結果が返ります。カタログをたどる必要がある説明では、通常 15～25 秒かかります。

試してみる（MCP stdio）

npm run server

クライアントからそのプロセスを指定してください。Cursor の例（mcp.json）：

{
  "mcpServers": {
    "foodex2-encoder": {
      "command": "npx",
      "args": ["tsx", "/ABS/PATH/TO/foodex2-encoder/src/server.ts"],
      "env": {
        "FOODEX2_LLM_API_KEY": "sk-or-…"
      }
    }
  }
}

ツール：encode。コード、基本用語、ファセット、フリーテキスト、適合度、方式、および短い explanation が返されます。カタログの検索、デコード、検証、EFSA のガイダンスは、無料の FoodEx2 Atlas MCP で利用できます。

テストと評価

npm test                 # unit tests (no model)
npm run lexical-eval     # lexical base-term cases (no model)
npm run encode-eval      # end-to-end gold set (needs a model key)

eval/encode-base-term.yaml は、機能ごとに現実的なケースを 1 つずつ含む、小規模で焦点を絞ったリグレッションテストセットです（カタログの同義語、モデルの同義語、料理名、抑制など）。正解ルールでは、ファセットやフリーテキストの断片を必須または禁止にできます。expected には、許容される基本コードを複数指定できます（いずれか）。

npm run encode-eval はモデルと MTX のバージョンを記録し、すべての実行が完了すると、公開またはパブリックコアリポジトリとの共有に使用できる eval/results/encode-base-term.json を書き出します。必ず、そのファイルの _provenance に記載されたモデルを明記してください。

構成

src/encode/     lexical → traverse → select → residuals
src/search/     lexical + embedding retrieval
src/server.ts   stdio MCP
src/tools.ts    tool handlers (shared surface for a future Worker wrapper)
data/           generated catalogue + embeddings (local)
eval/           gold cases + results artifact
vendor/         EFSA catalogues (submodule)

ライセンス

MIT — LICENSE を参照してください。Copyright (c) 2026 e-accent BV.

このライセンス許諾は、このソフトウェアを対象とします。vendor/efsa-catalogues/ にある EFSA カタログファイルと、それらを基に生成された data/ は、引き続き EFSA の規約に従います。

帰属表示（評価用入力）

eval/ の評価ケースで使用されている食品名の一部は、各国の食品成分データベースから引用しています。使用しているのは食品名のみで、栄養価は使用していません。これらのデータベースには、引き続き各発行元の利用条件が適用されます。

• CIQUAL（フランス、ANSES）— ciqual.anses.fr。 引用表記：Anses. Table de composition nutritionnelle des aliments Ciqual. データはEtalab Open Licence 2.0に基づいて利用できます。
• CoFID（英国）— McCance and Widdowson’s Composition of Foods Integrated Dataset、GOV.UK。 Open Government Licence v3.0に基づいてライセンスされた公共部門情報が含まれています。