List comments attached to a Polarion document.

Flat page; reconstruct threads via parent_comment_id (None = top-level) and child_comment_ids. text is verbatim; HTML is NOT sanitized — treat as untrusted when rendering.

Create one or more comments on a Polarion document in a single request.

All post together (201 with new IDs). Reply by setting parent_comment_id to a short ID from list_document_comments (None = top-level). text_format 'text/html' sent as-is (no sanitization); omit author_id to use the token's user. NOT idempotent — retry duplicates.

Resolve or re-open a single document comment.

PATCHes {"resolved": <bool>} (only patchable attr). Root comments only: a reply 400s ("Resolved field can be set only for root comments") → RuntimeError, so filter first. Resolving the root resolves the thread. Idempotent.

List all documents in a Polarion project.

Returns space_id + document_name (other document tools accept these) plus the document type. First call per project runs a discovery scan cached 60s.

Get a document's metadata (and optionally its raw body source).

Returns title/type/status/custom fields. With include_homepage_content_html=True, content_html carries homePageContent as raw HTML — the round-trip shape for update_document. homePageContent is inline prose only (headings and embedded work items are separate); use read_document end-to-end. Feed content_html back only when the flag was True (False blanks it; "" rejected on write).

List valid enum options for a document field of the given document type.

Call before update_document to resolve a status / type / custom-enum value — Polarion does NOT validate on write (unknown ids persist as ghosts). Document fields only. Returns the FULL set; document_type='~' is type-agnostic, and an unknown type silently falls back to ~, so verify the type id first.

List the structural parts of a document in order.

Use to map a document's structure — part IDs (move_work_item_to_document), heading levels, body content; each workitem part carries its description as Markdown. For plain reading prefer read_document. To list a document's work items use list_work_items instead.

Render a Polarion document end-to-end as flowing Markdown.

Paginates read_document_parts and interleaves headings, work-item descriptions, and prose into one stream — the canonical way to read a body. Read-only synthesis: do NOT feed back to update_document (collapses ID anchors, orphans headings); use get_document(include_homepage_content_html=True) for round-trip. For metadata-only extraction prefer list_work_items SQL.

Update a Polarion document's metadata or body.

PATCHes only set attributes (omitted preserved); no follow-up GET — call get_document for refreshed state. home_page_content_html is the round-trip pair for get_document(include_homepage_content_html=True), verbatim, no sanitization (NEVER pass untrusted input). Empty string rejected (orphans headings); pass '<p></p>' for near-empty.

Body-write rules:

• Headings auto-create: inline <h1>..<h4> become heading work items with module / outline_number set; bare <hN>Title</hN> is safe.

• Anchorless blocks break parts: <h3>X</h3><p>Body</p> PATCHes 200 but the next read_document_parts returns HTTP 500. Every anchorless <p>/<ul>/<ol>/<table>/<div>/<blockquote>/<pre> needs a unique id= (tool raises ValueError before PATCH, on dry_run too). No auto-stamping here; for body text prefer create_work_items + move_work_item_to_document.

• No macro references: a polarion_wiki macro name=module-workitem <div> makes a part but leaves the work item's module unset (half attached) — attach via move_work_item_to_document.

Prefer workflow_action over raw status; it MUST pair with ≥1 attribute (empty PATCH 400s). Unknown status / type raise ValueError; a custom_fields key absent from the document type's sampled schema is rejected (a type with no populated customs blocks it).

Create a new Polarion document in a space.

First call list_documents and confirm module_name is unique in the space (a duplicate returns HTTP 409). Supply only enum ids from list_document_enum_options — unverified ids persist as ghosts. custom_fields keys are validated against the document type's existing schema; a key no document of that type uses is rejected.

Starts empty (or with optional home_page_content); add parts later via update_document / move_work_item_to_document. module_name is the persistent URL identifier.

home_page_content is Markdown → sanitized HTML; post-create round-trip is raw HTML via get_document(include_homepage_content_html=True) ↔ update_document. Each block element is stamped a unique id="polarion_mcp_N" (else the next read_document_parts 500s); <h1>..<h4> are skipped (rewritten to macro form on save).

List a work item's outgoing or incoming links.

One direction per call. Forward exposes role (parent, verifies, …) and suspect. Back falls back to a linkedWorkItems: Lucene query that drops the role, so back role is None — recover via forward on the source.

Create one or more outgoing links (1-50) from a single source work item.

All share the source and post atomically. Per spec target_project_id defaults to source; revision pins (else HEAD); suspect marks re-review. Guards both role (workitem-link-role) and target existence before POST (on dry_run too) — unguarded they store as ghost/dangling links.

link_ids are 5-segment composites in input order (delete path ids). POST is atomic: a 4xx (e.g. duplicate (role,target) → 409) rolls back the batch — re-query before retry. Raises on an id-count mismatch.

Phantom-success footgun: when the source is in a document, move_work_item_to_document already auto-created one link. A NEW same-role link returns 201 but is NOT persisted. Verify forward (source) + back (target); if missing, detach → create → re-attach.

Delete one or more outgoing links (1-50) from a single source work item.

Mirrors create_work_item_links. Only outgoing links removed (delete a back link on the other work item). Identify refs from a prior create or from list_work_item_links(direction="forward").

Polarion's delete is idempotent and silent (204 even for stale refs). To make no-ops visible the tool pre-reads existing links and splits into deleted_link_ids / not_found_link_ids (no-op reported, never raised). Pre-read is fail-closed (RuntimeError before any delete).

Update suspect / revision on one existing outgoing work item link.

Identify the link via list_work_item_links(direction="forward") (role + target address one link). suspect / revision tri-state: a value updates, None leaves unchanged — at least one required (all-None 400s). One link per call (no bulk PATCH). A role typo 404s.

Move a work item into a Polarion document at a specific position.

moveToDocument atomically sets module + outline_number and inserts a part — the ONLY supported attach path (macro-injection leaves module unset). Headings rejected (HTTP 400). Already-in-a-document items are moved, not copied; detach via move_work_item_from_document.

AT MOST one of previous_part_id (AFTER) / next_part_id (BEFORE); omit both to append. Discover part IDs via read_document_parts.

Side effect: auto-creates one outgoing link to the enclosing heading (project-config role); collides with a same-role create_work_item_links (phantom success). Removed on detach.

Detach a work item from its document, returning it to free-floating state.

Inverse of move_work_item_to_document. moveFromDocument clears module and removes the part — the ONLY detach path (PATCH on module rejected). The work item is preserved and re-attachable.

NOT idempotent: on an already free-floating item returns HTTP 400 (RuntimeError). Headings CAN be detached (become free-floating with space_id="" / outline_number="").

List Polarion projects the authenticated user can access.

Discover project IDs for other tools. Lucene allows trailing wildcards (name:ILCU*) but rejects leading ones (*foo*, HTTP 400).

Create one or more Polarion work items (1-50) in one request, same project.

Confirm every enum value (type / status / severity / custom enums) via list_work_item_enum_options first — unverified ids persist as ghosts that never match Lucene. custom_fields keys are validated against the type's existing schema; a key no item of that type uses is rejected, and a type with no populated customs blocks the write (nothing to validate against). hyperlinks[].role validated against hyperlink-role.

Atomic: guards + conversion + build run before the POST; one bad item rejects the whole batch (nothing created). Raises if the returned id count differs from submitted — re-query list_work_items first.

Items are free-floating; place in a document via move_work_item_to_document (direct module create lands in the recycle bin). description is Markdown → sanitized HTML; the post-create round-trip is raw HTML via get_work_item(include_description_html=True) ↔ update_work_item.

Update an existing Polarion work item.

PATCHes supplied fields, then GETs so current reflects the change. None / empty all mean leave unchanged — no clear path.

description_html is RAW Polarion HTML, verbatim, no sanitization (NEVER pass untrusted input); round-trip with get_work_item(include_description_html=True). Greenfield: use create_work_items Markdown — paths never mix.

hyperlinks / assignee_ids REPLACE (full list, not delta); each hyperlink role validated against hyperlink-role (before PATCH, on dry_run too). custom_fields partial; a key absent from the type's sampled schema is rejected (a type with no populated customs blocks it).

module NOT exposed — use move_work_item_to_document / move_work_item_from_document. Prefer workflow_action over raw status; workflow_action / change_type_to MUST pair with ≥1 body field (empty PATCH 400s). Unknown status / severity / resolution / priority / change_type_to raise ValueError listing valid options; with change_type_to set, status/severity/resolution scope to the target type.

List valid enum options for a work item field of the given type.

Call before create_work_items / update_work_item to resolve a type / status / severity / priority / custom-enum value — Polarion does NOT validate on write (unknown ids persist as ghosts). Work-item fields only. Returns the FULL set; work_item_type='~' is type-agnostic, and an unknown type silently falls back to ~, so verify the type id first.

Fetch copy-paste SQL recipes for the list_work_items SQL:(...) prefix.

Call this before writing a module-scoped, custom-field, or traceability SQL query, then adapt a recipe instead of hand-writing joins from memory. Returns the table schema plus parameterised recipes as one Markdown document; loaded on demand so it never occupies always-on context.

List and search work items in a Polarion project.

Lucene query (type:requirement, title:SRS*) or omit for all. Leading wildcards 400. module and body text are NOT indexed — use the SQL prefix for module scope, read_document_parts for body.

SQL prefix. A query starting with SQL:( runs native SQL for patterns Lucene can't express. Escape ' as '' (no bind params). C_DESCRIPTION LIKE does NOT match; LIKE is rejected inside EXISTS — keep it top-level via INNER JOIN. Before writing any SQL call get_sql_query_recipes and adapt a recipe — it holds the common patterns (document scope, custom-field, traceability); do not hand-write.

Get full details of a single Polarion work item.

With include_description_html=True, description_html carries the raw Polarion HTML body — the round-trip shape for update_work_item. Only feed it back when the flag was True (False blanks it; "" = unchanged).

Read a Polarion work item with its body rendered as Markdown.

Synthesis variant of get_work_item: same metadata plus description as Markdown. Read-only (collapses Polarion spans/anchors) — do NOT feed back to update_work_item; round-trip via the HTML pair instead.