CookHero

CookHero is a comprehensive, AI-powered dietary management platform that combines a recipe knowledge base, personalized meal planning, nutrition analytics, and multi-modal capabilities. It uses an MCP-driven architecture with Agent tools, Subagents, and MCP-style authentication to orchestrate planning, logging, and analysis workflows. Users interact with the system through a FastAPI backend and a frontend, enabling natural language queries, recipe discovery, meal planning, and nutrition tracking. The platform supports image uploads for dietary logging, automatic nutrition estimation, and real-time tool invocation visualization via SSE streams. To get started, deploy the backend and frontend, configure credentials, and then begin by asking for personalized meal plans, dietary recommendations, or to upload and analyze meals for caloric and macro tracking. The MCP framework allows you to extend with additional agents and tools, enabling custom workflows and integrations.

Prerequisites:

• Python 3.12+ and Node.js 18+
• Docker and Docker Compose (recommended for one-click deployment)

Option A: Docker one-click deployment (recommended)

1. Clone the repository and navigate into it:

git clone https://github.com/Decade-qiu/CookHero.git
cd CookHero

2. Configure environment variables:

cp .env.example .env
# Edit .env to fill necessary API keys and credentials

3. Start infrastructure with Docker Compose:

cd deployments
docker-compose up -d

This pulls and starts PostgreSQL, Redis, Milvus, MinIO, and etcd services.

4. Install Python dependencies and start the backend:

cd ..
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Initialize the database if needed
python -m scripts.howtocook_loader

# Start the backend API
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

5. Start the frontend:

cd frontend
npm install
npm run dev

6. Access the application:

• Frontend: http://localhost:5173
• Diet section: http://localhost:5173/diet
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Option B: Local development without Docker
1. Create and activate a virtual environment, install dependencies, and set up the database as described above.
2. Run the backend with uvicorn as shown in Step 4 of Option A.
3. Run the frontend with npm as shown in Step 5 of Option A.

Prerequisites: Ensure your environment has network access to required LLM, vision, and search services, and that the Milvus, Redis, and Postgres instances are reachable with the credentials provided in .env.

Notes and tips:

• Environment variables: Populate LLM_API_KEY, IMAGE_GENERATION_API_KEY, IMGBB_STORAGE_API_KEY, and other keys in the .env file. The MCP section in config.yml can be extended to enable/disable services like amap, image generation, and storage.
• If you modify MCP configurations, ensure the backend and any dependent services are restarted to pick up changes.
• For production, consider securing JWTs, tightening rate limits, and enabling structured auditing logs for SIEM compatibility.
• The frontend supports dynamic tool and subagent selection via the AgentHub; use this to tailor agent capabilities for specific tasks (recipe search, nutrition analysis, or meal planning).
• When using multimodal features, be mindful of image size limits (up to 4 images, each up to 10 MB) in relevant scenarios.
• If you encounter connection issues with Milvus/Redis/Postgres, verify network access, hostnames, and port mappings in docker-compose or config.yml, and ensure credentials are up to date.