Polarion MCP Server

Instructions

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