get_polarion_work_item

Instructions

<purpose>Get detailed information about a specific work item</purpose>

<when_to_use>
- AFTER using get_polarion_work_items() to identify specific work items of interest
- When you need complete details about a requirement, task, or specification
- When you need full content, relationships, and metadata
- For deep analysis of specific work items
</when_to_use>

<workflow_position>
STEP 1: Use get_polarion_work_items() to discover and filter work items
STEP 2: Identify specific work_item_id from the results
STEP 3: Use this tool to get complete details
STEP 4: Analyze relationships and linked items if needed
</workflow_position>

<parameters>
- project_id: Required. Must match project from previous search
- work_item_id: Required. Get from get_polarion_work_items() results
- fields: "@basic" for essential info, "@all" for complete details including relationships
</parameters>

<examples>
- Detailed requirement analysis: fields="@all"
- Quick verification: fields="@basic"
- Understanding relationships: fields="@all" (includes linked items)
</examples>

<output>
Complete work item details including:
- Full description and content
- Relationships to other work items
- Metadata and status information
- Approval and review information
</output>

<note>
Use this tool sparingly - only when you need detailed information about specific items
identified through get_polarion_work_items() searches
</note>

Implementation Reference

• polarion_mcp/server.py:267-322 (handler)

  Handler function for the 'get_polarion_work_item' MCP tool. Includes @mcp.tool() decorator for registration, detailed parameter documentation as schema, execution logic calling the client helper, error handling, and JSON response formatting.

  @mcp.tool()
  def get_polarion_work_item(project_id: str, work_item_id: str, fields: str = "@basic") -> str:
      """
      <purpose>Get detailed information about a specific work item</purpose>
      
      <when_to_use>
      - AFTER using get_polarion_work_items() to identify specific work items of interest
      - When you need complete details about a requirement, task, or specification
      - When you need full content, relationships, and metadata
      - For deep analysis of specific work items
      </when_to_use>
      
      <workflow_position>
      STEP 1: Use get_polarion_work_items() to discover and filter work items
      STEP 2: Identify specific work_item_id from the results
      STEP 3: Use this tool to get complete details
      STEP 4: Analyze relationships and linked items if needed
      </workflow_position>
      
      <parameters>
      - project_id: Required. Must match project from previous search
      - work_item_id: Required. Get from get_polarion_work_items() results
      - fields: "@basic" for essential info, "@all" for complete details including relationships
      </parameters>
      
      <examples>
      - Detailed requirement analysis: fields="@all"
      - Quick verification: fields="@basic"
      - Understanding relationships: fields="@all" (includes linked items)
      </examples>
      
      <output>
      Complete work item details including:
      - Full description and content
      - Relationships to other work items
      - Metadata and status information
      - Approval and review information
      </output>
      
      <note>
      Use this tool sparingly - only when you need detailed information about specific items
      identified through get_polarion_work_items() searches
      </note>
      """
      logger.info(f"Fetching work item {work_item_id} from project {project_id}")
      work_item = polarion_client.get_work_item(project_id, work_item_id, fields)
      if work_item:
          return json.dumps({
              "status": "success",
              "message": f"Successfully fetched work item: {work_item_id} from project {project_id}",
              "work_item": work_item
          }, indent=2)
      return json.dumps({
          "status": "error",
          "message": f"Failed to fetch work item {work_item_id} from project {project_id}. Work item may not exist or access is denied."
      }, indent=2)

• polarion_mcp/client.py:211-227 (helper)

  Supporting utility in PolarionClient class that performs the actual HTTP REST API request to retrieve the specific work item data from Polarion server, handles authentication, errors, and returns the raw data used by the handler.

  def get_work_item(self, project_id: str, work_item_id: str, fields: str = "@basic") -> Optional[Dict]:
      """Fetch a specific work item by ID from Polarion REST API."""
      try:
          self._ensure_token()
          api_url = f"{POLARION_BASE_URL}/rest/v1/projects/{project_id}/workitems/{work_item_id}"
          params = {'fields[workitems]': fields}
          response = self.session.get(api_url, params=params, headers=self._headers(), timeout=REQUEST_TIMEOUT_SECONDS)
          if response.status_code == 404:
              logger.warning(f"Work item not found: {work_item_id} in project: {project_id}")
              return None
          self._handle_api_response(response, f"fetch work item {work_item_id} from project {project_id}")
          work_item_data = response.json()
          logger.info(f"Fetched work item: {work_item_id} from project: {project_id}")
          return work_item_data
      except Exception as e:
          logger.error(f"Failed to fetch work item {work_item_id} from project {project_id}: {e}")
          return None

• polarion_mcp/server.py:286-310 (schema)

  Input schema documentation within the tool's docstring, describing parameters, types, requirements, and usage examples.

  <parameters>
  - project_id: Required. Must match project from previous search
  - work_item_id: Required. Get from get_polarion_work_items() results
  - fields: "@basic" for essential info, "@all" for complete details including relationships
  </parameters>
  
  <examples>
  - Detailed requirement analysis: fields="@all"
  - Quick verification: fields="@basic"
  - Understanding relationships: fields="@all" (includes linked items)
  </examples>
  
  <output>
  Complete work item details including:
  - Full description and content
  - Relationships to other work items
  - Metadata and status information
  - Approval and review information
  </output>
  
  <note>
  Use this tool sparingly - only when you need detailed information about specific items
  identified through get_polarion_work_items() searches
  </note>
  """

• polarion_mcp/server.py:267-267 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool named 'get_polarion_work_item'.

  @mcp.tool()