lucius-mcp 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

src/client/generated/docs/StatusControllerApi.md

@@ -0,0 +1,429 @@
+# src.client.generated.StatusControllerApi
+
+All URIs are relative to *http://localhost*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+[**create18**](StatusControllerApi.md#create18) | **POST** /api/status | Create a new status
+[**delete17**](StatusControllerApi.md#delete17) | **DELETE** /api/status/{id} | Delete status by id
+[**find_all15**](StatusControllerApi.md#find_all15) | **GET** /api/status | Find all statuses
+[**find_one14**](StatusControllerApi.md#find_one14) | **GET** /api/status/{id} | Find status by id
+[**patch17**](StatusControllerApi.md#patch17) | **PATCH** /api/status/{id} | Patch status
+[**suggest8**](StatusControllerApi.md#suggest8) | **GET** /api/status/suggest | Suggest statuses
+
+
+# **create18**
+> StatusDto create18(status_create_dto)
+
+Create a new status
+
+### Example
+
+
+```python
+import src.client.generated
+from src.client.generated.models.status_create_dto import StatusCreateDto
+from src.client.generated.models.status_dto import StatusDto
+from src.client.generated.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost
+# See configuration.py for a list of all supported configuration parameters.
+configuration = src.client.generated.Configuration(
+    host = "http://localhost"
+)
+
+
+# Enter a context with an instance of the API client
+async with src.client.generated.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = src.client.generated.StatusControllerApi(api_client)
+    status_create_dto = src.client.generated.StatusCreateDto() # StatusCreateDto | 
+
+    try:
+        # Create a new status
+        api_response = await api_instance.create18(status_create_dto)
+        print("The response of StatusControllerApi->create18:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling StatusControllerApi->create18: %s\n" % e)
+```
+
+
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **status_create_dto** | [**StatusCreateDto**](StatusCreateDto.md)|  | 
+
+### Return type
+
+[**StatusDto**](StatusDto.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: application/json
+ - **Accept**: */*
+
+### HTTP response details
+
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**200** | OK |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+# **delete17**
+> delete17(id)
+
+Delete status by id
+
+### Example
+
+
+```python
+import src.client.generated
+from src.client.generated.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost
+# See configuration.py for a list of all supported configuration parameters.
+configuration = src.client.generated.Configuration(
+    host = "http://localhost"
+)
+
+
+# Enter a context with an instance of the API client
+async with src.client.generated.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = src.client.generated.StatusControllerApi(api_client)
+    id = 56 # int | 
+
+    try:
+        # Delete status by id
+        await api_instance.delete17(id)
+    except Exception as e:
+        print("Exception when calling StatusControllerApi->delete17: %s\n" % e)
+```
+
+
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **id** | **int**|  | 
+
+### Return type
+
+void (empty response body)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: Not defined
+ - **Accept**: Not defined
+
+### HTTP response details
+
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**204** | No Content |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+# **find_all15**
+> PageStatusDto find_all15(workflow_id=workflow_id, page=page, size=size, sort=sort)
+
+Find all statuses
+
+### Example
+
+
+```python
+import src.client.generated
+from src.client.generated.models.page_status_dto import PageStatusDto
+from src.client.generated.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost
+# See configuration.py for a list of all supported configuration parameters.
+configuration = src.client.generated.Configuration(
+    host = "http://localhost"
+)
+
+
+# Enter a context with an instance of the API client
+async with src.client.generated.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = src.client.generated.StatusControllerApi(api_client)
+    workflow_id = 56 # int |  (optional)
+    page = 0 # int | Zero-based page index (0..N) (optional) (default to 0)
+    size = 10 # int | The size of the page to be returned (optional) (default to 10)
+    sort = [name,ASC] # List[str] | Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported. (optional) (default to [name,ASC])
+
+    try:
+        # Find all statuses
+        api_response = await api_instance.find_all15(workflow_id=workflow_id, page=page, size=size, sort=sort)
+        print("The response of StatusControllerApi->find_all15:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling StatusControllerApi->find_all15: %s\n" % e)
+```
+
+
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **workflow_id** | **int**|  | [optional] 
+ **page** | **int**| Zero-based page index (0..N) | [optional] [default to 0]
+ **size** | **int**| The size of the page to be returned | [optional] [default to 10]
+ **sort** | [**List[str]**](str.md)| Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported. | [optional] [default to [name,ASC]]
+
+### Return type
+
+[**PageStatusDto**](PageStatusDto.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: Not defined
+ - **Accept**: */*
+
+### HTTP response details
+
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**200** | OK |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+# **find_one14**
+> StatusDto find_one14(id)
+
+Find status by id
+
+### Example
+
+
+```python
+import src.client.generated
+from src.client.generated.models.status_dto import StatusDto
+from src.client.generated.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost
+# See configuration.py for a list of all supported configuration parameters.
+configuration = src.client.generated.Configuration(
+    host = "http://localhost"
+)
+
+
+# Enter a context with an instance of the API client
+async with src.client.generated.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = src.client.generated.StatusControllerApi(api_client)
+    id = 56 # int | 
+
+    try:
+        # Find status by id
+        api_response = await api_instance.find_one14(id)
+        print("The response of StatusControllerApi->find_one14:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling StatusControllerApi->find_one14: %s\n" % e)
+```
+
+
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **id** | **int**|  | 
+
+### Return type
+
+[**StatusDto**](StatusDto.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: Not defined
+ - **Accept**: */*
+
+### HTTP response details
+
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**200** | OK |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+# **patch17**
+> StatusDto patch17(id, status_patch_dto)
+
+Patch status
+
+### Example
+
+
+```python
+import src.client.generated
+from src.client.generated.models.status_dto import StatusDto
+from src.client.generated.models.status_patch_dto import StatusPatchDto
+from src.client.generated.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost
+# See configuration.py for a list of all supported configuration parameters.
+configuration = src.client.generated.Configuration(
+    host = "http://localhost"
+)
+
+
+# Enter a context with an instance of the API client
+async with src.client.generated.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = src.client.generated.StatusControllerApi(api_client)
+    id = 56 # int | 
+    status_patch_dto = src.client.generated.StatusPatchDto() # StatusPatchDto | 
+
+    try:
+        # Patch status
+        api_response = await api_instance.patch17(id, status_patch_dto)
+        print("The response of StatusControllerApi->patch17:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling StatusControllerApi->patch17: %s\n" % e)
+```
+
+
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **id** | **int**|  | 
+ **status_patch_dto** | [**StatusPatchDto**](StatusPatchDto.md)|  | 
+
+### Return type
+
+[**StatusDto**](StatusDto.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: application/json
+ - **Accept**: */*
+
+### HTTP response details
+
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**200** | OK |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+# **suggest8**
+> PageIdAndNameOnlyDto suggest8(query=query, workflow_id=workflow_id, id=id, ignore_id=ignore_id, page=page, size=size, sort=sort)
+
+Suggest statuses
+
+### Example
+
+
+```python
+import src.client.generated
+from src.client.generated.models.page_id_and_name_only_dto import PageIdAndNameOnlyDto
+from src.client.generated.rest import ApiException
+from pprint import pprint
+
+# Defining the host is optional and defaults to http://localhost
+# See configuration.py for a list of all supported configuration parameters.
+configuration = src.client.generated.Configuration(
+    host = "http://localhost"
+)
+
+
+# Enter a context with an instance of the API client
+async with src.client.generated.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = src.client.generated.StatusControllerApi(api_client)
+    query = 'query_example' # str |  (optional)
+    workflow_id = 56 # int |  (optional)
+    id = [56] # List[int] |  (optional)
+    ignore_id = [56] # List[int] |  (optional)
+    page = 0 # int | Zero-based page index (0..N) (optional) (default to 0)
+    size = 10 # int | The size of the page to be returned (optional) (default to 10)
+    sort = [name,ASC] # List[str] | Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported. (optional) (default to [name,ASC])
+
+    try:
+        # Suggest statuses
+        api_response = await api_instance.suggest8(query=query, workflow_id=workflow_id, id=id, ignore_id=ignore_id, page=page, size=size, sort=sort)
+        print("The response of StatusControllerApi->suggest8:\n")
+        pprint(api_response)
+    except Exception as e:
+        print("Exception when calling StatusControllerApi->suggest8: %s\n" % e)
+```
+
+
+
+### Parameters
+
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **query** | **str**|  | [optional] 
+ **workflow_id** | **int**|  | [optional] 
+ **id** | [**List[int]**](int.md)|  | [optional] 
+ **ignore_id** | [**List[int]**](int.md)|  | [optional] 
+ **page** | **int**| Zero-based page index (0..N) | [optional] [default to 0]
+ **size** | **int**| The size of the page to be returned | [optional] [default to 10]
+ **sort** | [**List[str]**](str.md)| Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported. | [optional] [default to [name,ASC]]
+
+### Return type
+
+[**PageIdAndNameOnlyDto**](PageIdAndNameOnlyDto.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: Not defined
+ - **Accept**: */*
+
+### HTTP response details
+
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**200** | OK |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+

src/services/test_case_service.py

@@ -19,7 +19,6 @@ from src.client.generated.models import (
     TestCaseCreateV2Dto,
     TestCaseDto,
     TestCaseOverviewDto,
-    TestCaseTreeSelectionDto,
     TestTagDto,
 )
 from src.client.generated.models.attachment_step_dto import AttachmentStepDto
@@ -80,9 +79,10 @@ class TestCaseService:
         self._client = client
         self._project_id = client.get_project()
         self._attachment_service = attachment_service or AttachmentService(self._client)
-        self._cf_cache: dict[int, dict[str, int]] = {}  # {project_id: {name: id}}
+        # {project_id: {name: {"id": int, "values": list[str]}}}
+        self._cf_cache: dict[int, dict[str, dict[str, Any]]] = {}
 
-    async def create_test_case(
+    async def create_test_case(  # noqa: C901
         self,
         name: str,
         description: str | None = None,
@@ -120,15 +120,46 @@ class TestCaseService:
         resolved_custom_fields = []
         if custom_fields:
             project_cfs = await self._get_resolved_custom_fields(self._project_id)
+            missing_fields = []
+            invalid_values = []
+
             for key, value in custom_fields.items():
-                cf_id = project_cfs.get(key)
-                if cf_id is None:
-                    raise AllureValidationError(f"Custom field '{key}' not found in project {self._project_id}.")
+                cf_info = project_cfs.get(key)
+                if cf_info is None:
+                    missing_fields.append(key)
+                else:
+                    cf_id = cf_info["id"]
+                    allowed_values = cf_info["values"]
+
+                    # Validate value if allowed_values are present
+                    if allowed_values and value not in allowed_values:
+                        invalid_values.append(f"'{key}': '{value}' (Allowed: {', '.join(allowed_values)})")
+                    else:
+                        resolved_custom_fields.append(
+                            CustomFieldValueWithCfDto(custom_field=CustomFieldDto(id=cf_id, name=key), name=value)
+                        )
 
-                resolved_custom_fields.append(
-                    CustomFieldValueWithCfDto(custom_field=CustomFieldDto(id=cf_id, name=key), name=value)
+            error_messages = []
+
+            if missing_fields:
+                missing_list_str = "\n".join([f"- {name}" for name in missing_fields])
+                error_messages.append(
+                    f"The following custom fields were not found in project {self._project_id}:\n{missing_list_str}"
                 )
 
+            if invalid_values:
+                invalid_list_str = "\n".join([f"- {item}" for item in invalid_values])
+                error_messages.append(f"The following custom field values are invalid:\n{invalid_list_str}")
+
+            if error_messages:
+                full_error_msg = "\n\n".join(error_messages) + (
+                    "\n\nUsage Hint:\n"
+                    "1. Exclude all missing custom fields from your request.\n"
+                    "2. Correct any invalid values to match the allowed options.\n"
+                    "3. Only include fields that explicitly exist in the project configuration."
+                )
+                raise AllureValidationError(full_error_msg)
+
         # 3. Create TestCaseCreateV2Dto with validation
         tag_dtos = self._build_tag_dtos(tags)
         try:
@@ -185,6 +216,27 @@ class TestCaseService:
         """
         return await self._client.get_test_case(test_case_id)
 
+    async def get_custom_fields(self, name: str | None = None) -> list[dict[str, Any]]:
+        """Get custom fields for the project with optional name filtering.
+
+        This method uses the internal cache to avoid duplicate API calls when
+        both get_custom_fields and create_test_case are used in the same session.
+        """
+        # Use cached resolution method to get field mapping
+        cf_mapping = await self._get_resolved_custom_fields(self._project_id)
+
+        result = []
+        filter_name = name.lower() if name else None
+
+        # Convert the cached mapping back to the display format
+        for field_name, field_info in cf_mapping.items():
+            if filter_name and filter_name not in field_name.lower():
+                continue
+
+            result.append({"name": field_name, "required": field_info["required"], "values": field_info["values"]})
+
+        return result
+
     async def update_test_case(self, test_case_id: int, data: TestCaseUpdate) -> TestCaseDto:
         """Update an existing test case.
 
@@ -423,10 +475,17 @@ class TestCaseService:
                 resolved_cfs = []
                 project_cfs = await self._get_resolved_custom_fields(project_id)
                 for key, value in data.custom_fields.items():
-                    cf_id = project_cfs.get(key)
-                    if cf_id:
+                    cf_info = project_cfs.get(key)
+                    if cf_info:
+                        # For updates, we blindly trust if it exists, or should we validate?
+                        # The plan implies validating create, let's also validate update to be safe,
+                        # but typically update is just "prepare kwargs".
+                        # If we want validation here, we should add it.
+                        # For now, adapting to the new dict structure is required.
                         resolved_cfs.append(
-                            CustomFieldValueWithCfDto(custom_field=CustomFieldDto(id=cf_id, name=key), name=value)
+                            CustomFieldValueWithCfDto(
+                                custom_field=CustomFieldDto(id=cf_info["id"], name=key), name=value
+                            )
                         )
                 patch_kwargs["custom_fields"] = resolved_cfs
                 has_changes = True
@@ -695,31 +754,31 @@ class TestCaseService:
                 raise AllureValidationError(f"Invalid tag '{t}': {e}", suggestions=[hint]) from e
         return tag_dtos
 
-    async def _get_resolved_custom_fields(self, project_id: int) -> dict[str, int]:
-        """Get or fetch custom field name-to-id mapping for a project."""
+    async def _get_resolved_custom_fields(self, project_id: int) -> dict[str, dict[str, Any]]:
+        """Get or fetch custom field name-to-info mapping for a project."""
         if project_id in self._cf_cache:
             return self._cf_cache[project_id]
 
-        try:
-            from src.client.generated.api.test_case_custom_field_controller_api import TestCaseCustomFieldControllerApi
-
-            api = TestCaseCustomFieldControllerApi(self._client.api_client)
-            selection = TestCaseTreeSelectionDto(project_id=project_id)
-            cfs = await api.get_custom_fields_with_values2(test_case_tree_selection_dto=selection)
-
-            mapping = {}
-            for cf_with_values in cfs:
-                if cf_with_values.custom_field and cf_with_values.custom_field.custom_field:
-                    inner_cf = cf_with_values.custom_field.custom_field
-                    if inner_cf.name and inner_cf.id:
-                        mapping[inner_cf.name] = inner_cf.id
-
-            self._cf_cache[project_id] = mapping
-            return mapping
-        except Exception as e:
-            # If we fail to fetch CFs, we might want to warn or raise.
-            # For now, let's raise as it's critical for resolving names to IDs.
-            raise AllureValidationError(f"Failed to fetch custom fields for project {project_id}: {e}") from e
+        # Use the client wrapper method for consistent error handling and response processing
+        cfs = await self._client.get_custom_fields_with_values(project_id)
+        logger.debug("Fetched %d custom fields for project %d", len(cfs), project_id)
+        mapping = {}
+        for cf_with_values in cfs:
+            if cf_with_values.custom_field and cf_with_values.custom_field.custom_field:
+                inner_cf = cf_with_values.custom_field.custom_field
+                if inner_cf.name and inner_cf.id:
+                    values = []
+                    if cf_with_values.values:
+                        values = [v.name for v in cf_with_values.values if v.name]
+
+                    mapping[inner_cf.name] = {
+                        "id": inner_cf.id,
+                        "required": bool(cf_with_values.custom_field.required),
+                        "values": values,
+                    }
+
+        self._cf_cache[project_id] = mapping
+        return mapping
 
     def _build_custom_field_dtos(self, custom_fields: dict[str, str] | None) -> list[CustomFieldValueWithCfDto]:
         """DEPRECATED: Use inline resolution in create_test_case."""

src/tools/__init__.py

@@ -2,6 +2,7 @@ from collections.abc import Awaitable, Callable
 
 from src.tools.create_test_case import create_test_case
 from src.tools.delete_test_case import delete_test_case
+from src.tools.get_custom_fields import get_custom_fields
 from src.tools.link_shared_step import link_shared_step
 from src.tools.search import get_test_case_details, list_test_cases, search_test_cases
 from src.tools.shared_steps import create_shared_step, delete_shared_step, list_shared_steps, update_shared_step
@@ -13,6 +14,7 @@ __all__ = [
     "create_test_case",
     "delete_shared_step",
     "delete_test_case",
+    "get_custom_fields",
     "get_test_case_details",
     "link_shared_step",
     "list_shared_steps",
@@ -31,6 +33,7 @@ all_tools: list[ToolFn] = [
     update_test_case,
     delete_test_case,
     list_test_cases,
+    get_custom_fields,
     search_test_cases,
     create_shared_step,
     list_shared_steps,

src/tools/get_custom_fields.py

@@ -0,0 +1,48 @@
+from typing import Annotated
+
+from pydantic import Field
+
+from src.client import AllureClient
+from src.services.test_case_service import TestCaseService
+
+
+async def get_custom_fields(
+    name: Annotated[
+        str | None, Field(description="Optional case-insensitive name filter to search for specific custom fields.")
+    ] = None,
+    project_id: Annotated[
+        int | None, Field(description="Allure TestOps project ID to fetch custom fields from.")
+    ] = None,
+) -> str:
+    """Get available custom fields and their allowed values for the project.
+
+    Use this tool to discover what custom fields are available (e.g., 'Layer', 'Priority')
+    and what values are valid for them (e.g., 'UI', 'High'). This is essential before
+    creating or updating test cases to ensure you use valid field names and values.
+
+    Args:
+        name: Optional name filter to find a specific field (case-insensitive).
+        project_id: Optional project ID override.
+
+    Returns:
+        A list of custom fields with their required status and allowed values.
+    """
+    async with AllureClient.from_env(project=project_id) as client:
+        service = TestCaseService(client)
+        fields = await service.get_custom_fields(name=name)
+
+    if not fields:
+        if name:
+            return f"No custom fields found matching '{name}'."
+        return "No custom fields found for this project."
+
+    lines = [f"Found {len(fields)} custom fields:"]
+
+    for cf in fields:
+        field_name = cf["name"]
+        required = "required" if cf["required"] else "optional"
+        values = ", ".join(cf["values"]) if cf["values"] else "Any text/No allowed values"
+
+        lines.append(f"- {field_name} ({required}): {values}")
+
+    return "\n".join(lines)