FoodEx2 Encoder MCP server

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:

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.

• English input only, including foreign food names commonly used in English.
• Group names the catalogue splits are kept as free text. When a description

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.

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 (FOODEX2LLMBASEURL, FOODEX2LLMAPIKEY, FOODEX2MODEL). 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), searchterms, getterm. 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.

Shortened. The full README is on GitHub.