update_countermeasure

Instructions

Implementation Reference

• src/sde_mcp_server/tools/countermeasures.py:149-196 (handler)

  Main execution logic for the update_countermeasure MCP tool. Handles input normalization, status resolution, API call, error handling, and JSON response formatting. The docstring defines the tool schema including parameters and usage instructions.

  @mcp.tool()
  async def update_countermeasure(ctx: Context, project_id: int, countermeasure_id: Union[int, str], status: Optional[str] = None, notes: Optional[str] = None) -> str:
      """Update a countermeasure (status or notes). Use when user says 'update status', 'mark as complete', or 'change status'. Do NOT use for 'add note', 'document', or 'note' - use add_countermeasure_note instead. Accepts countermeasure ID as integer (e.g., 21) or string (e.g., "T21" or "31244-T21").
      
      Status can be provided as name (e.g., 'Complete', 'Not Applicable'), slug (e.g., 'DONE', 'NA'), or ID (e.g., 'TS1'). The tool will automatically resolve names/slugs to the correct status ID required by the API.
      
      IMPORTANT: The 'notes' parameter sets a status_note, which is only saved when the status actually changes. If the countermeasure already has the target status, use add_countermeasure_note instead to add a note, or change the status to a different value first, then back to the target status to trigger saving the status_note."""
      global api_client
      if api_client is None:
          api_client = init_api_client()
      normalized_id = normalize_countermeasure_id(project_id, countermeasure_id)
      data = {}
      if status is not None:
          # Resolve status name/slug to ID (API requires status IDs like "TS1", not names like "Complete")
          status_id = resolve_status_to_id(status, api_client)
          
          # Validate that we got a proper status ID (should start with "TS")
          # If the resolved status doesn't look like an ID and doesn't match the original input,
          # it means the conversion might have failed
          if not status_id.upper().startswith('TS') and status_id.lower() == status.strip().lower():
              # The status wasn't converted - this means we couldn't find a match
              # Try to get available statuses to provide a helpful error message
              try:
                  statuses_response = api_client.get_task_status_choices()
                  status_choices = statuses_response.get('status_choices', [])
                  available_statuses = [s.get('name', '') for s in status_choices if s.get('name')]
                  return json.dumps({
                      "error": f"Could not resolve status '{status}' to a status ID. The API requires status IDs (e.g., 'TS1', 'TS2'), not names.",
                      "provided_status": status,
                      "available_status_names": available_statuses[:10],  # Show first 10
                      "suggestion": "Use get_task_status_choices to see all available statuses and their IDs."
                  }, indent=2)
              except Exception:
                  return json.dumps({
                      "error": f"Could not resolve status '{status}' to a status ID. The API requires status IDs (e.g., 'TS1', 'TS2'), not names like '{status}'.",
                      "provided_status": status,
                      "suggestion": "Use get_task_status_choices to see all available statuses and their IDs."
                  }, indent=2)
          
          data["status"] = status_id
      if notes is not None:
          data["status_note"] = notes
      
      if not data:
          return json.dumps({"error": "No update data provided. Specify either 'status' or 'notes'."}, indent=2)
      
      result = api_client.update_countermeasure(project_id, normalized_id, data)
      return json.dumps(result, indent=2)

• src/sde_mcp_server/tools/countermeasures.py:10-38 (helper)

  Helper function used by update_countermeasure to normalize countermeasure_id to the full 'project_id-T{n}' format expected by the API.

  def normalize_countermeasure_id(project_id: int, countermeasure_id: Union[int, str]) -> str:
      """
      Normalize countermeasure ID to full format (project_id-task_id).
      
      Accepts:
      - Integer: 21 -> "T21" -> "{project_id}-T21"
      - String starting with "T": "T21" -> "{project_id}-T21"
      - String in full format: "31244-T21" -> "31244-T21" (as-is)
      
      Args:
          project_id: The project ID
          countermeasure_id: Countermeasure ID as int or str
          
      Returns:
          Full task ID format: "{project_id}-T{number}" or existing full format
      """
      # If integer, convert to "T{number}" format
      if isinstance(countermeasure_id, int):
          task_id = f"T{countermeasure_id}"
      else:
          # Already a string
          task_id = countermeasure_id
      
      # If already in full format (contains project_id), return as-is
      if task_id.startswith(f"{project_id}-"):
          return task_id
      
      # Otherwise, construct full format
      return f"{project_id}-{task_id}"

• src/sde_mcp_server/tools/countermeasures.py:69-146 (helper)

  Helper function used by update_countermeasure to resolve human-readable status names or slugs (e.g., 'Complete', 'DONE') to API-required status IDs (e.g., 'TS1'). Fetches status choices from API and performs exact/partial matching.

  def resolve_status_to_id(status: str, api_client) -> str:
      """
      Resolve a status name or slug to its ID.
      
      The API requires status IDs (e.g., "TS1", "TS2") not names (e.g., "Complete").
      This function looks up the status ID from the task-statuses endpoint.
      
      Args:
          status: Status name (e.g., "Complete"), slug (e.g., "DONE"), or ID (e.g., "TS1")
          api_client: The API client instance
          
      Returns:
          Status ID (e.g., "TS1") or the original value if not found
      """
      if not status or not status.strip():
          return status
      
      try:
          # Get all available statuses
          statuses_response = api_client.get_task_status_choices()
          status_choices = statuses_response.get('status_choices', [])
          
          if not status_choices:
              # If we can't get statuses, return original (might already be an ID)
              return status
          
          # Normalize input for comparison
          status_normalized = status.strip()
          status_lower = status_normalized.lower()
          
          # Check if it's already an ID (starts with "TS")
          if status_normalized.upper().startswith('TS'):
              # Verify it's a valid ID
              for s in status_choices:
                  if s.get('id', '').upper() == status_normalized.upper():
                      return s['id']
              return status_normalized  # Return as-is if not found
          
          # Try to match by exact name, slug, or meaning first (most reliable)
          for status_obj in status_choices:
              name = status_obj.get('name', '')
              slug = status_obj.get('slug', '')
              meaning = status_obj.get('meaning', '')
              status_id = status_obj.get('id', '')
              
              # Exact matches (case-insensitive)
              if (status_lower == name.lower() or 
                  status_lower == slug.lower() or 
                  status_lower == meaning.lower()):
                  return status_id
          
          # Try partial/fuzzy matching as fallback (e.g., "complete" -> "Complete")
          # Only match if the input is a substring of the name/slug (not the other way around)
          # This avoids false positives like "complete" matching "incomplete"
          for status_obj in status_choices:
              name = status_obj.get('name', '').lower()
              slug = status_obj.get('slug', '').lower()
              meaning = status_obj.get('meaning', '').lower()
              status_id = status_obj.get('id', '')
              
              # Check if normalized input matches the start of name/slug/meaning
              # or if it's a common variation
              if (name.startswith(status_lower) or 
                  slug.startswith(status_lower) or
                  meaning.startswith(status_lower) or
                  # Handle common variations like "completed" -> "complete"
                  (status_lower in ['completed', 'done', 'finished'] and 'complete' in name) or
                  (status_lower in ['completed', 'done', 'finished'] and 'done' in slug)):
                  return status_id
          
          # If no match found, return original (might be a valid ID we don't know about)
          return status_normalized
          
      except Exception as e:
          # If lookup fails, log the error but still return original value
          # In production, you might want to log this for debugging
          # For now, we'll return the original value
          return status.strip()