内容
# 卡路里表格 MCP
用于通过卡路里表格网络应用使用的非官方网络端点，搜索和编写卡路里表格食物日记条目。
该服务器设计用于诸如“将这些Mealie衍生的食物记录到卡路里表格中”之类的助手工作流程，而无需将v1直接耦合到Mealie。它接受来自任何调用者的规范化项目有效载荷。
## 安全模型
- 通过环境变量配置多个帐户。
- 读取/搜索工具可以使用`KT_DEFAULT_ACCOUNT`。
- 每个写入工具都需要一个明确的`account`。
- 默认情况下，写入工具永远不会写入。
- 只有当`commit=true`时，才会发生实际写入。
- 流式HTTP `/mcp`可以使用`MCP_BEARER_TOKEN`保护。
- `/health`仅检查进程/配置的活跃度。它不会登录，搜索或写入。
- 活动凭证验证作为明确的`check_account_auth(account)`工具公开。
## Docker
```bash
cp .env.example .env
docker compose up -d
curl -fsS http://localhost:8080/health
```
镜像:
```text
ghcr.io/nikopol666/kaloricke-tabulky-mcp:latest
```
`latest`仅从semver发布标签发布。
## 环境
```env
KT_ACCOUNTS=personal,partner
KT_ACCOUNT_PERSONAL_EMAIL=user@example.com
KT_ACCOUNT_PERSONAL_PASSWORD=replace-me
# Optional alternative when plaintext contains characters that are hard to pass through Compose/Portainer:
# KT_ACCOUNT_PERSONAL_PASSWORD_MD5=32-character-browser-md5
KT_ACCOUNT_PARTNER_EMAIL=partner@example.com
KT_ACCOUNT_PARTNER_PASSWORD=replace-me
# KT_ACCOUNT_PARTNER_PASSWORD_MD5=32-character-browser-md5
KT_DEFAULT_ACCOUNT=personal
MCP_BEARER_TOKEN=replace-me-long-random-token
MCP_HTTP_PORT=8080
```
别名规范化为小写下划线。诸如`my-account`和`my_account`之类的冲突将被拒绝。
`KT_ACCOUNT_<ALIAS>_PASSWORD_MD5`是可选的，并且在设置时优先于纯文本密码。将其视为密码等效的秘密材料。
当设置`MCP_BEARER_TOKEN`时，MCP客户端必须向`/mcp`发送`Authorization: Bearer <token>`。`/health`保持未经身份验证以进行容器健康检查。
## 工具
### `list_accounts`
列出安全的帐户别名和掩码电子邮件地址。
### `check_account_auth(account)`
为一个配置的帐户运行显式登录检查。
### `probe_user_meal_endpoints(account)`
用于从身份验证的KT帐户发现私有自定义餐/配方创建表面的只读诊断。它仅获取诸如`/user/recipe/add`，`/user/foodstuff-meal/create`和`/user/settings/meal/detail/0`之类的页面/表单网址，然后返回表单操作，输入名称，脚本网址和端点字符串。它不调用`add`/`save` JSON端点并且不创建配方。
### `search_food(query, account=None, kind="food", page=0, limit=10)`
搜索食物或饮料条目。`kind`是`food`或`drink`。
### `list_custom_recipes(account, query="", page=0, limit=50)`
从`/user/settings/meal/list?format=json&page=...&limit=...&query=...`列出私有自定义配方/餐。 在调用`create_custom_recipe`后使用此功能以验证配方是否存在并检索其`recipe_guid`以用于`record_recipe_serving`。
### `record_food(...)`
预览：
```json
{
"account": "personal",
"date": "2026-05-18",
"meal_type": "lunch",
"query": "rýže vařená",
"amount": 150,
"unit": "g"
}
```
写入：
```json
{
"account": "personal",
"date": "2026-05-18",
"meal_type": "lunch",
"query": "rýže vařená",
"amount": 150,
"unit": "g",
"commit": true
}
```
### `record_food_batch(account, date, items, commit=false)`
适用于Mealie/assistant工作流程的规范有效载荷：
```json
{
"account": "personal",
"date": "2026-05-18",
"default_meal_type": "lunch",
"items": [
{"name": "kuřecí prsa", "amount": 180, "unit": "g", "source": "mealie"},
{"name": "rýže vařená", "amount": 150, "unit": "g", "source": "mealie"}
]
}
```
仅在查看预览后添加`"commit": true`。
### `prepare_recipe_import(account, title, ingredients, ...)`
Mealie到卡路里表格配方的预览助手。 它解析每个配方成分以获取卡路里表格食物有效载荷，并返回匹配的`food_guid`，单位选择，乘数和源元数据。 使用此功能在调用`create_custom_recipe`之前查看匹配结果。
```json
{
"account": "personal",
"title": "Lasagne podle Mealie",
"servings": 4,
"source": "mealie",
"source_id": "lasagne",
"ingredients": [
{"name": "mleté hovězí maso", "amount": 500, "unit": "g", "source": "mealie"},
{"name": "krájená rajčata", "amount": 400, "unit": "g", "source": "mealie"}
]
}
```
### `create_custom_recipe(...)`
预览或创建真正的私有卡路里表格自定义配方。 默认情况下，写入端点为`/user/settings/meal/detail/edit/0?format=json`;传递`recipe_guid`以通过`/user/settings/meal/detail/edit/{recipe_guid}?format=json`更新现有的自定义配方。 仅当`"commit": true`时，才会发生写入。 KT从解析的成分项中计算营养。
```json
{
"account": "personal",
"title": "Lasagne podle Mealie",
"recipe_guid": "optional-existing-custom-recipe-guid",
"servings": 4,
"preparation_time_minutes": 60,
"source": "mealie",
"source_id": "lasagne",
"ingredients": [
{"name": "mleté hovězí maso", "amount": 500, "unit": "g", "source": "mealie"},
{"name": "krájená rajčata", "amount": 400, "unit": "g", "source": "mealie"}
],
"commit": true
}
```
响应包括`recipe_guid`。 使用该GUID和`record_recipe_serving`记录创建的配方的部分。 预览响应返回一个紧凑的`payload_summary`;仅当需要完整KT JSON正文时，为诊断设置`include_payload=true`。
### `upload_custom_recipe_image(...)`
预览或将图像上传到现有的卡路里表格自定义配方，通过`/user/settings/meal/detail/{recipe_guid}/image/create?format=json`。 仅当`"commit": true`时，才会发生写入。 将图像作为原始base64或`data:image/...;base64,...` URL传递; 服务器使用身份验证的KT会话，而不是来自DevTools捕获的浏览器cookie。
```json
{
"account": "personal",
"recipe_guid": "created-kt-custom-recipe-guid",
"image_base64": "data:image/jpeg;base64,...",
"filename": "lasagne.jpg",
"content_type": "image/jpeg",
"commit": true
}
```
观察到的KT多部分字段名称默认为`file`。 仅当将来的浏览器捕获显示不同的表单字段时，才覆盖`field_name`。
### `record_recipe_serving(...)`
预览或记录卡路里表格自定义配方的份量，记录后配方存在于帐户中。 自定义配方通过与常规食物相同的卡路里表格食物/餐查找和日记添加流程解析。
预览：
```json
{
"account": "personal",
"date": "2026-06-01",
"meal_type": "dinner",
"query": "Lasagne podle Mealie",
"amount": 1,
"unit": "porce"
}
```
写入：
```json
{
"account": "personal",
"date": "2026-06-01",
"meal_type": "dinner",
"recipe_guid": "resolved-or-created-kt-guid",
"amount": 1,
"unit": "porce",
"commit": true
}
```
### `get_diary_summary(account=None, date=None)`
返回每日汇总指标。
### `get_diary_detail(account=None, date=None)`
返回每日日记详细有效载荷用于诊断。
### `record_weight(account, weight_kg, date=None, commit=false)`
预览或写入体重。 需要明确的`account`和`commit=true`才能写入。
## 开发
```bash
python -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest
python -m compileall src tests
```
本地运行：
```bash
python -m kaloricke_tabulky_mcp.main --transport streamable-http
```
## 注意事项
本项目与卡路里表格无关。 它使用非官方的网络端点，这些端点可能会在未经通知的情况下更改。
