get_polarion_work_items
Search and discover work items like requirements and tasks in Polarion projects using filters to explore project scope and identify relevant items.
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>Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| project_id | Yes | ||
| query | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
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 []