Rundeck MCP Server

Instructions

Returns the full execution details including status, timing, node results,
and the arguments used.

Args:
    execution_id: The execution ID (integer)

Returns:
    Execution object with full details

Examples:
    >>> execution = get_execution(12345)
    >>> print(execution.status)
    'succeeded'
    >>> print(execution.duration_seconds)
    45.2

Implementation Reference

• rundeck_mcp/tools/executions.py:61-84 (handler)

  The get_execution tool handler: retrieves detailed execution information from Rundeck API via HTTP GET /execution/{execution_id} and parses the response.

  def get_execution(execution_id: int) -> Execution:
      """Get detailed information about a specific execution.
  
      Returns the full execution details including status, timing, node results,
      and the arguments used.
  
      Args:
          execution_id: The execution ID (integer)
  
      Returns:
          Execution object with full details
  
      Examples:
          >>> execution = get_execution(12345)
          >>> print(execution.status)
          'succeeded'
          >>> print(execution.duration_seconds)
          45.2
      """
      client = get_client()
      response = client.get(f"/execution/{execution_id}")
  
      return _parse_execution(response)

• rundeck_mcp/models/executions.py:92-183 (schema)

  Pydantic schema/model for the Execution return type of get_execution tool, including fields, validators, and computed properties.

  class Execution(BaseModel):
      """A job execution instance.
  
      Represents a single run of a job, including its status, timing, and results.
      """
  
      id: int = Field(description="The execution ID")
      href: str | None = Field(default=None, description="API URL for this execution")
      permalink: str | None = Field(default=None, description="Web UI URL for this execution")
      status: ExecutionStatus = Field(description="Execution status")
      project: str = Field(description="The project name")
      job: JobReference | None = Field(default=None, description="Reference to the job (None for adhoc executions)")
      user: str = Field(description="User who started this execution")
      date_started: datetime | None = Field(
          default=None,
          alias="date-started",
          description="When the execution started",
      )
      date_ended: datetime | None = Field(
          default=None,
          alias="date-ended",
          description="When the execution ended (None if still running)",
      )
      argstring: str | None = Field(
          default=None,
          description="The argument string used for this execution",
      )
      description: str | None = Field(default=None, description="Execution description")
      successful_nodes: list[str] | None = Field(
          default=None,
          alias="successfulNodes",
          description="List of nodes that succeeded",
      )
      failed_nodes: list[str] | None = Field(
          default=None,
          alias="failedNodes",
          description="List of nodes that failed",
      )
  
      @field_validator("date_started", "date_ended", mode="before")
      @classmethod
      def parse_date_dict(cls, v: Any) -> datetime | None:
          """Parse date from Rundeck's dict format or ISO string."""
          if v is None:
              return None
          if isinstance(v, datetime):
              return v
          if isinstance(v, dict):
              # Rundeck returns {"unixtime": 1234567890, "date": "..."}
              if "unixtime" in v:
                  return datetime.fromtimestamp(v["unixtime"] / 1000)
              if "date" in v:
                  return datetime.fromisoformat(v["date"].replace("Z", "+00:00"))
          if isinstance(v, str):
              return datetime.fromisoformat(v.replace("Z", "+00:00"))
          return None
  
      @computed_field
      @property
      def duration_seconds(self) -> float | None:
          """Calculate duration in seconds."""
          if self.date_started and self.date_ended:
              return (self.date_ended - self.date_started).total_seconds()
          return None
  
      @computed_field
      @property
      def execution_summary(self) -> str:
          """Generate a human-readable summary of this execution."""
          parts = [f"Execution #{self.id}: {self.status.upper()}"]
  
          if self.job:
              parts.append(f"Job: {self.job.name}")
              if self.job.group:
                  parts[-1] = f"Job: {self.job.group}/{self.job.name}"
  
          if self.user:
              parts.append(f"User: {self.user}")
  
          if self.duration_seconds is not None:
              parts.append(f"Duration: {self.duration_seconds:.1f}s")
  
          if self.argstring:
              parts.append(f"Args: {self.argstring}")
  
          return " | ".join(parts)
  
      @computed_field
      @property
      def type(self) -> Literal["execution"]:
          return "execution"

• rundeck_mcp/server.py:107-109 (registration)

  MCP server registration loop that adds get_execution (via read_tools list) as a read-only tool with appropriate annotations.

  # Register read-only tools (always available)
  for tool in read_tools:
      add_read_only_tool(mcp, tool)

• rundeck_mcp/tools/__init__.py:13-20 (registration)

  Definition of read_tools list that includes get_execution for registration in MCP server.

  read_tools = [
      # Jobs
      list_jobs,
      get_job,
      # Executions
      list_executions,
      get_execution,
      get_execution_output,

• rundeck_mcp/tools/executions.py:145-181 (helper)

  Helper function to parse raw API response data into Execution model instance.

  def _parse_execution(data: dict[str, Any]) -> Execution:
      """Parse execution data from API response.
  
      Args:
          data: Raw API response data
  
      Returns:
          Parsed Execution model
      """
      # Parse job reference if present
      job_data = data.get("job")
      job_ref = None
      if job_data:
          job_ref = JobReference(
              id=job_data.get("id", ""),
              name=job_data.get("name", ""),
              group=job_data.get("group"),
              project=job_data.get("project", data.get("project", "")),
              href=job_data.get("href"),
              permalink=job_data.get("permalink"),
          )
  
      return Execution(
          id=data["id"],
          href=data.get("href"),
          permalink=data.get("permalink"),
          status=data.get("status", "running"),
          project=data.get("project", ""),
          job=job_ref,
          user=data.get("user", "unknown"),
          date_started=data.get("date-started"),
          date_ended=data.get("date-ended"),
          argstring=data.get("argstring"),
          description=data.get("description"),
          successful_nodes=data.get("successfulNodes"),
          failed_nodes=data.get("failedNodes"),
      )