OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List work package comments

list_work_package_comments

Read-onlyIdempotent

Read a work package's comment thread and field-change history, including authors, timestamps, internal flags, and from-to values, with paged results and full-entry lookup.

Instructions

Read the comment thread and change history of a work package.

Use this whenever the question is "what did people say about this ticket" or "what changed on it": it returns the full activity journal — comment entries (author, markdown text, internal flag, timestamps) and field-change entries whose details are parsed into {field, from, to} (for example {"field": "Status", "from": "New", "to": "In progress"}).

Returns the standard list envelope: items plus pagination{total,page,page_size,has_more} and notes.

Pitfalls. OpenProject's activities endpoint is unpaginated — this tool fetches the entire journal on every call and pages it here, so page/page_size cost the same upstream but keep the reply small. Entries are ordered oldest first, so ask for the last page to see the latest discussion. Comment text is cut at max_comment_chars and marked truncated: true; pass that entry's id back as activity_id to read it in full.

Cross-references: post a comment with add_work_package_comment; the work package itself (description, custom fields, watchers) comes from get_work_package; files referenced in a comment are listed by list_attachments.

Input Schema

Name	Required	Description
`id`	Yes	Work package id. Get it from search_work_packages, list_work_packages or get_work_package — never guess it.
`page`	No	1-based page number over the journal. Entries are oldest first, so the newest comments are on the LAST page.
`page_size`	No	Journal entries per page, 1-100. Keep it small: comments are long.
`activity_id`	No	Read exactly one journal entry, uncapped, instead of a page. The id comes from a previous call to this tool. Must belong to work package `id`.
`max_comment_chars`	No	Per-comment character cap, 50-50000. A cut comment comes back with truncated=true and comment_length; re-read it in full via activity_id.

Output Schema

Name	Required	Description	Default
`sums`	No
`items`	No
`notes`	No
`groups`	No
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed67 schema fields changedv0.4.0Oct 24, 2026

changedOutput schema / properties / groups / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A server-side group bucket, computed over the full filtered set.",
-      "properties": {
-        "count": {
-          "default": 0,
-          "description": "Records in this group across all pages.",
-          "type": "integer"
-        },
-        "sums": {
-          "anyOf": [
-            {
-              "additionalProperties": {
-                "type": "number"
-              },
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Per-group sums when show_sums was requested."
-        },
-        "value": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Group value, e.g. a status name."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "sums": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "number"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / groups / default
```
Removed value: -null
```

removedOutput schema / properties / groups / description

Removed value: -"Present only when group_by was requested."

removedOutput schema / properties / items / description
```
Removed value: -"The page of results."
```

removedOutput schema / properties / items / items / description

Removed value: -"One journal entry: a comment, a set of field changes, or both.\n\nOpenProject aggregates a comment and the edits saved with it into a single\njournal entry, so ``kind='comment'`` entries can still carry ``details``."

changedOutput schema / properties / items / items / properties / author / anyOf

Previous value: -[
-  {
-    "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"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / author / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / author / description
```
Removed value: -"User who wrote the entry."
```

removedOutput schema / properties / items / items / properties / comment / anyOf

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

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

removedOutput schema / properties / items / items / properties / comment / description

Removed value: -"Comment body as markdown (raw); html is dropped. Cut to max_comment_chars when 'truncated' is true."

addedOutput schema / properties / items / items / properties / comment / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / comment_length / anyOf

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

removedOutput schema / properties / items / items / properties / comment_length / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / comment_length / description
```
Removed value: -"Character length of the untruncated comment; set only when truncated."
```
addedOutput schema / properties / items / items / properties / comment_length / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / created_at / anyOf

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

removedOutput schema / properties / items / items / properties / created_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / created_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / items / items / properties / created_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / details / description

Removed value: -"Field changes recorded with this entry; always a list, empty for a comment-only entry."

removedOutput schema / properties / items / items / properties / details / items / description
```
Removed value: -"One field change inside a journal entry, parsed into its parts."
```
removedOutput schema / properties / items / items / properties / details / items / properties / field / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / details / items / properties / field / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / details / items / properties / field / description
```
Removed value: -"Changed field as OpenProject labels it, e.g. 'Status', 'Start date'."
```
addedOutput schema / properties / items / items / properties / details / items / properties / field / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / details / items / properties / from / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / details / items / properties / from / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / details / items / properties / from / description
```
Removed value: -"Previous value; null when the field was set for the first time."
```
addedOutput schema / properties / items / items / properties / details / items / properties / from / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / details / items / properties / text / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / details / items / properties / text / default
```
Removed value: -null
```

removedOutput schema / properties / items / items / properties / details / items / properties / text / description

Removed value: -"The change as OpenProject phrases it, kept verbatim for anything the parser could not split (attachment adds, diff-only notes)."

addedOutput schema / properties / items / items / properties / details / items / properties / text / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / details / items / properties / to / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / details / items / properties / to / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / details / items / properties / to / description
```
Removed value: -"New value; null when the field was cleared."
```
addedOutput schema / properties / items / items / properties / details / items / properties / to / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / id / anyOf

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

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

removedOutput schema / properties / items / items / properties / id / description

Removed value: -"Activity id. Pass it back as list_work_package_comments(activity_id=...) to read a truncated comment in full."

addedOutput schema / properties / items / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / internal / default
```
Removed value: -false
```

removedOutput schema / properties / items / items / properties / internal / description

Removed value: -"True for internal (project-member-only) comments; OpenProject >= 16."

removedOutput schema / properties / items / items / properties / kind / description

Removed value: -"'comment' when the entry carries comment text, 'field_change' otherwise."

removedOutput schema / properties / items / items / properties / truncated / default
```
Removed value: -false
```
removedOutput schema / properties / items / items / properties / truncated / description
```
Removed value: -"True when the comment was cut to max_comment_chars."
```

removedOutput schema / properties / items / items / properties / updated_at / anyOf

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

removedOutput schema / properties / items / items / properties / updated_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / updated_at / description
```
Removed value: -"ISO 8601 UTC timestamp of the last edit."
```
addedOutput schema / properties / items / items / properties / updated_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / version / anyOf

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

removedOutput schema / properties / items / items / properties / version / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / version / description
```
Removed value: -"Journal version number of this entry within the work package."
```
addedOutput schema / properties / items / items / properties / version / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / work_package / anyOf

Previous value: -[
-  {
-    "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"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / work_package / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / work_package / description
```
Removed value: -"Work package the entry belongs to."
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation markers: capped aggregations, unavailable modules, …"

removedOutput schema / properties / pagination / description
```
Removed value: -"Total/page/page_size/has_more."
```
removedOutput schema / properties / pagination / properties / has_more / description
```
Removed value: -"True when further pages exist."
```
removedOutput schema / properties / pagination / properties / page / description
```
Removed value: -"1-based page number of this result."
```
removedOutput schema / properties / pagination / properties / page_size / description
```
Removed value: -"Records requested per page."
```
removedOutput schema / properties / pagination / properties / total / description
```
Removed value: -"Total matching records on the server."
```
removedOutput schema / properties / sums / default
```
Removed value: -null
```

removedOutput schema / properties / sums / description

Removed value: -"Present only when show_sums was requested."

First observedv0.1.0Aug 12, 2026

TDQS

A4.8/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive behavior, but the description adds substantial operational context: upstream is unpaginated, the full journal is fetched on every call, paging is applied locally, entries are oldest first, comment text is truncated by max_comment_chars, and truncated entries can be re-read via activity_id. The only minor gap is not explicitly stating authentication or permission requirements, but the rest is strong.

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?

The description is long but well-structured and front-loaded: purpose, use case, return shape, pitfalls, and cross-references are separated into clear paragraphs. Every sentence contributes operational value, especially the pitfalls and cross-reference sections.

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?

With an output schema present, the description does not need to explain return values exhaustively, but it still gives the envelope shape and highlights the parsed field-change structure. Annotations, schema, and description together cover everything needed to call the tool correctly, including the unpaginated upstream and truncation behavior.

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?

Schema coverage is 100%, so the baseline would be 3, but the description adds meaningful semantics beyond the schema: page/page_size cost the same upstream because the endpoint is unpaginated, newest comments are on the last page, activity_id reads one uncapped entry, and max_comment_chars truncation behavior is explained with the re-read path.

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 action and resource: reading a work package's comment thread and change history. It clearly distinguishes this from get_work_package, which covers description, custom fields, and watchers, and from add_work_package_comment.

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?

Explicitly says when to use it ('what did people say about this ticket' / 'what changed on it') and includes cross-references for posting comments, fetching the work package itself, and listing attachments. It also explains the ordering pitfall so the agent knows to request the last page for latest discussion.

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

Deploy Server