OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Preview or apply work package updates

bulk_update_work_packages

Preview and apply up to 50 work-package updates in one validated batch, with dry-run checks to catch errors before committing.

Instructions

Preview or apply up to 50 work-package updates, each with its own changes.

First call with dry_run=true (default). Review each before/after diff and validation error, then submit the same updates with dry_run=false and each preview's lock_version. Omitted fields remain untouched; null clears clearable fields; target_versions=[] clears version assignments. Status/type/priority accept names or ids, as in update_work_package.

All items are validated before any update. If any preflight fails, nothing is applied; correct those items or submit a valid subset. Execution is sequential and NOT atomic: concurrent edits can still conflict after validation. Each item reports its result; partial_failure is true when some apply and others fail. Item notes flag values OpenProject will ignore or ignored, such as story_points without Backlogs. An unknown outcome means a connection/server failure may have happened after committing: re-read that item before retrying. Writes are never automatically retried or rolled back. Never rerun successful items. Notifications use the same notify flag for the whole batch.

Input Schema

TableJSON Schema

Name	Required	Description
`notify`	No	Send notification emails when applying updates.
`dry_run`	No	Defaults to preview: validate and show changes without PATCH.
`updates`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`items`	Yes
`notes`	Yes
`total`	Yes
`applied`	Yes
`dry_run`	Yes
`partial_failure`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.3.3Oct 3, 2026

changedInput schema / properties / updates / items / properties / changes / properties / assignee / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / changes / properties / priority / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / changes / properties / responsible / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / updates / items / properties / changes / properties / sprint

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": "__unchanged__",
+  "description": "Numeric sprint id from list_sprints; null (or 'none') clears it."
+}

changedInput schema / properties / updates / items / properties / changes / properties / status / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / changes / properties / type / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / updates / items / properties / changes / properties / version / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

Changed3 schema fields changedv0.3.1Sep 23, 2026

addedInput schema / properties / updates / items / properties / changes / properties / remaining_hours

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / updates / items / properties / changes / properties / story_points

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / items / items / properties / notes

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Addedv0.3.0Sep 14, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: all-items-validated-first preflight, non-atomic sequential execution, concurrent-edit conflicts, partial_failure semantics, item notes for ignored values, batch-wide notify, and that writes are never auto-retried or rolled back. This is exactly the operational context an agent needs and the annotations alone would not supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the dry_run workflow, then layers validation, execution, and error semantics. It is long but every sentence carries distinct operational information with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, high-risk batch mutation with an output schema already covering return values, the description supplies the full operational picture: preflight, non-atomicity, partial failure, unknown-outcome handling, and field-clearing rules. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema coverage, the description adds crucial meaning the schema does not: omitted fields are untouched, null clears clearable fields, target_versions=[] clears version assignments, status/type/priority accept names or ids, and lock_version must be copied from the preview. These resolve the otherwise confusing __unchanged__ vs null defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (update), resource (work packages), batch scope (up to 50, each with its own changes), and the preview/apply duality in the first sentence. The bulk framing plus the reference to update_work_package for field conventions clearly separates it from the singular sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit two-step workflow: call with dry_run=true (the default), review diffs and validation errors, then resubmit with dry_run=false and each preview's lock_version. It also states the when-not ('Never rerun successful items', 'submit a valid subset') and how to recover from partial failure.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server