Skip to main content
Glama
kar-thik

OpenProject CE MCP Server

by kar-thik
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Get project report data

get_project_report_data
Read-onlyIdempotent

Aggregate everything a status report needs about one project and one date window.

Instructions

Aggregate everything a status report needs about one project and one date window.

Use it for weekly reports, sprint reviews, standups and "what happened in June" — one call replaces a dozen filtered listings. It returns, for the window: created, updated and closed_updated work-package buckets (each {items, total, truncated, more_via} with compact rows), open_total plus open_by_status counts computed server-side over the whole open set, a time summary (total hours with per-activity and per-user breakdowns) and the project's membership roster.

Done/in-progress classification is safe here: every row carries is_closed, read from the status's own isClosed flag on this instance, so it works on translated and renamed workflows where matching status names would not. closed_updated means "currently closed and updated inside the window", not completed in that window. Completion dates are not established by these reads.

Pitfalls. Counts and row lists are different things: total is always the server's number, while items stops at an internal cap and then sets truncated and adds a notes entry — quote the count, not the row count. open_by_status covers the open set as it is now, not as it was during the window. updated includes the rows in closed_updated. Time visibility is permission-bound, so a total_hours of 0 can mean "not allowed to see" rather than "nobody logged time" — an unreadable time ledger and an unreadable roster each degrade into a notes entry instead of failing the call. Read notes before calling any number complete.

Cross-references: rendered reports are the weekly_report and daily_standup prompts, which run this same aggregation server-side; drill into a bucket with list_work_packages, into hours with list_time_entries, and into one row with get_work_package.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
to_dateYesLast day of the report window, ISO YYYY-MM-DD, inclusive.
from_dateYesFirst day of the report window, ISO YYYY-MM-DD, inclusive. Required and never inferred — 'this week' means different days to different people.
project_idYesNumeric project id or project identifier (the URL slug). Both come from list_projects; the identifier is what appears in /projects/<identifier>.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
timeYesTime logged against the project inside the window.
notesNoIn-band markers: which lists were capped, which sources degraded. Read them before quoting a number as complete.
rosterNoProject membership roster: who may act in the project and with which roles.
createdYesWork packages created inside the window (createdAt range filter).
projectNoThe project the report covers.
to_dateYesWindow end, ISO YYYY-MM-DD, inclusive.
updatedYesWork packages changed inside the window (updatedAt range filter). Includes the ones that were closed.
from_dateYesWindow start, ISO YYYY-MM-DD, inclusive.
open_totalNoOpen work packages in the project right now, server-reported.
closed_updatedYesWork packages currently closed and updated inside the window. This is not a completion-date filter; old closed tickets can be edited later.
open_by_statusNoServer-side groupBy=status counts over the whole open set, independent of paging. Never re-add these from rows.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.3.0
    • removedOutput schema / properties / closed
      Removed value: -{
-  "description": "Work packages in a closed status that changed inside the window — the 'done this week' set.",
-  "properties": {
-    "items": {
-      "description": "Items included (capped).",
-      "items": {
-        "description": "One work package inside a report window, compact enough to list hundreds of.",
-        "properties": {
-          "assignee": {
-            "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": "Assigned user or group; null when unassigned."
-          },
-          "created_at": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "description": "ISO 8601 UTC timestamp the work package was raised. A created_at whose date equals updated_at's is a row nothing has happened to since it was raised."
-          },
-          "due_date": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "description": "ISO date (YYYY-MM-DD); null when unset."
-          },
-          "id": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "description": "Work package id — the #1234 number get_work_package takes."
-          },
-          "is_closed": {
-            "anyOf": [
-              {
-                "type": "boolean"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "description": "True when this status carries the instance's isClosed flag. Null means the status was not in GET /statuses — treat it as unknown, never as open."
-          },
-          "status": {
-            "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": "Status as the instance names it."
-          },
-          "subject": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "description": "Subject line."
-          },
-          "type": {
-            "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": "Work package type (Task, Bug, …)."
-          },
-          "updated_at": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null,
-            "description": "ISO 8601 UTC timestamp."
-          }
-        },
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "more_via": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Tool call that returns the full list."
-    },
-    "total": {
-      "default": 0,
-      "description": "Total available items.",
-      "type": "integer"
-    },
-    "truncated": {
-      "default": false,
-      "description": "True when items were dropped.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}
    • addedOutput schema / properties / closed_updated
      Added value: +{
+  "description": "Work packages currently closed and updated inside the window. This is not a completion-date filter; old closed tickets can be edited later.",
+  "properties": {
+    "items": {
+      "description": "Items included (capped).",
+      "items": {
+        "description": "One work package inside a report window, compact enough to list hundreds of.",
+        "properties": {
+          "assignee": {
+            "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": "Assigned user or group; null when unassigned."
+          },
+          "created_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "ISO 8601 UTC timestamp the work package was raised. A created_at whose date equals updated_at's is a row nothing has happened to since it was raised."
+          },
+          "due_date": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "ISO date (YYYY-MM-DD); null when unset."
+          },
+          "id": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Work package id — the #1234 number get_work_package takes."
+          },
+          "is_closed": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "True when this status carries the instance's isClosed flag. Null means the status was not in GET /statuses — treat it as unknown, never as open."
+          },
+          "status": {
+            "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": "Status as the instance names it."
+          },
+          "subject": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Subject line."
+          },
+          "type": {
+            "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": "Work package type (Task, Bug, …)."
+          },
+          "updated_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "ISO 8601 UTC timestamp."
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "more_via": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Tool call that returns the full list."
+    },
+    "total": {
+      "default": 0,
+      "description": "Total available items.",
+      "type": "integer"
+    },
+    "truncated": {
+      "default": false,
+      "description": "True when items were dropped.",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}
    • changedOutput schema / required
      Previous value: -[
-  "from_date",
-  "to_date",
-  "created",
-  "updated",
-  "closed",
-  "time"
-]New value: +[
+  "from_date",
+  "to_date",
+  "created",
+  "updated",
+  "closed_updated",
+  "time"
+]
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare the safe read-only/idempotent profile, but the description goes far beyond: truncation semantics (total vs items cap), notes entries for degraded reads, permission-bound time visibility where 0 hours can mean 'not allowed', and open_by_status reflecting the current set rather than the window. This is unusually rich behavioral disclosure.

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 purpose followed by labeled 'Pitfalls' and 'Cross-references' sections; every sentence carries non-redundant information. It is on the long side overall, but the structure keeps it scannable and little reads as 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 multi-bucket aggregation tool with permission caveats, the description covers outcome shape, failure-degradation behavior, classification semantics, and drill-down paths. Even though an output schema exists, the semantic traps (is_closed, closed_updated, notes) are exactly what an agent needs to interpret results correctly.

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

Parameters3/5

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

Schema coverage is 100%, so all three parameters are already documented in the input schema (including the from_date 'never inferred' note). The description adds semantic framing around the 'window' concept but no new per-parameter syntax or format detail beyond what the schema provides. Baseline 3.

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 up front: 'Aggregate everything a status report needs about one project and one date window.' It clearly distinguishes itself from the many list_* siblings by positioning as a one-call aggregation that replaces 'a dozen filtered listings.'

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 contexts (weekly reports, sprint reviews, standups, 'what happened in June') plus named alternatives for drilling down: list_work_packages for buckets, list_time_entries for hours, get_work_package for a single row.

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

Deploy Server

Other Tools