Poetry MCP Server

Instructions

Implementation Reference

• src/poetry_mcp/server.py:232-272 (handler)

  The handler function decorated with @mcp.tool(), which registers the tool and implements the core logic: fetches poems by state from the catalog index, sorts by specified field, applies limit, strips content, and returns the list.

  @mcp.tool()
  async def list_poems_by_state(
      state: str,
      sort_by: str = "title",
      limit: int = 100
  ) -> List[Poem]:
      """
      List poems in a specific state.
  
      Args:
          state: State to filter by (completed, fledgeling, still_cooking, etc.)
          sort_by: Field to sort by (title, created_at, updated_at, word_count)
          limit: Maximum number of results
  
      Returns:
          List of poems in the specified state
      """
      cat = get_catalog()
  
      poems = cat.index.get_by_state(state)
  
      # Sort by requested field
      if sort_by == "title":
          poems.sort(key=lambda p: p.title.lower())
      elif sort_by == "created_at":
          poems.sort(key=lambda p: p.created_at, reverse=True)
      elif sort_by == "updated_at":
          poems.sort(key=lambda p: p.updated_at, reverse=True)
      elif sort_by == "word_count":
          poems.sort(key=lambda p: p.word_count, reverse=True)
  
      # Limit results
      poems = poems[:limit]
  
      # Remove content
      poems = [
          Poem(**{**p.model_dump(), 'content': None})
          for p in poems
      ]
  
      return poems