Gurkerl Recommender MCP
Explainable grocery recommendations, with MCP integration.
Nutrition- and budget-aware grocery ranking, offer monitoring and weekly digests, with offline samples and optional MCP/Telegram integrations.
Technology: Python · SQLite · MCP · Optional Node.js bridge · Telegram
What it does
- Explainable scoring for nutrition, price, promotions and close-to-expiry offers.
- A dependency-free sample recommender and configurable monitoring pipeline.
- Weekly plans/digests, notification deduplication and SQLite state.
- An optional local MCP server and clients for authenticated external MCP services.
Project status
A personal recommendation toolkit with reproducible offline examples. External service ingestion and account tools require separate credentials and authorization. Recommendations do not provide medical nutrition advice or automatically place orders.
Quick start
Requires Python 3.11+ for the documented setup; Node.js 22+ is needed only for the optional JavaScript bridge.
git clone https://github.com/Fernise/gurkerl-recommender-mcp.git
cd gurkerl-recommender-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
python -m gurkerl_recommender.cli --sample
python -m gurkerl_recommender.monitor_cli --config config.example.json
The sample configuration is offline and prints to the console. To expose the local recommendation tools through MCP:
python -m pip install -e '.[mcp]'
python -m gurkerl_recommender.server
For the optional Node SDK helper, run npm ci first. See configuration, scoring and MCP integration notes. Real account credentials belong only in an ignored local .env file.
Verification
python -m unittest discover -s tests -v
The suite uses sample products and mocked external responses. Authenticated grocery access, MCP account tools and Telegram delivery are not exercised during CI.
Repository map
| Path | Responsibility |
|---|---|
gurkerl_recommender/ |
Scoring, models, sources, MCP clients and CLI commands |
tests/ |
Offline scoring, monitor, client and notifier regressions |
scripts/ |
Optional Node MCP discovery helpers |
config*.example.json |
Safe source/notifier configuration examples |
profile.example.json |
Fictional recommendation preferences |
deploy/ |
Example service/timer units |
Documentation
- Verification record and limits
- Architecture and data boundaries
- Configuration
- Security policy
- Contribution guidance
- Third-party notices
License
Original project code is licensed under the MIT License.
Third-party libraries and assets retain their own licenses.