OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Get work package detail

get_work_package

Read-onlyIdempotent

Retrieve a work package's full details by id: description, dates, custom fields, parent, progress, and lock version for safe edits.

Instructions

Read one work package in full: description, dates, custom fields, parent and progress.

This is the tool to call once a search or list has given you an id, and the only way to read a work package's description text. The lock_version in the result is what update_work_package needs for a safe concurrent edit.

Returns every core field, custom_fields in the canonical [{key, name, type, value, value_ids}] shape (only fields that have a value), an available map saying whether this work package exposes dev links, meetings or file links, and any requested includes.

Pitfalls: includes are capped at 20 — a truncated children list means you should call list_work_packages(parent_id=…) for the rest, which more_via spells out verbatim. A sub-resource that 403s or 404s (module off, no permission) degrades into a notes entry instead of failing the whole read.

For the comment thread use list_work_package_comments; for attachment bytes use download_attachment; for linked PRs and commits use get_work_package_git_activity.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes	Work package id — the number shown as #1234 in OpenProject. Comes from search_work_packages or list_work_packages. Instances on 17.x with semantic identifiers enabled also accept the semantic form ('PROJ-42', the row's display_id).
`include`	No	Extra sub-resources, fetched concurrently: 'relations', 'watchers', 'attachments', 'children', 'custom_actions'. Each is capped at 20 items and reports {truncated, total, more_via} when there are more. Ask only for what you need — every include is one more upstream request.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	Work package id.
`date`	No	Milestone date (ISO YYYY-MM-DD); null for non-milestones.
`type`	No	Work package type.
`notes`	No	Degradation notes for this result.
`author`	No	Creating user.
`parent`	No	Parent work package.
`sprint`	No	The sprint the work package is planned in; null when unassigned.
`status`	No	Status.
`project`	No	Owning project.
`subject`	No	Subject line.
`version`	No	Legacy alias: the sole target version, or null for zero/multiple.
`assignee`	No	Assigned user or group.
`category`	No	Category.
`children`	No	Present only when 'children' was requested.
`due_date`	No	ISO date (YYYY-MM-DD).
`priority`	No	Priority.
`watchers`	No	Present only when 'watchers' was requested.
`available`	No	Feature availability for this WP: dev links, meetings, files.
`relations`	No	Present only when 'relations' was requested.
`created_at`	No	ISO 8601 UTC timestamp.
`display_id`	No	Human-facing id as the instance renders it. Matches the numeric id unless the instance uses semantic identifiers (17.x, e.g. 'PROJ-42'); null when the instance predates it.
`start_date`	No	ISO date (YYYY-MM-DD).
`updated_at`	No	ISO 8601 UTC timestamp.
`attachments`	No	Present only when 'attachments' was requested.
`description`	No	Description as markdown (raw); html is dropped.
`responsible`	No	Accountable user.
`spent_hours`	No	Logged time in hours.
`lock_version`	No	Optimistic-locking version; pass to update_work_package.
`story_points`	No	Story points.
`custom_fields`	No	Always a list; empty when none are set.
`project_phase`	No	Project phase this work package sits in (16.1+, only when phases are active in the project and visible to this user); details via get_project_phase.
`custom_actions`	No	Present only when 'custom_actions' was requested.
`estimated_hours`	No	Estimate in hours.
`percentage_done`	No	Progress, 0-100.
`remaining_hours`	No	Remaining work in hours.
`target_versions`	No	All target versions; legacy instances yield zero or one.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.3Oct 3, 2026

addedOutput schema / properties / sprint

Added value: +{
+  "anyOf": [
+    {
+      "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": "null"
+    }
+  ],
+  "default": null,
+  "description": "The sprint the work package is planned in; null when unassigned."
+}

Changed2 schema fields changedv0.3.1Sep 23, 2026

addedOutput schema / properties / remaining_hours

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Remaining work in hours."
+}

addedOutput schema / properties / story_points

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Story points."
+}

Changed2 schema fields changedv0.3.0Sep 14, 2026

addedOutput schema / properties / target_versions

Added value: +{
+  "description": "All target versions; legacy instances yield zero or one.",
+  "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"
+}

changedOutput schema / properties / version / description

Previous value: -"Version / sprint."New value: +"Legacy alias: the sole target version, or null for zero/multiple."

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?

Goes far beyond annotations (readOnly/idempotent/openWorld): discloses the 20-include truncation cap with a recovery path, the graceful 403/404 degradation into a `notes` entry, the `lock_version` contract with update_work_package for safe edits, and the `value_ids` shape for custom fields. That is real behavioral context no schema or annotation 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-loaded with the primary purpose, then behavior, then pitfalls, then sibling routing. Dense but every sentence earns its place. Slightly long, but the content justifies most of the length.

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?

Given an output schema exists, the description correctly avoids restating return fields while still disclosing behavioral facets (includes cap, more_via, degradation, lock_version contract) an agent must know to call and use the tool correctly.

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 100% and both params are well documented there (semantic id form, include enum). Description adds value by explaining the concurrency semantics of the `lock_version` returned for `update_work_package` and reiterating the include cap/more_via pattern, but does not add parameter-level detail the schema lacks.

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 (Read) and resource (one work package) with scope details (description, dates, custom fields, parent, progress). Explicitly distinguishes itself from search/list ('the tool to call once a search or list has given you an id') and names sibling routing for its own return surface.

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?

Explicit when-to-use: 'once a search or list has given you an id.' Explicit routing to alternatives: 'For the comment thread use list_work_package_comments; for attachment bytes use download_attachment; for linked PRs and commits use get_work_package_git_activity.' No inference required.

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

Deploy Server