get_catalog_stats
Retrieve catalog statistics including poem counts, quality metrics, and health information to monitor your poetry collection's status and performance.
Instructions
Get catalog statistics.
Returns: CatalogStats with counts, metrics, and health information
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| by_form | Yes | Count of poems by form | |
| by_state | Yes | Count of poems by state | |
| last_sync | No | Timestamp of last catalog sync | |
| newest_poem | Yes | Title of most recently created poem | |
| oldest_poem | Yes | Title of oldest poem | |
| total_poems | Yes | Total number of poems in catalog | |
| avg_word_count | Yes | Average word count per poem | |
| total_word_count | Yes | Total words across all poems | |
| poems_without_tags | Yes | Number of poems with no tags | |
| poems_missing_frontmatter | No | Number of poems with incomplete frontmatter |
Implementation Reference
- src/poetry_mcp/server.py:275-285 (handler)The main execution logic for the get_catalog_stats tool. Decorated with @mcp.tool() which also handles registration in the FastMCP server. Calls catalog.get_stats() to compute and return CatalogStats.
@mcp.tool() async def get_catalog_stats() -> CatalogStats: """ Get catalog statistics. Returns: CatalogStats with counts, metrics, and health information """ cat = get_catalog() return cat.get_stats() - Pydantic model defining the output schema (CatalogStats) for the get_catalog_stats tool, including detailed field descriptions and example.
class CatalogStats(BaseModel): """ Catalog statistics and health metrics. Returned by get_catalog_stats() tool. """ total_poems: int = Field( ..., description="Total number of poems in catalog" ) by_state: dict[str, int] = Field( ..., description="Count of poems by state" ) by_form: dict[str, int] = Field( ..., description="Count of poems by form" ) poems_without_tags: int = Field( ..., description="Number of poems with no tags" ) poems_missing_frontmatter: int = Field( default=0, description="Number of poems with incomplete frontmatter" ) total_word_count: int = Field( ..., description="Total words across all poems" ) avg_word_count: float = Field( ..., description="Average word count per poem" ) newest_poem: str = Field( ..., description="Title of most recently created poem" ) oldest_poem: str = Field( ..., description="Title of oldest poem" ) last_sync: Optional[str] = Field( default=None, description="Timestamp of last catalog sync" ) class Config: """Pydantic configuration.""" json_schema_extra = { "example": { "total_poems": 381, "by_state": { "completed": 49, "fledgeling": 172, "still_cooking": 65, "needs_research": 10, "risk": 22, "phone_poetry": 63 }, "by_form": { "free_verse": 310, "prose_poem": 45, "american_sentence": 18, "catalog_poem": 8 }, "poems_without_tags": 350, "poems_missing_frontmatter": 0, "total_word_count": 125430, "avg_word_count": 329.2, "newest_poem": "November Rain", "oldest_poem": "First Poem", "last_sync": "2025-10-30T21:45:00Z" } }