> ## 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.
# Facility Tools
> MCP tools for managing facilities — list, create, update, and inspect offices, factories, warehouses, and other operational sites
# Facility Tools
Facilities are the physical locations where your organization operates — offices, factories, warehouses, data centers, waste water treatment plants, etc. They are the anchor entity for most environmental data: energy invoices, waste records, and water consumption are all linked to a specific facility.
Facilities are the starting point for most queries. Call `list_facilities` first to discover facility IDs, then use those IDs with `list_invoices`, `list_wastes`, or `get_greenhouse_gas_emissions`.
## Read Operations
## `list_facilities`
List facilities for an organization with optional filters.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `organization_id` | string | No | default org | Organization UUID |
| `name` | string | No | — | Filter by name (partial match, case-insensitive) |
| `country` | string | No | — | ISO 3166-1 alpha-2 country code (e.g. `ES`, `DE`, `FR`) |
| `type` | string | No | — | Facility type: `office`, `factory`, `warehouse`, `store`, `data_center`, `waste_water_facilities`, `other` |
| `status` | string | No | — | Status filter: `active`, `archived` |
| `page` | integer | No | 1 | Page number |
| `size` | integer | No | 50 | Results per page |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Madrid Office",
"type": "office",
"country": "ES",
"address": "Calle Gran Vía 1, Madrid",
"status": "active",
"co2e": 1250.5,
"co2e_biomass": 0.0,
"logistic_factor": 0.8,
"categories": ["heat", "electricity", "water"],
"cups_list": ["ES0021000000000001AA"],
"facility_purpose_type": "facilities",
"created_at": "2024-11-24T10:30:00Z",
"updated_at": "2024-11-24T10:30:00Z",
"invoices_in_review_count": 2,
"categories_without_data": 0
}
],
"total": 12,
"page": 1,
"size": 50,
"pages": 1
}
```
**Key response fields:**
| Field | Description |
| -------------------------- | ----------------------------------------------------------------------- |
| `co2e` | Total CO₂e emissions in kg for this facility |
| `categories` | Configured consumption categories (e.g. `electricity`, `water`, `heat`) |
| `cups_list` | CUPS supply point codes (Spanish energy market) |
| `invoices_in_review_count` | Number of invoices pending review |
| `categories_without_data` | Categories with no invoices — indicates data gaps |
**Example prompts:**
```
"List all our active offices in Spain"
"Show me the factories in Germany"
"Which facilities do we have in France?"
"List archived facilities"
```
***
## `get_facility`
Get a single facility by ID with full details including address, categories, emission totals, and linked data such as waste water treatment configuration.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------- |
| `facility_id` | string | **Yes** | UUID of the facility |
| `organization_id` | string | No | Organization UUID (uses default if not set) |
Returns the same fields as `list_facilities` items, plus additional fields for waste water treatment facilities:
| Field | Description |
| ---------------- | ---------------------------------------------------------- |
| `water_type` | Water type of the waste water treatment line |
| `methane_burned` | Whether methane is burned at the facility |
| `wwt_line` | Waste water treatment line configuration (id + line\_code) |
| `sludge_line` | Sludge treatment line configuration |
| `wwd_line` | Water discharge line configuration |
**Example prompts:**
```
"Show me details for facility 550e8400-..."
"What categories are configured for our Madrid office?"
```
***
## Write Operations
### `create_facility`
Create a new facility in the organization. Returns the created facility with its assigned ID.
**Address or Country Required**: You must provide either an `address` (from which the country is geocoded automatically) or a `country` code. If both are provided, the geocoded country from the address takes precedence.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | -------------- | ----------- | ----------- | -------------------------------------------------------------------------------- |
| `name` | string | **Yes** | — | Facility name (e.g. `"Madrid Office"`, `"Barcelona Warehouse"`) |
| `type` | string | **Yes** | — | Facility type: `office`, `factory`, `warehouse`, `store`, `data_center`, `other` |
| `country` | string | Conditional | — | ISO country code (e.g. `ES`, `FR`). Required if `address` is not provided |
| `address` | string | Conditional | — | Street address. If provided, country is derived automatically |
| `logistic_factor` | number | No | 0.8 | Logistics allocation factor (0 to 1) |
| `categories` | array\[string] | No | — | Consumption categories: `electricity`, `heat`, `water`, `recharge` |
| `cups_list` | array\[string] | No | — | CUPS supply point codes (Spanish energy market) |
| `organization_id` | string | No | default org | Organization UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Madrid Office",
"type": "office",
"country": "ES",
"address": "Calle Gran Vía 1, Madrid",
"status": "active",
"co2e": null,
"logistic_factor": 0.8,
"categories": ["heat", "electricity", "water"],
"created_at": "2024-11-24T10:30:00Z"
}
```
**Example prompts:**
```
"Create a new office in Madrid called 'Madrid HQ'"
"Add a factory in Germany with address Industriestr. 5, Berlin"
"Set up a new warehouse in France tracking electricity and water"
```
**Common errors:**
| Error | Cause |
| --------------------------------------------- | ---------------------------------------------------- |
| 422: "Either address or country is required." | Neither `address` nor `country` was provided |
| 422: "Invalid address." | The address could not be geocoded to a valid country |
***
### `update_facility`
Update an existing facility. Only provided fields are changed — omitted fields remain unchanged.
**Archiving Side Effects**: Setting `status` to `archived` will also archive any linked logistic hub and deactivate associated supply contracts.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | -------------- | -------- | ----------- | ---------------------------------------------------------------- |
| `facility_id` | string | **Yes** | — | UUID of the facility to update. Use `list_facilities` to find it |
| `name` | string | No | — | New facility name |
| `type` | string | No | — | New facility type |
| `country` | string | No | — | New ISO country code |
| `address` | string | No | — | New street address |
| `status` | string | No | — | Set to `active` or `archived` |
| `logistic_factor` | number | No | — | New logistics factor (0 to 1) |
| `categories` | array\[string] | No | — | New consumption categories |
| `cups_list` | array\[string] | No | — | New CUPS codes |
| `organization_id` | string | No | default org | Organization UUID |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Madrid HQ (Renamed)",
"type": "office",
"country": "ES",
"status": "active",
"logistic_factor": 0.9,
"updated_at": "2024-12-01T14:00:00Z"
}
```
**Example prompts:**
```
"Rename the Madrid office to 'Madrid HQ'"
"Archive the old Barcelona warehouse"
"Update the logistic factor of our Berlin factory to 0.6"
"Add water tracking to the Madrid office categories"
```
***
## Workflows
### Querying facility data
1. **Discover facilities** — `list_facilities` to find by name, country, or type
2. **Inspect a facility** — `get_facility` for full details
3. **Query energy data** — `list_invoices` with the `facility_id` to see electricity, gas, water consumption
4. **Query waste data** — `list_wastes` with the `facility_id` for waste records and treatment methods
5. **Query emissions** — `get_greenhouse_gas_emissions` with the `facility_id` for validated emission totals
### Setting up a new facility
1. **Create the facility** — `create_facility` with name, type, and location
2. **Verify it was created** — `get_facility` to confirm details
3. **Upload energy data** — Use the API or CLI to upload invoices for the new facility
4. **Check emissions** — `get_greenhouse_gas_emissions` once invoices are processed
### Managing existing facilities
1. **Find the facility** — `list_facilities` with name or country filter
2. **Update details** — `update_facility` to rename, change address, or update categories
3. **Archive if needed** — `update_facility` with `status: "archived"` (cascades to linked resources)
## Related
REST API endpoint for facility creation
REST API endpoint for facility updates
Energy invoices linked to a facility
Waste records linked to a facility
Aggregated emissions by facility
Manage facilities from the command line