Poetry MCP Server

Instructions

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()

• src/poetry_mcp/models/results.py:156-241 (schema)

  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"
              }
          }