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-…
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"
Lexical hits return in about a second. Descriptions that need a catalogue walk
typically take 15–25 seconds.
Try it (MCP stdio)
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
npm run lexical-eval
npm run encode-eval
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.
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: