OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Get work package schema

get_work_package_schema

Read-onlyIdempotent

Retrieve the required and writable fields, custom field keys, and allowed options for a project's work package type before creating or updating to avoid 422 errors.

Instructions

Show which fields a work package of this type accepts in this project.

Call it before create_work_package/update_work_package when you need the required fields, when you want a custom field's key or its allowed options, or after a 422 that named a field you do not recognise.

Returns required_fields (writable keys you must supply), fields — every core attribute with {key, name, type, required, writable, has_default, allowed_values} — and custom_fields with {key, name, type, required, writable, options}. allowed_values/options are {id, name} lists for status, category, version and list/user custom fields.

Pitfalls: key is the wire spelling (startDate, customField12) — that is what raw_filters and custom_fields writes use, though writes also accept the display name. A field with writable: false is computed by OpenProject; sending it is an error, not a no-op. allowed_values is null when the API only offers a lookup URL (assignee, project) — resolve those with search_principals or list_projects instead. Long option lists are capped at 50 with a marker in notes.

Ids for both parameters come from get_project_metadata; to read the values actually set on one work package use get_work_package.

Input Schema

Name	Required	Description
`refresh`	No	Bypass the cache after an administrator changed the type or its custom fields.
`type_id`	Yes	Numeric work-package type id from get_project_metadata(project_id=...).types — not the type name.
`project_id`	Yes	Numeric project id — this endpoint does not accept the string identifier. The schema is per project AND type: the same type carries different custom fields in another project.

Output Schema

Name	Required	Description	Default
`notes`	No
`fields`	No
`type_id`	Yes
`project_id`	Yes
`custom_fields`	No
`required_fields`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed50 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"Everything a create/update call needs to be valid."

removedOutput schema / properties / custom_fields / description

Removed value: -"Always a list; empty when the type has none."

removedOutput schema / properties / custom_fields / items / description

Removed value: -"Custom-field definition: the canonical custom-field read shape without a value."

removedOutput schema / properties / custom_fields / items / properties / key / description
```
Removed value: -"Wire key, e.g. 'customField12' — use it in raw_filters."
```

removedOutput schema / properties / custom_fields / items / properties / name / anyOf

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

removedOutput schema / properties / custom_fields / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / custom_fields / items / properties / name / description
```
Removed value: -"Display name, e.g. 'Severity'."
```
addedOutput schema / properties / custom_fields / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / custom_fields / items / properties / options / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "description": "A reference to another resource. Canonical output shape.",
-      "properties": {
-        "id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Resource id."
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Human-readable name."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": [
+            "integer",
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

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

removedOutput schema / properties / custom_fields / items / properties / options / description

Removed value: -"Allowed {id, name} options for list/user/version custom fields; null for free-text and numeric ones."

removedOutput schema / properties / custom_fields / items / properties / required / default
```
Removed value: -false
```
removedOutput schema / properties / custom_fields / items / properties / required / description
```
Removed value: -"Creation fails without it."
```

removedOutput schema / properties / custom_fields / items / properties / type / anyOf

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

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

removedOutput schema / properties / custom_fields / items / properties / type / description

Removed value: -"Normalized custom-field type: 'list', 'string', 'text', 'user', 'date', … — the same vocabulary get_work_package reports in custom_fields[].type."

addedOutput schema / properties / custom_fields / items / properties / type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / custom_fields / items / properties / writable / default
```
Removed value: -false
```
removedOutput schema / properties / custom_fields / items / properties / writable / description
```
Removed value: -"False means computed/read-only."
```

removedOutput schema / properties / fields / description

Removed value: -"Core attributes with type/required/writable."

removedOutput schema / properties / fields / items / description
```
Removed value: -"One attribute of a work-package schema."
```

changedOutput schema / properties / fields / items / properties / allowed_values / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "description": "A reference to another resource. Canonical output shape.",
-      "properties": {
-        "id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Resource id."
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Human-readable name."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": [
+            "integer",
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

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

removedOutput schema / properties / fields / items / properties / allowed_values / description

Removed value: -"Valid {id, name} choices when the schema inlines them (status, category, version); null when the API only offers a lookup URL."

removedOutput schema / properties / fields / items / properties / has_default / anyOf

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

removedOutput schema / properties / fields / items / properties / has_default / default
```
Removed value: -null
```
removedOutput schema / properties / fields / items / properties / has_default / description
```
Removed value: -"True when OpenProject fills it in for you."
```
addedOutput schema / properties / fields / items / properties / has_default / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```
removedOutput schema / properties / fields / items / properties / key / description
```
Removed value: -"Wire attribute name, e.g. 'subject', 'assignee', 'startDate'."
```

removedOutput schema / properties / fields / items / properties / name / anyOf

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

removedOutput schema / properties / fields / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / fields / items / properties / name / description
```
Removed value: -"Localized label shown in the UI."
```
addedOutput schema / properties / fields / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / fields / items / properties / required / default
```
Removed value: -false
```
removedOutput schema / properties / fields / items / properties / required / description
```
Removed value: -"Creation fails without it."
```

removedOutput schema / properties / fields / items / properties / type / anyOf

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

removedOutput schema / properties / fields / items / properties / type / default
```
Removed value: -null
```
removedOutput schema / properties / fields / items / properties / type / description
```
Removed value: -"Schema type, e.g. 'String', 'Formattable', 'User', '[]User'."
```
addedOutput schema / properties / fields / items / properties / type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / fields / items / properties / writable / default
```
Removed value: -false
```
removedOutput schema / properties / fields / items / properties / writable / description
```
Removed value: -"False means read-only; do not send it."
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation notes, e.g. capped allowed-value lists."

removedOutput schema / properties / project_id / anyOf

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

removedOutput schema / properties / project_id / description
```
Removed value: -"Project the schema was requested for."
```
addedOutput schema / properties / project_id / type
```
Added value: +[
+  "integer",
+  "string"
+]
```

removedOutput schema / properties / required_fields / description

Removed value: -"Writable keys that must be supplied on create."

removedOutput schema / properties / type_id / anyOf

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

removedOutput schema / properties / type_id / description

Removed value: -"Work-package type the schema was requested for."

addedOutput schema / properties / type_id / type
```
Added value: +[
+  "integer",
+  "string"
+]
```

First observedv0.1.0Aug 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: writable:false fields are computed and sending them is an error rather than a no-op, allowed_values is null when the API only gives a lookup URL, and long option lists are capped at 50 with a note. These are exactly the failure modes an agent would otherwise hit.

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-loaded with purpose and trigger, then returns, then pitfalls — a good shape. The explicit enumeration of return fields is somewhat redundant with the existing output schema and pads length, but no sentence is filler.

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 read-only schema-introspection tool with full schema coverage, rich annotations and an output schema, this covers everything: when to call it, what it returns, what the keys mean on the wire, and which sibling to use when a value cannot be resolved here.

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?

Schema coverage is already 100%, so the baseline is 3, but the description adds provenance — both ids come from get_project_metadata — and reinforces that the schema is per project AND type. It does not, however, explain the refresh/cache parameter, which is left entirely to the schema.

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 and resource plus scope: 'Show which fields a work package of this type accepts in this project.' It is immediately distinguishable from get_work_package (which reads values) and from create/update_work_package, which it explicitly precedes.

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 concrete triggers: before create/update when you need required fields, when you want a custom field key or its allowed options, or after a 422 naming an unknown field. It also names the alternatives for cases this tool does not cover — get_work_package for actual values, search_principals/list_projects for lookup-URL fields, get_project_metadata for ids.

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

Deploy Server