OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Preview or apply work package updates

bulk_update_work_packages

Preview or apply up to 50 work-package updates with per-item changes; validate all before applying and report each result.

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

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

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.

Changed8 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / properties / items / items / properties / changes / items / properties / after / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / changes / items / properties / before / default
```
Removed value: -null
```

changedOutput schema / properties / items / items / properties / error / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "description": "The body of the structured tool error.",
-    "properties": {
-      "error_identifier": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "OpenProject error identifier urn, when provided."
-      },
-      "hint": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "How to fix it (always English)."
-      },
-      "http_status": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Upstream HTTP status, if any."
-      },
-      "message": {
-        "description": "What went wrong, in plain language.",
-        "type": "string"
-      },
-      "type": {
-        "description": "Taxonomy member, e.g. 'validation_failed'.",
-        "type": "string"
-      },
-      "violations": {
-        "anyOf": [
-          {
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Field-level problems: [{attribute, message}]."
-      }
-    },
-    "required": [
-      "type",
-      "message"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "error_identifier": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "hint": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "http_status": {
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "message": {
+        "type": "string"
+      },
+      "type": {
+        "type": "string"
+      },
+      "violations": {
+        "anyOf": [
+          {
+            "items": {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "type",
+      "message"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / error / default
```
Removed value: -null
```

removedOutput schema / properties / items / items / properties / lock_version / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / lock_version / default
```
Removed value: -null
```
addedOutput schema / properties / items / items / properties / lock_version / type
```
Added value: +[
+  "integer",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / notes / default
```
Removed value: -null
```

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

A4.8/5.0

Behavior5/5

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

Goes far beyond annotations: preflight validation of all items before any write, sequential but non-atomic execution, partial_failure reporting, item notes for values OpenProject ignores (story_points without Backlogs), unknown-outcome semantics implying a possible post-commit server failure, no auto retry/rollback, and a warning never to rerun successful items. This is a materially richer disclosure than destructiveHint=false/idempotentHint=false provides.

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

Conciseness4/5

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

Front-loads the dry-run contract and every sentence carries operational content, including the subtle anti-retry warning. It is a dense single paragraph, though, which makes the review-then-apply procedure harder to scan than a short sequence would be.

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?

An output schema exists, so return values need not be explained, yet the description still covers result reporting (per-item results, partial_failure, item notes) and the lock_version round-trip. For a high-risk batch mutation this is complete enough for correct invocation.

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

Parameters4/5

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

Explains the semantics that matter most: omitted fields untouched, null clears clearable fields, target_versions=[] clears assignments, and notify applies to the whole batch. Schema coverage is 67%, and fields like custom_fields and percentage_done remain undocumented in both places, so it does not fully compensate for the gap.

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 (preview/apply), resource (work-package updates), and batch scope (up to 50, each with its own changes). This clearly distinguishes it from update_work_package, the single-item 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?

Prescribes an explicit two-phase workflow: dry_run=true first, review diffs and validation errors, then resubmit with dry_run=false and each preview's lock_version. It also states the recovery path (correct failing items or submit a valid subset) and says status/type/priority follow update_work_package semantics.

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

Deploy Server