ms-sentinel-mcp-server

Instructions

Implementation Reference

• tools/workspace_tools.py:319-401 (handler)

  The run method implements the core handler logic for the 'sentinel_metadata_get' tool. It extracts the metadata_id parameter, retrieves the metadata from the Azure Sentinel client, serializes it using a helper function, and returns a structured result including validation status and any errors.

  async def run(self, ctx: Context, **kwargs):
      """
      Get details for specific metadata by ID.
  
      Parameters:
          metadata_id (str, required): The ID of the metadata object to retrieve.
      Returns:
          dict: {
              'metadata': dict,
              'valid': bool,
              'errors': list[str],
              'error': str (optional, present only if an error occurs)
          }
      Output Fields:
          - metadata: Metadata object (id, name, kind, etc.)
          - valid: True if successful, False otherwise
          - errors: List of error messages (empty if none)
          - error: Error message if an error occurs (optional)
      Error cases will always include an 'error' key for testability.
      """
      logger = self.logger
      # Accept both 'metadata_id' and 'id' as input keys using the base class method
      metadata_id = self._extract_param(kwargs, "metadata_id") or self._extract_param(
          kwargs, "id"
      )
      logger.debug("SentinelMetadataGetTool metadata_id: %r", metadata_id)
      # If a full ARM resource ID is provided, extract the short name (last segment)
      if metadata_id and "/" in metadata_id:
          metadata_id = metadata_id.rstrip("/").split("/")[-1]
      result = {
          "metadata": {},
          "valid": False,
          "errors": [],
      }
      if not metadata_id:
          error_msg = (
              "Missing required parameter: metadata_id or id. Provide either "
              "the short name or the full ARM resource ID."
          )
          logger.error("%s", error_msg)
          result["error"] = error_msg
          result["errors"].append(error_msg)
          return result
      workspace_name, resource_group, subscription_id = self.get_azure_context(ctx)
      try:
          client = self.get_securityinsight_client(subscription_id)
          meta = client.metadata.get(resource_group, workspace_name, metadata_id)
  
          def _serialize_model(obj):
              if hasattr(obj, "as_dict"):
                  return obj.as_dict()
              elif hasattr(obj, "__dict__"):
                  # fallback, filter out private attributes
                  return {
                      k: v for k, v in obj.__dict__.items() if not k.startswith("_")
                  }
              elif obj is None:
                  return None
              else:
                  return str(obj)
  
          result["metadata"] = {
              "id": getattr(meta, "id", None),
              "name": getattr(meta, "name", None),
              "kind": getattr(meta, "kind", None),
              "content_id": getattr(meta, "content_id", None),
              "version": getattr(meta, "version", None),
              "parent_id": getattr(meta, "parent_id", None),
              "author": _serialize_model(getattr(meta, "author", None)),
              "source": _serialize_model(getattr(meta, "source", None)),
              "support": _serialize_model(getattr(meta, "support", None)),
              "categories": getattr(meta, "categories", None),
              "dependencies": getattr(meta, "dependencies", None),
              "created": str(getattr(meta, "created", "")),
              "last_modified": str(getattr(meta, "last_modified", "")),
          }
          result["valid"] = True
      except Exception as ex:
          error_msg = f"Error retrieving metadata: {ex}"
          logger.exception(error_msg)
          result["error"] = error_msg
          result["errors"].append(error_msg)
      return result

• tools/workspace_tools.py:570-579 (registration)

  The register_tools function registers the SentinelMetadataGetTool (which provides the 'sentinel_metadata_get' tool) with the MCP server instance via the class's register method.

  def register_tools(mcp):
      """Register all Sentinel workspace-related tools with the MCP server instance."""
      SentinelWorkspaceGetTool.register(mcp)
      SentinelSourceControlsListTool.register(mcp)
      SentinelSourceControlGetTool.register(mcp)
      SentinelMetadataListTool.register(mcp)
      SentinelMetadataGetTool.register(mcp)
      SentinelMLAnalyticsSettingsListTool.register(mcp)
      SentinelMLAnalyticsSettingGetTool.register(mcp)

• tools/workspace_tools.py:316-338 (schema)

  Tool name, description, input parameters (metadata_id), and output schema/format are defined here in the class and run method docstring.

  name = "sentinel_metadata_get"
  description = "Get details for specific Sentinel metadata by ID."
  
  async def run(self, ctx: Context, **kwargs):
      """
      Get details for specific metadata by ID.
  
      Parameters:
          metadata_id (str, required): The ID of the metadata object to retrieve.
      Returns:
          dict: {
              'metadata': dict,
              'valid': bool,
              'errors': list[str],
              'error': str (optional, present only if an error occurs)
          }
      Output Fields:
          - metadata: Metadata object (id, name, kind, etc.)
          - valid: True if successful, False otherwise
          - errors: List of error messages (empty if none)
          - error: Error message if an error occurs (optional)
      Error cases will always include an 'error' key for testability.
      """