FoodEx2 Encoder

foodex2-encoder

将英文食品描述转换为 EFSA FoodEx2 代码（MTX catalogue）的库和 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)

词汇匹配通常约一秒即可返回。需要遍历目录的描述通常需要 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 是一组精简且有针对性的回归测试：每项能力对应一个实际案例（目录同义词、模型同义词、命名菜肴、克制处理等）。Gold 规则可以要求或禁止特定面面和自由文本片段；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。版权所有 (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 授权的公共部门信息。