list_latest
Retrieve newly added youth opportunities from all sources, sorted by recency, with optional filters for opportunity type and maximum number.
Instructions
List the newest opportunities across all sources, most recent first.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/opportunity_mcp/server.py:63-69 (handler)The 'list_latest' MCP tool handler function. It accepts an optional OpportunityType filter and a limit (default 20), and returns the newest opportunities across all sources, most recent first. Delegates to Index.latest().
@mcp.tool() def list_latest( type: OpportunityType | None = None, limit: int = 20, ) -> list[Opportunity]: """List the newest opportunities across all sources, most recent first.""" return _get_index().latest(opp_type=type, limit=limit) - src/opportunity_mcp/server.py:63-64 (registration)The tool is registered via the @mcp.tool() decorator on the list_latest function, which is how FastMCP registers MCP tools.
@mcp.tool() def list_latest( - src/opportunity_mcp/schema.py:11-20 (schema)The OpportunityType enum used as a parameter type for list_latest. Defines valid opportunity types (scholarship, fellowship, internship, etc.).
class OpportunityType(StrEnum): SCHOLARSHIP = "scholarship" FELLOWSHIP = "fellowship" INTERNSHIP = "internship" CONFERENCE = "conference" EXCHANGE = "exchange" COMPETITION = "competition" GRANT = "grant" AWARD = "award" OTHER = "other" - src/opportunity_mcp/schema.py:40-59 (schema)The Opportunity return type schema, defining the shape of each opportunity returned by list_latest.
class Opportunity(BaseModel): """A single opportunity record. The shape every adapter must produce.""" model_config = ConfigDict(use_enum_values=False) id: str = Field(..., description="sha1(source + canonical_url)[:16]") title: str type: OpportunityType summary: str = Field(..., max_length=500) deadline: date | None = None funded: FundingLevel = FundingLevel.UNKNOWN eligible_countries: list[str] | Literal["worldwide"] | None = None eligible_levels: list[StudyLevel] = Field(default_factory=list) host_country: str | None = None apply_url: AnyHttpUrl source_site: str source_url: AnyHttpUrl posted_at: datetime scraped_at: datetime raw_categories: list[str] = Field(default_factory=list) - src/opportunity_mcp/index.py:207-218 (helper)The Index.latest() method that list_latest delegates to. Queries the SQLite database for opportunities ordered by posted_at DESC, with optional type filter and limit.
def latest( self, *, opp_type: OpportunityType | None = None, limit: int = 20 ) -> list[Opportunity]: sql = "SELECT * FROM opportunities" params: list = [] if opp_type: sql += " WHERE type = ?" params.append(opp_type.value) sql += " ORDER BY posted_at DESC LIMIT ?" params.append(limit) rows = self.conn.execute(sql, params).fetchall() return [_row_to_opportunity(r) for r in rows]