songconmaisaix31-design/mcpet

McPet – AI‑powered desktop companion

What it is

• A small desktop “pet” that lives on your screen and talks to you via an LLM (DeepSeek or ChatGPT). It shows the status of your AI‑agent sessions, local token usage, and can remind you to eat or drink coffee.
• It also integrates cheap‑food services: you can query McDonald’s coupons and Luckin Coffee menus, place (demo) orders and log nutrition.

Key capabilities

Capability	How you access it
Desktop companion	Drag, click, right‑click the pet; hide/show via tray.
Character & outfits	Switch between DeepSeek‑娘 and ChatGPT‑娘; apply “麦麦套装” or “炸薯条” skins.
Work‑session monitoring	Shows progress, waiting input, errors of any LLM session that writes logs the pet can read.
Token & balance view	Displays local token accounting, Orca cache, and DeepSeek balance with timestamps.
McDonald’s & Luckin Coffee	Search coupons, store info, real‑time pricing; confirm to generate a demo order or cancel it.
Nutrition log	Pull nutrition facts for a menu item, record how many servings you ate, view daily totals.
Timed reminders	Default reminders at 11:30 am (meal) and 15:00 pm (coffee); configurable via the Settings menu.

Installation paths

• Windows portable – Download the zip from the releases page, unzip, and double‑click Start-Pet.vbs. The bundle contains a pre‑built McPet.exe and its runtime, so no extra install is needed.
• Agent mode – For tools that already host an LLM session, download the Agent zip, install Python 3.10+ dependencies (pip install -r requirements‑agent.txt), run src.agent_install to get a server.command/server.args pair, and point your host’s MCP configuration to the mcpet service (STDIO transport).
• From source – Clone the repo, create a virtual environment, install requirements.txt, then run python -m src.main --desktop. The UI is built with PySide6 (Qt).

Typical workflow

1. Start the pet – either via the portable exe or python … --desktop.
2. Choose a character – right‑click → 角色与动作 → pick a skin.
3. Ask the pet – either click the bubble or speak to your LLM host: e.g. 用 McPet 看当前会话状态.
4. Check food deals – 今天有什么麦当劳优惠？ or 帮我查附近瑞幸，选一杯拿铁.
5. Log nutrition – after eating, say 查询巨无霸营养，我吃了 1.5 份.
6. Adjust reminders – via Settings or by voice: 饭点改成 12:15.

Configuration

• Tokens for McDonald’s and Luckin are stored in a local .env file. The repo ships a .env.trial with shared demo credentials, so you can try the query features without providing your own keys.
• All other settings (reminder times, chosen skin, UI preferences) are saved in the pet’s data directory and persist across runs.

Current status

• The released version is v0.1.0 (Python/Qt). A Tauri‑based native build and a custom “original” character are in early M0 development.
• Some advanced GIF‑based animations require you to import additional assets locally; the basic zip includes the core 15 animated actions.
• Order placement is a demo – the pet shows a summary and asks for confirmation, but you must complete payment in the official brand app.

Where to learn more

• Full user guide: docs/USER-GUIDE.md
• Quick start for release packages: docs/RELEASE-QUICKSTART.md
• Agent integration details: docs/AGENT-HOST.md & docs/AGENT-SKILL.md
• Issue tracker for bugs or feature requests.

---

McPet blends a playful desktop mascot with practical AI‑agent monitoring and everyday convenience services, targeting developers who keep LLMs running on their machines.