Polarion MCP Server

Instructions

<purpose>Discover and search work items (requirements, tasks, etc.) in a Polarion project</purpose>

<when_to_use>
- MAIN DISCOVERY TOOL: Use this to explore project contents
- When searching for specific topics (e.g., "HMI", "requirements")
- When you need to understand project scope and available work items
- BEFORE using get_polarion_work_item() for detailed info
</when_to_use>

<workflow_position>
STEP 1: After get_polarion_projects(), use this to explore project contents
STEP 2: Analyze results to identify relevant work items
STEP 3: Use get_polarion_work_item() for detailed information on specific items
OPTIONAL: Use get_polarion_document() if user provides specific space/document names
</workflow_position>

<parameters>
- project_id: Required. Get from get_polarion_projects() results
- limit: Number of items (default 10). Use 30-50 for comprehensive searches
- query: POWERFUL filter. Examples:
  * "HMI" - finds HMI-related items
  * "type:requirement" - only requirements
  * "HMI AND type:requirement" - HMI requirements
  * "title:system" - items with "system" in title
</parameters>

<examples>
- Finding HMI requirements: query="HMI AND type:requirement", limit=30
- Project overview: query="", limit=50
- Security items: query="security OR safety", limit=20
- All requirements: query="type:requirement", limit=100
</examples>

<output>
Minimal fields (id, title, type, description) - use get_polarion_work_item() for full details
Contains rich information including work item relationships and metadata
</output>

<critical_note>
This tool often contains all the information you need. Work items include:
- Requirements, specifications, tasks
- Relationships between items
- Project structure and organization
Check results thoroughly before seeking additional tools
</critical_note>

Implementation Reference

• polarion_mcp/server.py:202-266 (handler)

  MCP tool handler decorated with @mcp.tool(). Defines input schema via type hints and docstring. Delegates to PolarionClient.get_work_items() and formats JSON response with status, work_items list, and guidance.

  @mcp.tool()
  def get_polarion_work_items(project_id: str, limit: int = 10, query: str = "") -> str:
      """
      <purpose>Discover and search work items (requirements, tasks, etc.) in a Polarion project</purpose>
      
      <when_to_use>
      - MAIN DISCOVERY TOOL: Use this to explore project contents
      - When searching for specific topics (e.g., "HMI", "requirements")
      - When you need to understand project scope and available work items
      - BEFORE using get_polarion_work_item() for detailed info
      </when_to_use>
      
      <workflow_position>
      STEP 1: After get_polarion_projects(), use this to explore project contents
      STEP 2: Analyze results to identify relevant work items
      STEP 3: Use get_polarion_work_item() for detailed information on specific items
      OPTIONAL: Use get_polarion_document() if user provides specific space/document names
      </workflow_position>
      
      <parameters>
      - project_id: Required. Get from get_polarion_projects() results
      - limit: Number of items (default 10). Use 30-50 for comprehensive searches
      - query: POWERFUL filter. Examples:
        * "HMI" - finds HMI-related items
        * "type:requirement" - only requirements
        * "HMI AND type:requirement" - HMI requirements
        * "title:system" - items with "system" in title
      </parameters>
      
      <examples>
      - Finding HMI requirements: query="HMI AND type:requirement", limit=30
      - Project overview: query="", limit=50
      - Security items: query="security OR safety", limit=20
      - All requirements: query="type:requirement", limit=100
      </examples>
      
      <output>
      Minimal fields (id, title, type, description) - use get_polarion_work_item() for full details
      Contains rich information including work item relationships and metadata
      </output>
      
      <critical_note>
      This tool often contains all the information you need. Work items include:
      - Requirements, specifications, tasks
      - Relationships between items
      - Project structure and organization
      Check results thoroughly before seeking additional tools
      </critical_note>
      """
      logger.info(f"Fetching {limit} work items from project {project_id}")
      work_items = polarion_client.get_work_items(project_id, limit, query)
      if work_items:
          return json.dumps({
              "status": "success",
              "message": f"Successfully fetched {len(work_items)} work items from project {project_id}",
              "work_items": work_items,
              "count": len(work_items),
              "project_id": project_id,
              "next_steps": "Use get_polarion_work_item() for detailed info on specific items"
          }, indent=2)
      return json.dumps({
          "status": "error",
          "message": f"Failed to fetch work items from project {project_id}. Check token, project ID, or permissions."
      }, indent=2)

• polarion_mcp/client.py:190-210 (helper)

  Core helper method in PolarionClient class that performs the actual REST API GET request to Polarion's /workitems endpoint, handles authentication, parameters, response parsing, and error handling.

  def get_work_items(self, project_id: str, limit: int = 10, query: str = "") -> List[Dict]:
      """Fetch work items (minimal fields). Parameters: project_id, limit, optional query."""
      try:
          self._ensure_token()
          api_url = f"{POLARION_BASE_URL}/rest/v1/projects/{project_id}/workitems"
          params = {
              'fields[workitems]': WORK_ITEM_MIN_FIELDS,
              'page[size]': limit
          }
          if query:
              params['query'] = query
          response = self.session.get(api_url, params=params, headers=self._headers(), timeout=REQUEST_TIMEOUT_SECONDS)
          self._handle_api_response(response, f"fetch work items from project {project_id}")
          data = response.json()
          work_items = (data.get('data') or [])[:limit]
          logger.info(f"Fetched {len(work_items)} work items from {project_id}")
          return work_items
      except Exception as e:
          logger.error(f"Failed to fetch work items from {project_id}: {e}")
          return []