mccarbon README

README проекта с github.com/yeqv111/mccarbon. Одним файлом markdown: README.md.

麦麦碳账本 · mccarbon

你大概从没算过,自己在麦当劳吃掉了一年多少公斤二氧化碳。 麦麦碳账本把它算出来,还告诉你换成什么能少一点。

carbon-book-preview


一句话介绍

省钱不是主题,热量不是主题,点餐更不是主题——麦麦碳账本要讲的是「你的麦当劳一年,排了多少碳,以及怎么少排一点」。

它用麦当劳官方 MCP 拉取你的历史订单,按三层碳核算模型(餐品 / 包装 / 配送)估算出个人餐饮碳足迹,产出一份单文件 HTML「碳账本」:总碳足迹、碳等级 A–E、三层结构、月度曲线、碳重集中类别、最碳重一单、直观换算(几棵树 / 开车多少公里),以及一个减排模拟器。

为什么选这个方向? 全站参赛作品里,没有任何一份做环保 / 碳足迹维度(基于对官方仓库全部 529 份参赛作品的竞品分析,详见 workbuddy.md)。它天然契合麦当劳自身的「Plan for Change / 2050 净零」叙事,同时是一个真正的个人工具——不是玩梗,是能用的东西。

核心能力

快速开始

📖 第一次使用? 直接看 USAGE.md。

# 1. 克隆仓库
git clone https://github.com/w16638771062/mccarbon.git
cd mccarbon

# 2. 零安装直接跑(无需第三方依赖、无需 Token、无需联网)
PYTHONPATH=src python3 -m mccarbon demo

# 3. 生成可分享的 HTML 碳账本
PYTHONPATH=src python3 -m mccarbon --mock --html carbon-book.html

嫌 PYTHONPATH=src 麻烦的话,装一次就能用短命令:

pip install .
mccarbon demo

环境要求:Python 3.9+(已在 3.9.6 与 3.13.12 实测通过),零第三方依赖。

方法学(M)

碳足迹题材最怕被质疑「数字是编的」,所以这里把口径写在明处。三层模型:

第一层 · 餐品层(约占总量 90%)

来源 关键数据
Vegan Society「Plate Up For The Planet」 英国麦当劳餐品实测:Double Big Mac 4.46 / Quarter Pounder 2.99 / Big Mac 2.35 / 20 块麦乐鸡 2.13 / Filet-O-Fish 0.82 / McPlant 0.29 / McFlurry 0.17 / 大薯条 0.15(kg CO2e / 份)
ADEME Agribalyse 数据库 快餐汉堡品类 LCA 值 18.6 kg CO2e/kg 成品,其中农业环节占 92.5%
欧盟牛肉 LCA 23.5 kg CO2e/kg——是豆类 / 土豆的 20 倍以上,这就是「换蛋白质」最有效的原因

中文菜单的绝大多数餐品没有公开实测值,因此按碳类别中值外推(牛肉 2.40 / 鸡肉 1.00 / 鱼 0.80 / 植物基 0.30 / 小食 0.35 … kg CO2e 每份)。这比把英国单品数据硬套到中文菜单上更稳,也更好解释。

第二层 · 包装层

依据《中国产品全生命周期温室气体排放系数库》:

按渠道分摊:外送(餐盒 + 餐具 + 袋)远重于到店 / 自提。

第三层 · 配送层

参考国内外卖研究:每单平均 111.80 g CO2e,其中包装占 86%,配送段本身仅约 15.6 g(电动两轮为主)。 → 所以「到店自提」几乎能抹掉配送层,是减排里性价比最高的动作之一。

换算常数

一棵成熟树每年约吸收 21 kg CO2;汽油乘用车约 170 g CO2 / 公里。

⚠️ 免责声明:本账本为估算值,非麦当劳官方披露数据,仅用于横向对比与减排方向判断。不同地区、供应链、包装规格都会导致实际值偏差。

真实数据接入

真实历史订单来自 order-list,营养数据来自 list-nutrition-foods,积分账户来自 query-my-account。必须先有 Token。

  1. 申请麦当劳 MCP Token(参考 M-China/mcd-mcp-server)。
  2. 配置 Token(二选一):
# 方式 A:环境变量
export MCD_MCP_TOKEN="your_token"

# 方式 B:命令行直接传
PYTHONPATH=src python3 -m mccarbon account --token "your_token"
  1. 先验证 Token(推荐第一步):
PYTHONPATH=src python3 -m mccarbon account --token "your_token"

能打印出会员卡号 / 积分,说明 Token 有效;若报 401 则 Token 无效或已过期。

  1. 拉取真实订单并生成碳账本:
PYTHONPATH=src python3 -m mccarbon --live --html carbon-book.html --token "your_token"

命令说明

python3 -m mccarbon [report|demo|export|account] [选项]
子命令 作用 常用选项
report(默认) 生成碳账本 --html <PATH> --json <PATH> --start/--end --name --city --token --detail
demo 用离线示例数据一键演示 同 report
export 只导出归一化订单 JSON --json <PATH>
account 只读取并打印真实会员账号信息(验证 Token 用) --token

数据源优先级:--mock 强制离线;--live / --token / MCD_MCP_TOKEN 强制走真实;都不写则检测到 Token 就走真实,否则回退 mock。

项目结构

mccarbon/
├── src/mccarbon/
│   ├── factors.py         # 排放因子库(餐品/包装/配送)+ 食材归类
│   ├── carbon.py          # 三层碳核算引擎
│   ├── reduce.py          # 减排模拟器
│   ├── models.py          # Order / OrderItem 数据模型
│   ├── nutrition.py       # 官方营养表解析与餐品归类
│   ├── mcp_client.py      # 零依赖 MCP Streamable HTTP 客户端
│   ├── source.py          # MCP 数据源抽象与容错解析
│   ├── mock_data.py       # 2026 年全年示例订单
│   ├── report.py          # 单文件 HTML 碳账本生成
│   ├── render.py          # 终端文本碳账单
│   └── cli.py             # 命令行入口
├── tests/                 # 单元测试
├── examples/              # 演示产物
├── README.md              # 项目介绍(本文件)
├── USAGE.md               # 📖 面向使用者的完整使用指南
├── CONTEST_DECLARATION.md # 官方原版参赛声明,请勿改动
├── MCP_INTEGRATION.md     # MCP 接入说明
├── mcp-config.example.json
├── workbuddy.md           # WorkBuddy 专项奖励说明
├── skill/SKILL.md         # 在 WorkBuddy 里当对话式 Skill 用
├── requirements.txt       # 空文件:零第三方依赖
└── pyproject.toml

技术亮点

示例输出

见 examples/carbon-book.html,或直接跑 python3 -m mccarbon demo。

许可证

MIT License — 详见 LICENSE。

本项目为麦当劳程序员节创意开发大赛参赛作品,非麦当劳官方产品。碳足迹为估算值,不构成任何环保声明或专业建议;餐品、包装与供应状态以麦当劳官方渠道实时结果为准。

mccarbon (yeqv111/mccarbon)

Ищем в базе…

Что это такое?Личный калькулятор углеродного следа от заказов в McDonald's. Он получает вашу реальную историю заказов через MCP McDonald's, оценивает выбросы CO2 от еды, упаковки и доставки и создаёт единый HTML-отчёт «углеродная книга» с симулятором сокращения выбросов.
Это библиотека или инструмент командной строки?Это самостоятельный CLI на Python, который запускается как модуль (python3 -m mccarbon). Во время работы графического интерфейса нет — единственный видимый результат — самодостаточный файл carbon-book.html, который открывается в браузере.
Как попробовать без какой-либо настройки?Запустите команду demo, и вы сразу увидите результат со встроенными примерными данными за целый год заказов; аккаунт и токен не нужны. Для своих данных запустите подкоманду report после настройки действующего токена MCP.
Нужен ли мне токен MCP от McDonald's, чтобы пользоваться этим?Только если вы хотите использовать свою реальную историю заказов. Токен MCP McDonald's получают через M-China/mcd-mcp-server, и передают его через параметр --token или переменную окружения MCDMCPTOKEN; сам инструмент требует Python 3.9+ и не требует сторонних пакетов.
Насколько точны цифры углеродного следа?Это оценки, а не официальные данные McDonald's. Только для некоторых позиций меню в Великобритании есть опубликованные измеренные значения выбросов; большинство позиций китайского меню рассчитаны экстраполяцией по медианам категорий, поэтому реальные значения могут отличаться в зависимости от региона и цепочки поставок.
Как на самом деле рассчитывается углеродный след?Модель из трёх частей: еда (около 90% от общего итога, по измеренным данным из Великобритании или по оценкам на основе медиан категорий), упаковка (на основе китайской базы данных коэффициентов выбросов жизненного цикла для коробок, столовых приборов и пакетов) и доставка (на основе исследований выбросов домашней доставки еды).
Что предлагает симулятор сокращения выбросов?Он моделирует конкретные замены: красное мясо на белое, доставка на самовывоз, сокращение десертов вдвое или отказ от дополнительных позиций комбо-набора. Для каждой замены он показывает, сколько кг CO2e и какой процент от вашего общего следа она экономит.
Почему автор создал инструмент для углеродного следа, а не что-то другое?Конкурентный анализ всех 529 работ конкурса программистов фестиваля McDonald's показал, что ни одна не затронула экологический или углеродный аспект, хотя это соответствует собственной повестке McDonald's «Plan for Change / чистый ноль к 2050 году» и действительно полезно в повседневной жизни, а не является просто игрушкой.
Не запутывает ли учёт заказ комбо-наборов?Нет, инструмент автоматически разбивает реальные комбо-заказы (например, наборы «микс» или «купи картошку — получи картошку») на отдельные позиции, чтобы каждый компонент корректно учитывался в углеродном следе.
Какие есть похожие проекты?vibex, SoulMatrix, math-mastery, monolith, mai-shen-zai-ci, slimdeer, ttfx, Baize
Автор
yeqv111
Размер
0.7 MB
Звёзды
1.8K
Обновлён
КоммитOct 13
Возраст
1 мес
Коммиты · 90 дней