get_polarion_document

Instructions

<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>

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