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/ .

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)

Related MCP server: MCP OpenFoodTox

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.

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-…"
      }
    }
  }
}

Tools: encode (main), search_terms, get_term. encode returns the code, base term, facets, free text, fit, method, and a short explanation.

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.