list_jobs
View all background jobs with their current status, command, and start time to monitor ongoing processes.
Instructions
List all background jobs with their status.
Returns a list of all background jobs, including their job ID, status, command, and start time. Jobs are sorted by start time (newest first).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_jobs"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | Yes | List of all background jobs |
Implementation Reference
- src/mcp_background_job/server.py:34-48 (handler)MCP tool handler for 'list_jobs', decorated with @mcp.tool() which registers it. Calls JobManager.list_jobs() and returns ListOutput.
@mcp.tool() async def list_jobs() -> ListOutput: """List all background jobs with their status. Returns a list of all background jobs, including their job ID, status, command, and start time. Jobs are sorted by start time (newest first). """ try: job_manager = get_job_manager() jobs = await job_manager.list_jobs() return ListOutput(jobs=jobs) except Exception as e: logger.error(f"Error listing jobs: {e}") raise ToolError(f"Failed to list jobs: {str(e)}") - Pydantic model for the output schema of list_jobs tool, containing list of JobSummary.
class ListOutput(BaseModel): """Output from list tool.""" jobs: List[JobSummary] = Field(..., description="List of all background jobs") - Pydantic model for individual job summary used in ListOutput.
class JobSummary(BaseModel): """Minimal job information for listing operations.""" job_id: str = Field(..., description="UUID v4 job identifier") status: JobStatus = Field(..., description="Current job status") command: str = Field(..., description="Shell command being executed") started: datetime = Field(..., description="UTC timestamp when job started") - Core logic in JobManager service class that implements listing jobs: updates statuses, creates summaries, sorts by start time.
async def list_jobs(self) -> List[JobSummary]: """List all jobs. Returns: List of JobSummary objects for all jobs """ # Update all job statuses for job_id in list(self._jobs.keys()): try: await self._update_job_status(job_id) except Exception as e: logger.warning(f"Failed to update status for job {job_id}: {e}") # Create summaries summaries = [] for job in self._jobs.values(): summaries.append( JobSummary( job_id=job.job_id, status=job.status, command=job.command, started=job.started, ) ) # Sort by start time (newest first) summaries.sort(key=lambda x: x.started, reverse=True) return summaries