FoodEx2 Encoder

foodex2-encoder

Library and stdio MCP server that turns an English food description into an EFSA FoodEx2 code (MTX catalogue): base term, facet descriptors, and labelled free text for what the code cannot express.

This repository is the core. A hosted version is available at https://foodex2-encoder.foodnotes.org/ .

Limitations

Check every code before you use it. In particular:

• English input only, including foreign food names commonly used in English.
• Group names the catalogue splits are kept as free text. When a description uses a name that the catalogue only has as several separate terms, that part goes to free text instead of the code. For example, canned shellfish is coded as Canned seafood with source-commodity=shellfish in free text, rather than Canned seafood made from crustaceans and molluscs. The code is not wrong, but it is broader than the description: Canned seafood also covers other marine animals, such as sea urchins.

What you need

• Node.js 20+
• Python 3 (one-time catalogue build from the vendored EFSA .ecf)
• An OpenAI-compatible model endpoint and API key (OpenRouter is the default)

Install

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/ is generated locally (~25 MB) and is gitignored. Rebuild after updating the vendor/efsa-catalogues submodule.

The coding rules in src/rules/ (EFSA business rules, facet cardinality, our own checks) are shared with the FoodEx2 Atlas validator. Their data comes from rules/cardinality.yaml, rules/conflicts.yaml and vendor/efsa-business-rules/; after editing those, regenerate the committed src/rules/rules-data.json with npm run build:rules. Sources, licence and limits are in rules/efsa-business-rules.md.

Model endpoint

Copy .env (or export the same variables). OpenRouter needs only a key:

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

Any other OpenAI-compatible endpoint works the same way (FOODEX2_LLM_BASE_URL, FOODEX2_LLM_API_KEY, FOODEX2_MODEL). The server calls that endpoint for classify / select / residual steps; your chat client’s subscription is separate.

Try it (CLI)

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

Lexical hits return in about a second. Descriptions that need a catalogue walk typically take 15–25 seconds.

Try it (MCP stdio)

npm run server

Point a client at that process. Cursor example (mcp.json):

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

Tool: encode. It returns the code, base term, facets, free text, fit, method, and a short explanation. Catalogue lookups, decoding, validation and EFSA guidance are in the free FoodEx2 Atlas MCP.

Tests and eval

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 is a small, focused regression set: one realistic case per capability (catalogue synonym, model synonym, named dish, restraint, and so on). Gold rules can require or forbid facets and free-text fragments; expected may list several acceptable base codes (any-of).

npm run encode-eval records the model and MTX version, and on a complete run writes eval/results/encode-base-term.json for publishing or sharing with the public core repo. Always cite the model named in that file’s _provenance.

Layout

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)

Licence

MIT — see LICENSE. Copyright (c) 2026 e-accent BV.

That grant covers this software. EFSA catalogue files under vendor/efsa-catalogues/ (and generated data/ derived from them) remain subject to EFSA’s terms.

Attribution (eval inputs)

Some food names used as evaluation cases under eval/ were drawn from national food composition databases. We use food names only (not nutrient values). Those databases remain under their publishers’ terms:

• CIQUAL (ANSES, France) — ciqual.anses.fr. Cite as: Anses. Table de composition nutritionnelle des aliments Ciqual. Data are available under the Etalab Open Licence 2.0.
• CoFID (UK) — McCance and Widdowson’s Composition of Foods Integrated Dataset, GOV.UK. Contains public sector information licensed under the Open Government Licence v3.0.