Polarion MCP Server

Instructions

Implementation Reference

• polarion_mcp/server.py:324-388 (handler)

  MCP tool handler function for 'get_polarion_document'. Registers the tool with @mcp.tool() decorator and implements the core logic by calling PolarionClient.get_document(), formatting success/error JSON responses.
  @mcp.tool() def get_polarion_document(project_id: str, space_id: str, document_name: str, fields: str = "@basic") -> str: """ <purpose>Access specific structured documents within a Polarion space</purpose> <when_to_use> - When you need access to organized documents (specifications, manuals) - When user provides specific space and document names - When work items reference specific documents that need direct access - For accessing curated requirement collections in document format </when_to_use> <workflow_position> STEP 1: Use get_polarion_projects() to identify project STEP 2: Use get_polarion_work_items() to explore and potentially discover space references STEP 3: Use this tool when you have specific space_id and document_name ALTERNATIVE: Often get_polarion_work_items() provides equivalent or better information </workflow_position> <parameters> - project_id: Required. From get_polarion_projects() - space_id: Required. EXACT space name (user-provided or from work item references) - document_name: Required. Document name (e.g., "HMI", "System Requirements Specification") - fields: "@basic" for summary, "@all" for complete content </parameters> <examples> - HMI specifications: project_id="AutoCar", space_id="Master Specifications", document_name="HMI" - System requirements: project_id="AutoCar", space_id="Requirements", document_name="System" </examples> <critical_requirements> - space_id must be EXACT name (case-sensitive) - document_name is case-sensitive - Use quotes around space names with spaces (e.g., "Master Specifications") - Space names typically provided by user or discovered from work item exploration </critical_requirements> <output> Structured document content including organized requirements and specifications Often contains similar information to work items but in document format </output> <troubleshooting> If 404 error: Verify space_id and document_name spelling Common spaces: "Master Specifications", "Requirements", "Design Documents" Try exploring with get_polarion_work_items() first for context </troubleshooting> <note> Space names are not discoverable via API - they come from user knowledge or work item references </note> """ logger.info(f"Fetching document {document_name} from space {space_id} in project {project_id}") document = polarion_client.get_document(project_id, space_id, document_name, fields) if document: return json.dumps({ "status": "success", "message": f"Successfully fetched document: {document_name} from space {space_id} in project {project_id}", "document": document }, indent=2) return json.dumps({ "status": "error", "message": f"Failed to fetch document {document_name} from space {space_id} in project {project_id}. Document may not exist or access is denied." }, indent=2)
• polarion_mcp/client.py:229-245 (helper)

  Core helper method in PolarionClient that performs the actual REST API call to retrieve the Polarion document using the constructed endpoint and handles response/error cases.
  def get_document(self, project_id: str, space_id: str, document_name: str, fields: str = "@basic") -> Optional[Dict]: """Fetch a specific document from Polarion REST API.""" try: self._ensure_token() api_url = f"{POLARION_BASE_URL}/rest/v1/projects/{project_id}/spaces/{space_id}/documents/{document_name}" params = {'fields[documents]': fields} response = self.session.get(api_url, params=params, headers=self._headers(), timeout=REQUEST_TIMEOUT_SECONDS) if response.status_code == 404: logger.warning(f"Document not found: {document_name} in space: {space_id} of project: {project_id}") return None self._handle_api_response(response, f"fetch document {document_name} from space {space_id} in project {project_id}") document_data = response.json() logger.info(f"Fetched document: {document_name} from space: {space_id} in project: {project_id}") return document_data except Exception as e: logger.error(f"Failed to fetch document {document_name} from space {space_id} in project {project_id}: {e}") return None