Polarion MCP Server

Instructions

<purpose>Discover available Polarion projects for exploration</purpose>

<when_to_use>
- ALWAYS use this FIRST when starting Polarion exploration
- When you need to find the correct project_id for other operations
- When user asks about projects without specifying project name
- To verify authentication is working
</when_to_use>

<workflow_position>
STEP 1: Use this tool first to discover available projects
STEP 2: Choose relevant project_id from results  
STEP 3: Use get_polarion_work_items() to explore project contents
STEP 4: Use get_polarion_work_item() for detailed information
</workflow_position>

<parameters>
- limit: Number of projects to retrieve (default 10, increase for comprehensive view)
</parameters>

<examples>
- Finding automotive projects: Look for "AutoCar", "Vehicle", "Car" in project names
- Comprehensive discovery: Use limit=50 to see all available projects
</examples>

<output>List of projects with basic info - use project 'id' field for subsequent calls</output>

Implementation Reference

• polarion_mcp/server.py:121-164 (handler)

  Main tool handler for get_polarion_projects. Decorated with @mcp.tool(), handles input validation via docstring, calls client.get_projects, formats and returns JSON response.

  @mcp.tool()
  def get_polarion_projects(limit: int = 10) -> str:
      """
      <purpose>Discover available Polarion projects for exploration</purpose>
      
      <when_to_use>
      - ALWAYS use this FIRST when starting Polarion exploration
      - When you need to find the correct project_id for other operations
      - When user asks about projects without specifying project name
      - To verify authentication is working
      </when_to_use>
      
      <workflow_position>
      STEP 1: Use this tool first to discover available projects
      STEP 2: Choose relevant project_id from results  
      STEP 3: Use get_polarion_work_items() to explore project contents
      STEP 4: Use get_polarion_work_item() for detailed information
      </workflow_position>
      
      <parameters>
      - limit: Number of projects to retrieve (default 10, increase for comprehensive view)
      </parameters>
      
      <examples>
      - Finding automotive projects: Look for "AutoCar", "Vehicle", "Car" in project names
      - Comprehensive discovery: Use limit=50 to see all available projects
      </examples>
      
      <output>List of projects with basic info - use project 'id' field for subsequent calls</output>
      """
      logger.info(f"Fetching {limit} projects from Polarion")
      projects = polarion_client.get_projects(limit)
      if projects:
          return json.dumps({
              "status": "success",
              "message": f"Successfully fetched {len(projects)} projects",
              "projects": projects,
              "count": len(projects)
          }, indent=2)
      return json.dumps({
          "status": "error",
          "message": "Failed to fetch projects. Please check authentication and token."
      }, indent=2)

• polarion_mcp/client.py:153-170 (helper)

  Core helper method in PolarionClient that performs the actual REST API call to retrieve projects from Polarion, handles authentication, errors, and returns list of project dicts.

  def get_projects(self, limit: int = 10) -> List[Dict]:
      """Fetch projects from Polarion REST API (lightweight fields)."""
      try:
          self._ensure_token()
          api_url = f"{POLARION_BASE_URL}/rest/v1/projects"
          params = {
              'fields[projects]': '@basic',
              'page[size]': limit
          }
          response = self.session.get(api_url, params=params, headers=self._headers(), timeout=REQUEST_TIMEOUT_SECONDS)
          self._handle_api_response(response, "fetch projects")
          data = response.json()
          projects = (data.get('data') or [])[:limit]
          logger.info(f"Fetched {len(projects)} projects")
          return projects
      except Exception as e:
          logger.error(f"Failed to fetch projects: {e}")
          return []

• polarion_mcp/server.py:122-150 (schema)

  Docstring sections defining input parameters and output format, used by FastMCP for schema validation.

  def get_polarion_projects(limit: int = 10) -> str:
      """
      <purpose>Discover available Polarion projects for exploration</purpose>
      
      <when_to_use>
      - ALWAYS use this FIRST when starting Polarion exploration
      - When you need to find the correct project_id for other operations
      - When user asks about projects without specifying project name
      - To verify authentication is working
      </when_to_use>
      
      <workflow_position>
      STEP 1: Use this tool first to discover available projects
      STEP 2: Choose relevant project_id from results  
      STEP 3: Use get_polarion_work_items() to explore project contents
      STEP 4: Use get_polarion_work_item() for detailed information
      </workflow_position>
      
      <parameters>
      - limit: Number of projects to retrieve (default 10, increase for comprehensive view)
      </parameters>
      
      <examples>
      - Finding automotive projects: Look for "AutoCar", "Vehicle", "Car" in project names
      - Comprehensive discovery: Use limit=50 to see all available projects
      </examples>
      
      <output>List of projects with basic info - use project 'id' field for subsequent calls</output>
      """

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

  @mcp.tool() decorator registers the function as an MCP tool.

  @mcp.tool()

• polarion_mcp/server.py:13-13 (helper)

  Global instantiation of PolarionClient used by all tool handlers.

  polarion_client = PolarionClient()