jobs_list

Instructions

Implementation Reference

• src/mcp_template/modules/jobs.py:30-37 (handler)

  The tool handler function for 'jobs_list'. Decorated with @server.tool(name='jobs_list'), annotated as readOnly and idempotent. Takes an optional limit parameter (default 20) and delegates to container.jobs.list_jobs().

  @server.tool(
      name="jobs_list",
      annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=False),
  )
  async def jobs_list(limit: int = 20) -> object:
      """List recent background jobs with current status and results."""
      with container.metrics.observe_tool("jobs_list"):
          return await container.jobs.list_jobs(limit=limit)

• src/mcp_template/services/jobs.py:65-68 (helper)

  The actual implementation of list_jobs() on JobService. Acquires a lock, sorts job statuses by submission time (descending), limits results, and returns a JobList model.

  async def list_jobs(self, limit: int = 20) -> JobList:
      async with self._lock:
          items = sorted(self._jobs.values(), key=lambda item: item.submitted_at, reverse=True)[:limit]
          return JobList(items=[item.model_copy(deep=True) for item in items], total=len(self._jobs))

• src/mcp_template/types/models.py:85-106 (schema)

  JobStatus and JobList model definitions used by the jobs_list tool. JobStatus holds id, name, status, timestamps, progress, metadata, result, error. JobList wraps a list of JobStatus items with a total count.

  class JobStatus(TemplateModel):
      id: str
      name: str
      status: Literal["queued", "running", "succeeded", "failed"]
      submitted_at: datetime
      started_at: datetime | None = None
      completed_at: datetime | None = None
      progress: float = 0.0
      metadata: dict[str, Any] = Field(default_factory=dict)
      result: dict[str, Any] | None = None
      error: str | None = None
  
  
  class JobSubmission(TemplateModel):
      job: JobStatus
      queue_depth: int
  
  
  class JobList(TemplateModel):
      items: list[JobStatus]
      total: int

• src/mcp_template/modules/__init__.py:17-22 (registration)

  Module registrars mapping that includes 'jobs' mapped to register_jobs, which registers the jobs_list tool on the MCP server.

  MODULE_REGISTRARS: dict[str, ModuleRegistrar] = {
      "system": register_system,
      "workspace": register_workspace,
      "jobs": register_jobs,
      "design": register_design,
  }

• src/mcp_template/modules/jobs.py:55-64 (registration)

  The ModuleDescriptor returned by the register() function, declaring 'jobs_list' in the tools list for the jobs module.

  return ModuleDescriptor(
      name="jobs",
      title="Jobs",
      summary="Long-running task scaffolding and status resources for orchestration-heavy servers.",
      tags=["background", "async", "orchestration"],
      maturity="beta",
      tools=["jobs_submit_blueprint", "jobs_get_status", "jobs_list"],
      resources=["job://{job_id}"],
      prompts=["jobs_postmortem"],
  )