list_works
Retrieve and filter work items like issues and tickets from DevRev with options for type, state, dates, owners, and pagination.
Instructions
List all work items (issues, tickets) in DevRev
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | The type of works to list | |
| cursor | No | The cursor to use for pagination. If not provided, iteration begins from the first page. In the output you get next_cursor, use it and the correct mode to get the next or previous page. You can use these to loop through all the pages. | |
| applies_to_part | No | The part IDs of the works to list | |
| created_by | No | The user IDs of the creators of the works to list | |
| owned_by | No | The user IDs of the owners of the works to list | |
| state | No | The state names of the works to list | |
| modified_by | No | The user IDs of the users who modified the works to list | |
| sla_summary | No | Service Level Agreement summary filter on issues to list. | |
| sort_by | No | The field (and the order) to sort the works by, in the sequence of the array elements | |
| rev_orgs | No | The rev_org IDs of the customer rev_orgs filter on Issues and Tickets to list. Use this filter for issues and tickets that are related to a customer rev_org. | |
| target_close_date | No | ||
| target_start_date | No | The target start date range can only be used for issues. Do not use this field for tickets. | |
| actual_close_date | No | ||
| actual_start_date | No | The actual start date range can only be used for issues. Do not use this field for tickets. | |
| created_date | No | ||
| modified_date | No | ||
| sprint | No | Use this to filter on sprints. | |
| custom_fields | No | Use this to filter on the custom fields, which are not present in the input schema. | |
| subtype | No | Use this to filter on the subtype of the work items. |
Implementation Reference
- src/devrev_mcp/server.py:716-835 (handler)The handler logic for executing the 'list_works' tool. It processes input arguments to build a filter payload for the DevRev API 'works.list' endpoint and handles the response.
elif name == "list_works": payload = {} payload["issue"] = {} payload["ticket"] = {} type = arguments.get("type") if not type: raise ValueError("Missing type parameter") payload["type"] = type cursor = arguments.get("cursor") if cursor: payload["cursor"] = cursor["next_cursor"] payload["mode"] = cursor["mode"] applies_to_part = arguments.get("applies_to_part") if applies_to_part: payload["applies_to_part"] = applies_to_part created_by = arguments.get("created_by") if created_by: payload["created_by"] = created_by modified_by = arguments.get("modified_by") if modified_by: payload["modified_by"] = modified_by owned_by = arguments.get("owned_by") if owned_by: payload["owned_by"] = owned_by state = arguments.get("state") if state: payload["state"] = state custom_fields = arguments.get("custom_fields") if custom_fields: payload["custom_fields"] = {} for custom_field in custom_fields: payload["custom_fields"]["tnt__" + custom_field["name"]] = custom_field["value"] sla_summary = arguments.get("sla_summary") if sla_summary: payload["issue"]["sla_summary"] = {"target_time": {"type": "range", "after": sla_summary["after"], "before": sla_summary["before"]}} sort_by = arguments.get("sort_by") if sort_by: payload["sort_by"] = sort_by rev_orgs = arguments.get("rev_orgs") if rev_orgs and rev_orgs != []: if 'ticket' in type: payload["ticket"]["rev_org"] = rev_orgs if 'issue' in type: payload["issue"]["rev_orgs"] = rev_orgs subtype = arguments.get("subtype") if subtype: if 'ticket' in type: payload["ticket"]["subtype"] = subtype if 'issue' in type: payload["issue"]["subtype"] = subtype target_close_date = arguments.get("target_close_date") if target_close_date: payload["target_close_date"] = {"type": "range", "after": target_close_date["after"], "before": target_close_date["before"]} target_start_date = arguments.get("target_start_date") if target_start_date: if 'issue' in type: payload["issue"]["target_start_date"] = {"type": "range", "after": target_start_date["after"], "before": target_start_date["before"]} actual_close_date = arguments.get("actual_close_date") if actual_close_date: payload["actual_close_date"] = {"type": "range", "after": actual_close_date["after"], "before": actual_close_date["before"]} actual_start_date = arguments.get("actual_start_date") if actual_start_date: if 'issue' in type: payload["issue"]["actual_start_date"] = {"type": "range", "after": actual_start_date["after"], "before": actual_start_date["before"]} created_date = arguments.get("created_date") if created_date: payload["created_date"] = {"type": "range", "after": created_date["after"], "before": created_date["before"]} modified_date = arguments.get("modified_date") if modified_date: payload["modified_date"] = {"type": "range", "after": modified_date["after"], "before": modified_date["before"]} sprint = arguments.get("sprint") if sprint: payload["issue"]["sprint"] = sprint if payload["issue"] == {}: payload.pop("issue") if payload["ticket"] == {}: payload.pop("ticket") response = make_devrev_request( "works.list", payload ) if response.status_code != 200: error_text = response.text return [ types.TextContent( type="text", text=f"List works failed with status {response.status_code}: {error_text}" ) ] return [ types.TextContent( type="text", text=f"Works listed successfully: {response.json()}" ) ] - src/devrev_mcp/server.py:116-229 (schema)JSON Schema defining the input parameters for the 'list_works' tool, including various filters for listing work items.
types.Tool( name="list_works", description="List all work items (issues, tickets) in DevRev", inputSchema={ "type": "object", "properties": { "type": {"type": "array", "items": {"type": "string", "enum": ["issue", "ticket"]}, "description": "The type of works to list"}, "cursor": { "type": "object", "properties": { "next_cursor": {"type": "string", "description": "The cursor to use for pagination. If not provided, iteration begins from the first page."}, "mode": {"type": "string", "enum": ["after", "before"], "description": "The mode to iterate after the cursor or before the cursor ."}, }, "required": ["next_cursor", "mode"], "description": "The cursor to use for pagination. If not provided, iteration begins from the first page. In the output you get next_cursor, use it and the correct mode to get the next or previous page. You can use these to loop through all the pages." }, "applies_to_part": {"type": "array", "items": {"type": "string"}, "description": "The part IDs of the works to list"}, "created_by": {"type": "array", "items": {"type": "string"}, "description": "The user IDs of the creators of the works to list"}, "owned_by": {"type": "array", "items": {"type": "string"}, "description": "The user IDs of the owners of the works to list"}, "state": {"type": "array", "items": {"type": "string", "enum": ["open", "closed", "in_progress"]}, "description": "The state names of the works to list"}, "modified_by": {"type": "array", "items": {"type": "string"}, "description": "The user IDs of the users who modified the works to list"}, "sla_summary": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the SLA summary range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the SLA summary range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"], "description": "Service Level Agreement summary filter on issues to list." }, "sort_by": {"type": "array", "items": {"type": "string", "enum": ["target_start_date:asc", "target_start_date:desc", "target_close_date:asc", "target_close_date:desc", "actual_start_date:asc", "actual_start_date:desc", "actual_close_date:asc", "actual_close_date:desc", "created_date:asc", "created_date:desc"]}, "description": "The field (and the order) to sort the works by, in the sequence of the array elements"}, "rev_orgs": {"type": "array", "items": {"type": "string"}, "description": "The rev_org IDs of the customer rev_orgs filter on Issues and Tickets to list. Use this filter for issues and tickets that are related to a customer rev_org."}, "target_close_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the target close date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the target close date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "target_start_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the target start date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the target start date range, for example: 2025-06-03T00:00:00Z"}, }, "description": "The target start date range can only be used for issues. Do not use this field for tickets.", "required": ["after", "before"] }, "actual_close_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the actual close date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the actual close date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "actual_start_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the actual start date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the actual start date range, for example: 2025-06-03T00:00:00Z"}, }, "description": "The actual start date range can only be used for issues. Do not use this field for tickets.", "required": ["after", "before"] }, "created_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the created date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the created date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "modified_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the modified date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the modified date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "sprint": { "type": "array", "items": { "type": "string", "description": "The DevRev ID of the sprint to filter on. In DevRev a sprint is a vista group item. You will get these IDs from the response of get vista tool." }, "description": "Use this to filter on sprints." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string", "description": "The name of the custom field. All the characters in the name should be lowercase and words separated by underscores. For example: 'custom_field_name'"}, "value": {"type": "array", "items": {"type": "string"}, "description": "The value of the custom field"} }, "required": ["name", "value"] }, "description": "Use this to filter on the custom fields, which are not present in the input schema." }, "subtype": { "type": "array", "items": { "type": "string", "description": "The DevRev value of the subtype to filter on. Remember to always use the list_subtypes tool to check the correct DevRev values of subtypes." }, "description": "Use this to filter on the subtype of the work items." } }, "required": ["type"], }, ), - src/devrev_mcp/server.py:116-229 (registration)The tool is registered by being included in the list returned by the handle_list_tools() function, decorated with @server.list_tools().
types.Tool( name="list_works", description="List all work items (issues, tickets) in DevRev", inputSchema={ "type": "object", "properties": { "type": {"type": "array", "items": {"type": "string", "enum": ["issue", "ticket"]}, "description": "The type of works to list"}, "cursor": { "type": "object", "properties": { "next_cursor": {"type": "string", "description": "The cursor to use for pagination. If not provided, iteration begins from the first page."}, "mode": {"type": "string", "enum": ["after", "before"], "description": "The mode to iterate after the cursor or before the cursor ."}, }, "required": ["next_cursor", "mode"], "description": "The cursor to use for pagination. If not provided, iteration begins from the first page. In the output you get next_cursor, use it and the correct mode to get the next or previous page. You can use these to loop through all the pages." }, "applies_to_part": {"type": "array", "items": {"type": "string"}, "description": "The part IDs of the works to list"}, "created_by": {"type": "array", "items": {"type": "string"}, "description": "The user IDs of the creators of the works to list"}, "owned_by": {"type": "array", "items": {"type": "string"}, "description": "The user IDs of the owners of the works to list"}, "state": {"type": "array", "items": {"type": "string", "enum": ["open", "closed", "in_progress"]}, "description": "The state names of the works to list"}, "modified_by": {"type": "array", "items": {"type": "string"}, "description": "The user IDs of the users who modified the works to list"}, "sla_summary": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the SLA summary range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the SLA summary range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"], "description": "Service Level Agreement summary filter on issues to list." }, "sort_by": {"type": "array", "items": {"type": "string", "enum": ["target_start_date:asc", "target_start_date:desc", "target_close_date:asc", "target_close_date:desc", "actual_start_date:asc", "actual_start_date:desc", "actual_close_date:asc", "actual_close_date:desc", "created_date:asc", "created_date:desc"]}, "description": "The field (and the order) to sort the works by, in the sequence of the array elements"}, "rev_orgs": {"type": "array", "items": {"type": "string"}, "description": "The rev_org IDs of the customer rev_orgs filter on Issues and Tickets to list. Use this filter for issues and tickets that are related to a customer rev_org."}, "target_close_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the target close date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the target close date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "target_start_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the target start date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the target start date range, for example: 2025-06-03T00:00:00Z"}, }, "description": "The target start date range can only be used for issues. Do not use this field for tickets.", "required": ["after", "before"] }, "actual_close_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the actual close date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the actual close date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "actual_start_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the actual start date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the actual start date range, for example: 2025-06-03T00:00:00Z"}, }, "description": "The actual start date range can only be used for issues. Do not use this field for tickets.", "required": ["after", "before"] }, "created_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the created date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the created date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "modified_date": { "type": "object", "properties": { "after": {"type": "string", "description": "The start date of the modified date range, for example: 2025-06-03T00:00:00Z"}, "before": {"type": "string", "description": "The end date of the modified date range, for example: 2025-06-03T00:00:00Z"}, }, "required": ["after", "before"] }, "sprint": { "type": "array", "items": { "type": "string", "description": "The DevRev ID of the sprint to filter on. In DevRev a sprint is a vista group item. You will get these IDs from the response of get vista tool." }, "description": "Use this to filter on sprints." }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string", "description": "The name of the custom field. All the characters in the name should be lowercase and words separated by underscores. For example: 'custom_field_name'"}, "value": {"type": "array", "items": {"type": "string"}, "description": "The value of the custom field"} }, "required": ["name", "value"] }, "description": "Use this to filter on the custom fields, which are not present in the input schema." }, "subtype": { "type": "array", "items": { "type": "string", "description": "The DevRev value of the subtype to filter on. Remember to always use the list_subtypes tool to check the correct DevRev values of subtypes." }, "description": "Use this to filter on the subtype of the work items." } }, "required": ["type"], }, ), - src/devrev_mcp/utils.py:12-39 (helper)Utility function used by the handler to make authenticated POST requests to the DevRev API.
def make_devrev_request(endpoint: str, payload: Dict[str, Any]) -> requests.Response: """ Make an authenticated request to the DevRev API. Args: endpoint: The API endpoint path (e.g., "works.get" or "search.hybrid") payload: The JSON payload to send Returns: requests.Response object Raises: ValueError: If DEVREV_API_KEY environment variable is not set """ api_key = os.environ.get("DEVREV_API_KEY") if not api_key: raise ValueError("DEVREV_API_KEY environment variable is not set") headers = { "Authorization": f"{api_key}", "Content-Type": "application/json", } return requests.post( f"https://api.devrev.ai/{endpoint}", headers=headers, json=payload )