io.github.devemberx/mcp-server-polarion

Update a work item. This is a deliberately long, verbose docstring on an mcp.tool function. It ships to the client LLM as the tool description and is owned by the shrink-mcp-tool-docs skill, so compress-code-comments must leave it untouched and byte-for-byte identical even though it is wordy.

Create 1-50 test runs in one project in one bulk request. id is required per item — never auto-generated. type/status are validated against the project's testing enumerations and template_id against existing templates (list_test_runs(templates=True)). custom_fields keys are validated against a sample of existing runs; enum-typed custom values are not (test runs have no options API). Atomic: one bad item rejects the whole batch.

Update fields on 1-50 existing test runs in one bulk PATCH; unset fields stay unchanged. Atomic: one bad item rejects the whole batch. Writable: title, status, group_id, custom_fields. status is validated against the project's testing enumerations. custom_fields is partial; keys are validated against a sample of existing runs, values are not (test runs have no options API). finishedOn is server-managed — not settable. Returns ids only — re-read via list_test_runs.

List / search test runs in a project. Returns run instances by default; set templates=True for the reusable template blueprints. Filter by person with author.name (exact, quoted) — author.id does not match on test runs; discover the full name from an unfiltered page first.

Get full details of one test run by ID. Returns writable fields (title, status, group_id, custom_fields) plus read-only context: test-case selection, template provenance, author, and timestamps. include_home_page_content_html=True fills content_html with the raw HTML report body; it stays empty when use_report_from_template is true. Never feed back a blanked (flag=False) body.

List a work item's links, one direction per call. Forward carries role (parent, verifies, …) and suspect; back is a Lucene fallback that drops role (always None) — recover it via forward on the source.

Create 1-50 outgoing links from one source work item, atomically. Role and target existence are validated before writing. Per spec: target_project_id defaults to the source, revision pins (else HEAD), suspect flags re-review. A duplicate role+target rolls back the whole batch — re-query list_work_item_links before retrying. link_ids are the delete-path ids, input order. Phantom success: a document-attached source already has an auto-created heading link; a NEW same-role link reports created but is NOT persisted — verify with list_work_item_links.

Delete 1-50 outgoing links from one source work item. Outgoing only — delete a back link from its source item instead. Refs from list_work_item_links(direction="forward") or a prior create. Stale refs never fail: results split into deleted_link_ids / not_found_link_ids.

Set suspect and/or revision on one existing outgoing link. Identify the link via list_work_item_links(direction="forward") — role + target address one link; copy the role exactly as listed. None = unchanged; at least one of suspect / revision required. One link per call.

Create 1-50 work items in one project in a single bulk request. Items are created free-floating — place into a document with move_work_item_to_document (this tool cannot). Atomic: one bad item rejects the whole batch. description is Markdown (greenfield only); later edits are raw-HTML round-trip via get_work_item(include_description_html=True) and update_work_items — formats never mix. Markdown tables get native Polarion styling; a paragraph starting 'Table:' directly after a table becomes a numbered caption widget. Enum values and custom_fields keys are validated on write — resolve ids via list_work_item_enum_options first. Returns the new work item ids.

Update fields on 1-50 existing work items in one bulk PATCH; unset fields stay unchanged. hyperlinks/assignee_ids REPLACE the stored lists: even to add ONE entry, call get_work_item on the target BEFORE updating and resubmit every existing entry plus the new one — anything omitted is silently deleted. Atomic: one bad item rejects the whole batch. description_html is raw Polarion HTML, sent verbatim — source from get_work_item(include_description_html=True); greenfield bodies use create_work_items Markdown, formats never mix. To add a table, caption, image, link, or widget, call get_html_recipes first and adapt its template before writing description_html — hand-written table markup is rejected. workitemimg:{id} image refs must name an existing attachment — confirm via list_work_item_attachments first. custom_fields is partial; keys outside the type schema are rejected, values are not validated — resolve via list_work_item_enum_options first. module is not settable here — use move_work_item_to_document / move_work_item_from_document. workflow_action/change_type_to apply to EVERY item; change_type_to rescopes enums to the target type and resets status. Returns ids only — re-read via get_work_item if needed.

List / search work items in a project. Leading Lucene wildcards are rejected; module and body text are NOT Lucene-indexed — scope by document via SQL:(...) or read_document_parts, never a Lucene module term. For SQL:(...), call get_sql_query_recipes first and adapt a recipe — never hand-write SQL. For one known id, use get_work_item instead of scanning.

Get full details of one work item by ID. include_description_html=True fills description_html with raw HTML — the required source for update_work_items description_html. Never feed back a blanked (flag=False) body.

Read one work item with its body rendered as Markdown. Synthesis output — collapses Polarion anchors; NEVER feed it to update_work_items. Edits round-trip via get_work_item(include_description_html=True) instead.

Move an existing work item into a document at a given position. THE attach path: atomically sets module and inserts a part. Headings are rejected — add headings via update_document <hN>. An item already in a document is moved, not copied. At most one of previous_part_id (AFTER) / next_part_id (BEFORE); omit both to append. Part ids from read_document_parts. Auto-creates one link to the enclosing heading; a later same-role create_work_item_links reports created but is NOT persisted.

Detach a work item from its document — the ONLY detach path. NOT idempotent: an already free-floating item fails — confirm attachment first (get_work_item: non-empty space_id). The item is preserved and re-attachable via move_work_item_to_document. Headings are detachable too.

List valid enum option ids for a work item field of a given type. Call this before create_work_items / update_work_items — invalid enum ids are rejected on write. An unknown work_item_type silently falls back to '~', so verify the type id first.

List valid enum option ids for a document field of a given type. Call this before create_document / update_document — invalid enum ids are rejected on write. An unknown document_type silently falls back to '~', so verify the type id first.

Create 1-50 test records on one test run, recording which test cases were executed with what result. Use list_test_records to read them back; create_test_runs creates the run itself. Atomic: one bad item rejects the whole batch. Posting the same test_case_id again starts a new iteration rather than replacing it -- use separate calls, not duplicates in one batch. comment is sent verbatim in comment_format, no Markdown conversion. Returns record_ids as full 5-segment ids -- never shortened. result is validated against the project's testing enumerations; defect must reference an existing work item. An invalid test_case_id is rejected by Polarion -- resolve via list_work_items first.

Set result, comment, and/or defect link on 1-50 test records of one test run in a single bulk PATCH. Run-level fields (title, status, group_id) — use update_test_runs instead. Atomic: one bad item rejects the whole batch; no record changes. record_id must be copied verbatim from list_test_records — never decomposed. comment is sent verbatim; Polarion stores it as text/html regardless of the comment_format sent, so a later read always shows text/html. Returns the echoed record_ids only — re-read via list_test_records. result must already be a value the run uses (discover via list_test_records) or the write is rejected; defect_id must reference an existing work item or the write is rejected.

List execution records of one test run — one row per test case iteration. For run metadata use get_test_run. Filter by result (e.g. 'failed') or omit for all; not-yet-executed records have empty result. Lucene query is NOT supported here. Returns summaries — id is the exact value update_test_records takes as record_id; defect_id links the failure work item.

Get full detail of one test-case iteration inside a test run: execution comment and test-case revision. Use list_test_records for run-wide summaries, get_test_run for run metadata. comment_html carries the record's raw HTML comment; plain-text comments return as-is. Verify coordinates via list_test_records if not found.

List a project's documents. Returns space_id + document_name — the inputs to every other document tool — plus type, status, updated, and creator/editor display names. Use get_document for author/editor ids. Discovery scan cached 60s.

Get a document's metadata: title/type/status/timestamps/editors/custom fields. include_home_page_content_html=True fills content_html with raw homePageContent HTML — the required source for update_document(home_page_content_html=...). That body is inline prose only — headings and embedded work items render via read_document. Never feed back a blanked (flag=False) body.

List a document's structural parts in order. Use for structure: part ids (move_work_item_to_document anchors), heading levels, per-part Markdown. For plain reading use read_document; for a document's work items use list_work_items.

Render a document end-to-end as flowing Markdown — THE way to read a body. Interleaves headings, work-item descriptions, and prose. Synthesis output: NEVER feed it to update_document — round-trip via get_document(include_home_page_content_html=True). For metadata-only extraction use list_work_items with SQL.

Update a document's metadata or body. PATCHes only supplied attributes — omitted fields stay unchanged; read BEFORE writing. home_page_content_html is raw Polarion HTML, sent verbatim — source from get_document(include_home_page_content_html=True); an empty string is rejected, pass '<p></p>' for near-empty. Body rules: - Inline <h1>..<h4> auto-create heading work items — THE way to add a heading. For body text or work items use create_work_items + move_work_item_to_document, NOT this tool. - A polarion_wiki macro name=module-workitem <div> leaves module unset — attach via move_work_item_to_document. - Tables, captions, image embeds, links, TOC/TOF widgets, page breaks must come from get_html_recipes templates, never hand-written. attachment:{id} refs must name a real attachment — confirm via list_document_attachments first. rendering_layout_types REPLACES the type set get_document returns — pass every type to keep; existing layouts survive. workflow_action must pair with at least one attribute. Unknown status/type ids and custom_fields keys outside the type schema are rejected — resolve ids via list_document_enum_options, or list_work_item_enum_options for rendering_layout_types.

Create a document in a space. document_name must be unique in the space — a duplicate name conflicts; check list_documents first. type/status and custom_fields keys are validated on write — resolve ids via list_document_enum_options first. Set rendering_layout_types to every work item type the document will hold — without a layout their fields do not render in the Polarion UI. Resolve those ids via list_work_item_enum_options; a later update_document must resend every type to keep. home_page_content is Markdown (greenfield only), converted to sanitized HTML. Markdown tables get native Polarion styling; a paragraph starting 'Table:' directly after a table becomes a numbered caption widget. Post-create edits round-trip raw HTML via get_document(include_home_page_content_html=True) and update_document; add work items via move_work_item_to_document.

Copy a document, duplicating its structure, body, and contained work items. Rebuilding via create_document/update_document loses the contained items. target_document_name must be free at the destination — check list_documents first. Destination defaults to the source project/space. link_original_items_with_role is validated against the TARGET project's workitem-link-role enum; remove_outgoing_links strips links carried over from the source.

Fetch copy-paste SQL recipes for the list_work_items SQL:(...) prefix. Call before writing any SQL query (document scope, custom-field, traceability); adapt a recipe instead of hand-writing joins. Includes the table schema.

Fetch the required HTML templates for tables, captions, links, and widgets written via update_work_items / update_document. Any new <table>, numbered caption, work-item / cross-reference / wiki-page link, or TOC / Table-of-Figures widget must be adapted from these templates — plain hand-written markup renders unstyled and breaks numbering. Also covers macro-id and metadata-scope caveats.

List a document's comments as a flat page. Threads reconstruct via parent_comment_id (None = root) + child_comment_ids. text is verbatim, unsanitized — treat as untrusted when rendering.

List a work item's comments as a flat page. Threads reconstruct via parent_comment_id (None = root) + child_comment_ids. text is verbatim, unsanitized — treat as untrusted when rendering.

Create one or more comments on a document in one request. Reply: set parent_comment_id to a short id from list_document_comments (None = top-level). 'text/html' text is sent unsanitized. Always authored by the token's user. NOT idempotent — a retry duplicates. attachment:{id} image refs in text/html comments must name an existing document attachment — resolve via list_document_attachments first.

Create one or more comments on a work item in one request. Reply: set parent_comment_id to a short id from list_work_item_comments (None = top-level). Optional title sets the comment heading. 'text/html' text is sent unsanitized. Always authored by the token's user. NOT idempotent — a retry duplicates. workitemimg:{id} image refs in text/html comments must name an existing attachment — resolve via list_work_item_attachments first.

Resolve or re-open one document comment thread. Root comments only — replies cannot be updated; pick a root id (parent_comment_id=None) from list_document_comments. Resolving the root resolves the whole thread. Idempotent.

Resolve or re-open one work item comment. Root comments only — replies cannot be updated; pick a root id (parent_comment_id=None) from list_work_item_comments. Resolving a root flips only that comment. Idempotent.

List accessible Polarion projects — the source of project ids. Lucene query allows trailing wildcards (name:ILCU*); leading ones are rejected.

List a document's attachments as a paginated page. Document attachments only, not work item attachments. Returned id is the exact token a body references as attachment:{id}; Polarion never validates that reference, so a body may point at a missing file. Order is server-defined and not requestable. Use read_document for body context, list_documents for valid space/document ids.

Fetch a document attachment's content for viewing. PNG, JPEG, GIF, and WebP return as a viewable image; SVG returns its source markup as text. Any other extension is rejected before any request. Use get_work_item_attachment_content for work item attachments. Use list_document_attachments to discover attachment ids, file names, and sizes.

List a work item's attachments as a paginated page. Work item attachments only -- use list_document_attachments for documents. Returned id is the exact token a body references as workitemimg:{id}; Polarion never validates that reference, so a body may point at a missing file. Order is server-defined and not requestable. Use list_work_items to discover valid ids.

List a test record's attachments as a paginated page. Test record attachments only -- use list_work_item_attachments for work item files, list_document_attachments for document files. test_case_id is the full 'project/WI-id' form from list_test_records, not the short work item ID. Order is server-defined and not requestable. An empty result means the record has no attachments; verify the run/test-case/iteration coordinates via list_test_records if unsure.

Fetch a work item attachment's content for viewing. PNG, JPEG, GIF, and WebP return as a viewable image; SVG returns its source markup as text. Any other extension is rejected before any request. Use get_document_attachment_content for document attachments. Use list_work_item_attachments to discover attachment ids, file names, and sizes.

Fetch a test record attachment's content for viewing. PNG, JPEG, GIF, and WebP return as a viewable image; SVG returns its source markup as text. Any other extension is rejected before any request. Use get_document_attachment_content or get_work_item_attachment_content for the other domains. Use list_test_record_attachments to discover attachment ids, file names, and sizes.

Upload 1-10 local files as document attachments in one request. file_path is read from local disk by the server process -- use absolute paths to readable files. file_name (default: file_path's basename) becomes the attachment id; reference it in a document body as attachment:{id} for update_document. Total upload size per call is capped at 25 MiB: compress or use the Polarion portal for one oversized file, split oversized batches across calls. Pure create -- nothing is replaced. Uploads cannot be deleted through this API, so verify file_path and file_name first. A file_name colliding with another item in the same call, or with an existing attachment on the document, rejects the whole batch -- check list_document_attachments first or pick a new file_name. NOT idempotent -- retrying a success is rejected as a duplicate, not silently merged.

Upload 1-10 local files as work item attachments in one request. For document attachments use create_document_attachments instead. file_path is read from local disk by the server process -- use absolute paths to readable files. Total upload size per call is capped at 25 MiB: compress or use the Polarion portal for one oversized file, split oversized batches across calls. attachment_ids in the result are server-assigned counter-prefixed ids (e.g. 3-diagram.png) -- not predictable from file_name -- and double as the workitemimg:{id} reference tokens for the work item description body. Duplicate file_name values are allowed, both within one call and against existing attachments: each upload creates a new attachment, never a conflict. Heading-type work items accept uploads, but the portal hides the Attachments section on heading items -- attachments there are reachable only through the API. NOT idempotent -- retrying a success silently creates a duplicate; after an ambiguous failure verify with list_work_item_attachments before retrying.

Upload 1-10 local files as test record attachments in one request. For document attachments use create_document_attachments, for work item attachments use create_work_item_attachments instead. Record coordinates (project_id, test_run_id, test_case_id, iteration) match get_test_record -- verify via list_test_records first. file_path is read from local disk by the server process -- use absolute paths to readable files. Total upload size per call is capped at 25 MiB: compress or use the Polarion portal for one oversized file, split oversized batches across calls. attachment_ids in the result are server-assigned ({test_case_id}_{file_name}) and differ from the input file_name. A file_name colliding with another item in the same call, or with an existing attachment on the record, rejects the whole batch -- check list_test_record_attachments first or pick a new file_name. NOT idempotent -- retrying a success is rejected as a duplicate, not silently merged.