> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.
# PPWR Tools
> MCP tools for querying PPWR packaging compliance — units, BOM, substances, gaps, and compliance checks
# PPWR Tools
Query PPWR (Packaging and Packaging Waste Regulation) compliance data — packaging units, bill of materials, substance declarations, recyclability, gap analysis, and compliance evaluations. These tools support EU packaging regulation workflows.
PPWR tools cover the **packaging compliance** pillar. All endpoints use API v2 (`/v2/ppwr/`). Use `list_projects` first to find the project ID containing your packaging data.
## `list_packaging_units`
List packaging units for a PPWR project. Each unit represents a distinct packaging product being assessed for compliance.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `project_id` | string | **Yes** | — | Project UUID |
| `organization_id` | string | No | default org | Organization UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
{
"id": "a1b2c3d4-...",
"name": "Premium Wine Box",
"packaging_type": "primary",
"weight_grams": 450.0,
"volume_ml": 750.0,
"status": "in_progress",
"target_markets": ["ES", "FR", "DE"],
"is_food_contact": true,
"ean_code": "8412345678901",
"project_id": "proj-uuid-...",
"organization_id": "org-uuid-..."
}
]
```
**Key response fields:**
| Field | Description |
| ----------------- | ----------------------------------------------------------------------- |
| `packaging_type` | Type: `primary`, `secondary`, `tertiary`, or `transport` |
| `weight_grams` | Total packaging weight in grams |
| `status` | Assessment status: `draft`, `in_progress`, `compliant`, `non_compliant` |
| `target_markets` | ISO 3166-1 alpha-2 country codes for target markets |
| `is_food_contact` | Whether packaging is intended for food contact (Reg. EC 1935/2004) |
**Example prompts:**
```
"List all packaging units in this project"
"Which packaging units target the French market?"
"Show packaging units that are still in draft status"
```
***
## `get_packaging_unit`
Get full detail for a packaging unit — including bill of materials (BOM), substance declarations, and recyclability assessment.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | ------------------- |
| `packaging_unit_id` | string | **Yes** | — | Packaging unit UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "a1b2c3d4-...",
"name": "Premium Wine Box",
"packaging_type": "primary",
"weight_grams": 450.0,
"volume_ml": 750.0,
"status": "in_progress",
"target_markets": ["ES", "FR", "DE"],
"is_food_contact": true,
"bom_items": [
{
"id": "b2c3d4e5-...",
"component_name": "Outer carton",
"material_type": "paper_cardboard",
"weight_grams": 320.0,
"recycled_percentage": 85.0
}
],
"substances": [
{
"id": "c3d4e5f6-...",
"substance_name": "lead",
"concentration_ppm": 5.0,
"compliant": true
}
],
"recyclability": {
"grade": "B",
"assessed_by": "user-uuid-..."
}
}
```
**Example prompts:**
```
"Show the full detail for packaging unit X"
"What materials are in this packaging unit's BOM?"
"What substances have been declared?"
```
***
## `get_packaging_compliance`
Evaluate PPWR compliance for a single packaging unit. Returns pass/fail checks against specific PPWR articles, a timeline of upcoming deadlines, and overall compliance status.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | ------------------- |
| `packaging_unit_id` | string | **Yes** | — | Packaging unit UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"packaging_unit_id": "a1b2c3d4-...",
"packaging_unit_name": "Premium Wine Box",
"overall_status": "partial",
"checks": [
{
"code": "RECYCLED_CONTENT_MIN",
"requirement": "Minimum recycled content percentage",
"article": "Art. 7(1)",
"status": "pass",
"current_value": "85%",
"threshold": "65%",
"deadline": "2030-01-01"
},
{
"code": "HEAVY_METALS_LIMIT",
"requirement": "Sum of lead, cadmium, mercury, chromium VI below 100 ppm",
"article": "Art. 5(1)",
"status": "fail",
"current_value": "120 ppm",
"threshold": "100 ppm"
}
],
"timeline": [
{
"deadline": "2030-01-01",
"requirement": "Recycled content targets for paper packaging",
"status": "on_track",
"action": "Maintain current recycled content above 65%"
}
],
"compliant_count": 4,
"failed_count": 1,
"insufficient_count": 1
}
```
**Key response fields:**
| Field | Description |
| ------------------- | --------------------------------------------------------------- |
| `overall_status` | `compliant`, `non_compliant`, `partial`, or `insufficient_data` |
| `checks[].status` | Per-check result: `pass`, `fail`, or `insufficient_data` |
| `checks[].article` | PPWR article reference (e.g. "Art. 5(1)") |
| `timeline[].status` | Deadline tracking: `on_track`, `at_risk`, or `non_compliant` |
**Example prompts:**
```
"Is this packaging unit PPWR compliant?"
"Which compliance checks are failing?"
"What are the upcoming PPWR deadlines for this unit?"
```
***
## `get_project_compliance`
Evaluate PPWR compliance for all packaging units in a project. Returns a project-level summary with per-unit evaluations.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `project_id` | string | **Yes** | — | Project UUID |
| `organization_id` | string | No | default org | Organization UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"project_id": "proj-uuid-...",
"total_units": 8,
"compliant_units": 5,
"non_compliant_units": 1,
"partial_units": 1,
"insufficient_data_units": 1,
"unit_evaluations": [
{
"packaging_unit_id": "a1b2c3d4-...",
"packaging_unit_name": "Premium Wine Box",
"overall_status": "compliant",
"compliant_count": 6,
"failed_count": 0,
"insufficient_count": 0
}
]
}
```
**Example prompts:**
```
"How many packaging units are PPWR compliant?"
"Show the compliance status of all units in this project"
"Which units are non-compliant?"
```
***
## `get_packaging_gaps`
Analyze compliance gaps for a packaging unit using a traffic-light severity system. Each gap identifies a specific PPWR requirement that is not met, with the affected BOM components and required actions.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | ------------------- |
| `packaging_unit_id` | string | **Yes** | — | Packaging unit UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"packaging_unit_id": "a1b2c3d4-...",
"packaging_unit_name": "Premium Wine Box",
"overall_risk": "yellow",
"gaps": [
{
"code": "PFAS_NO_DECLARATION",
"severity": "red",
"category": "substances",
"article": "Art. 5(4)",
"description": "No PFAS declaration for food-contact packaging",
"deadline": "2026-12-31",
"action_required": "Obtain PFAS test certificate from supplier",
"affected_components": ["Inner liner"]
},
{
"code": "RECYCLED_CONTENT_MISSING",
"severity": "yellow",
"category": "recycled_content",
"article": "Art. 7(1)",
"description": "Recycled content not declared for 2 BOM items",
"action_required": "Request recycled content data from suppliers",
"affected_components": ["Outer carton", "Closure"]
}
],
"total_red": 1,
"total_yellow": 1,
"total_green": 0
}
```
**Key response fields:**
| Field | Description |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `overall_risk` | Worst-case severity across all gaps: `red` > `yellow` > `green` |
| `gaps[].severity` | Traffic-light risk: `red` (blocking), `yellow` (at risk), `green` (minor) |
| `gaps[].category` | Gap area: `substances`, `recycled_content`, `recyclability`, `material`, `labeling` |
| `gaps[].affected_components` | BOM item names affected by this gap |
**Example prompts:**
```
"What compliance gaps does this packaging unit have?"
"Are there any red-severity gaps?"
"What actions are required to close the gaps?"
```
***
## `get_ppwr_dashboard`
Get PPWR compliance dashboard metrics for a project — a high-level overview of packaging compliance health including substance safety, recycled content, recyclability grades, and supplier survey progress.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `project_id` | string | **Yes** | — | Project UUID |
| `organization_id` | string | No | default org | Organization UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"total_units": 12,
"avg_recycled_content": 72.5,
"substances_total": 24,
"substances_compliant": 20,
"units_by_status": {
"draft": 2,
"in_progress": 3,
"compliant": 5,
"non_compliant": 2
},
"grade_distribution": {
"A": 3,
"B": 4,
"C": 3,
"D": 2
},
"supplier_progress": {
"invited": 8,
"submitted": 5,
"validated": 3
}
}
```
**Key response fields:**
| Field | Description |
| ---------------------- | ---------------------------------------------------- |
| `avg_recycled_content` | Average recycled content percentage across all units |
| `substances_compliant` | Count of substance declarations that pass limits |
| `units_by_status` | Count of units by assessment status |
| `grade_distribution` | Count of units by recyclability grade (A–E) |
| `supplier_progress` | Supplier data collection funnel |
**Example prompts:**
```
"Show the PPWR dashboard for this project"
"What's the average recycled content across our packaging?"
"How many supplier surveys have been validated?"
```
## Workflow
1. **Find your project** — `list_projects` to find the project containing packaging data
2. **List packaging units** — `list_packaging_units` to see all units in the project
3. **Check dashboard** — `get_ppwr_dashboard` for a high-level compliance overview
4. **Dive into a unit** — `get_packaging_unit` for full detail (BOM, substances, recyclability)
5. **Check compliance** — `get_packaging_compliance` for pass/fail checks and deadlines
6. **Identify gaps** — `get_packaging_gaps` for traffic-light gap analysis with required actions
7. **Project-wide view** — `get_project_compliance` for a summary across all units
## Related
Find project IDs containing packaging data
CSRD/ESRS compliance and double materiality
GHG emissions for environmental impact
Organization hierarchy for group-level views