OpenProject MCP Server

Instructions

Implementation Reference

• src/openproject_mcp/tools/work_packages.py:343-405 (handler)

  Core handler implementation that queries the OpenProject API for work packages with optional project filter, JSON filters, and pagination, then formats the results into a markdown list.
  async def list_work_packages( project_id: str | None = None, filters: str | None = None, page: int = 1, page_size: int = 20, ) -> str: """List work packages with optional filtering and pagination. Args: project_id: Optional project ID to filter work packages filters: Optional JSON filter string (e.g., '[{"status_id":{"operator":"=","values":["1"]}}]') page: Page number (default: 1) page_size: Items per page (default: 20) Returns: Formatted markdown string with work packages list """ client = OpenProjectClient() try: params: dict[str, Any] = { "pageSize": page_size, "offset": (page - 1) * page_size, } if filters: params["filters"] = filters if project_id: endpoint = f"projects/{project_id}/work_packages" title = f"Work Packages in Project '{project_id}'" else: endpoint = "work_packages" title = "All Work Packages" result = await client.get(endpoint, params=params) # Extract metadata total = result.get("total", 0) count = result.get("count", 0) # Get work packages work_packages = get_embedded_collection(result, "elements") # Format as markdown markdown = f"""# {title} **Total:** {total} | **Showing:** {count} | **Page:** {page} --- """ if not work_packages: markdown += "\n*No work packages found.*\n" else: for wp in work_packages: markdown += "\n" + _format_work_package_list_item(wp) + "\n" return markdown finally: await client.close()
• src/openproject_mcp/server.py:94-114 (registration)

  MCP tool registration via @mcp.tool() decorator on the entry-point function that delegates to the core implementation.
  @mcp.tool() async def list_work_packages( project_id: str | None = None, filters: str | None = None, page: int = 1, page_size: int = 20, ): """List work packages with optional filtering and pagination. Args: project_id: Optional project ID to filter work packages filters: Optional JSON filter string page: Page number (default: 1) page_size: Items per page (default: 20) """ return await work_packages.list_work_packages( project_id=project_id, filters=filters, page=page, page_size=page_size, )
• src/openproject_mcp/tools/work_packages.py:289-340 (helper)

  Supporting function that formats a single work package dictionary into a detailed markdown list item, extracting embedded entities and links.
  def _format_work_package_list_item(wp: dict[str, Any]) -> str: """Format a work package as a concise list item. Args: wp: Work package object from OpenProject API Returns: Formatted markdown string for list display """ wp_id = wp.get("id", "N/A") subject = wp.get("subject", "No subject") # Get embedded resources embedded = wp.get("_embedded", {}) links = wp.get("_links", {}) # Type type_obj = embedded.get("type", {}) type_name = type_obj.get("name", "N/A") # Status status_obj = embedded.get("status", {}) status_name = status_obj.get("name", "N/A") # Priority priority_obj = embedded.get("priority", {}) priority_name = priority_obj.get("name", "N/A") # Project project_obj = embedded.get("project", {}) project_name = project_obj.get("name", "N/A") # Assignee assignee_link = links.get("assignee", {}) assignee_name = assignee_link.get("title") if assignee_link.get("href") else "Unassigned" # Parent parent_link = links.get("parent", {}) parent_name = parent_link.get("title") if parent_link.get("href") else None # Due date due_date = wp.get("dueDate", "No due date") markdown = f"""### #{wp_id}: {subject} - **Type:** {type_name} | **Status:** {status_name} | **Priority:** {priority_name} - **Project:** {project_name} | **Assignee:** {assignee_name} - **Due Date:** {due_date}""" if parent_name: markdown += f" | **Parent:** {parent_name}" return markdown