Polarion MCP Server

Instructions

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