Poetry MCP Server

Instructions

Implementation Reference

• src/poetry_mcp/server.py:116-189 (handler)

  The core handler function for the 'search_poems' tool. It performs text search, applies filters for states, forms, and tags, sorts by relevance, limits results, and returns a SearchResult. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def search_poems(
      query: str,
      states: Optional[List[str]] = None,
      forms: Optional[List[str]] = None,
      tags: Optional[List[str]] = None,
      limit: int = 20,
      include_content: bool = False
  ) -> SearchResult:
      """
      Search for poems matching criteria.
  
      Args:
          query: Text to search for in titles, content, and notes
          states: Filter by states (e.g., ["completed", "fledgeling"])
          forms: Filter by forms (e.g., ["free_verse", "prose_poem"])
          tags: Filter by tags (poems must have all specified tags)
          limit: Maximum number of results to return
          include_content: Whether to include full poem text in results
  
      Returns:
          SearchResult with matched poems and query metadata
      """
      import time
      start_time = time.perf_counter()
  
      cat = get_catalog()
  
      # Start with text search if query provided
      if query:
          results = cat.index.search_content(query, case_sensitive=False)
      else:
          # No query, start with all poems
          results = cat.index.all_poems.copy()
  
      # Apply state filter
      if states:
          results = [p for p in results if p.state in states]
  
      # Apply form filter
      if forms:
          results = [p for p in results if p.form in forms]
  
      # Apply tag filter (must have all tags)
      if tags:
          results = [
              p for p in results
              if all(tag.lower() in [t.lower() for t in p.tags] for tag in tags)
          ]
  
      # Sort by relevance (poems with more tag matches first)
      if tags:
          def relevance_score(poem: Poem) -> int:
              return sum(1 for tag in tags if tag.lower() in [t.lower() for t in poem.tags])
          results.sort(key=relevance_score, reverse=True)
  
      # Limit results
      total_matches = len(results)
      results = results[:limit]
  
      # Remove content if not requested
      if not include_content:
          results = [
              Poem(**{**p.model_dump(), 'content': None})
              for p in results
          ]
  
      query_time_ms = (time.perf_counter() - start_time) * 1000
  
      return SearchResult(
          poems=results,
          total_matches=total_matches,
          query_time_ms=query_time_ms
      )

• src/poetry_mcp/models/results.py:71-110 (schema)

  Pydantic model defining the output schema for the search_poems tool, including list of poems, total matches, and query time.

  class SearchResult(BaseModel):
      """
      Result from search_poems operation.
  
      Contains matched poems and query metadata.
      """
  
      poems: list[Poem] = Field(
          ...,
          description="List of poems matching search criteria"
      )
  
      total_matches: int = Field(
          ...,
          description="Total number of poems matching query (may be > len(poems) if limited)"
      )
  
      query_time_ms: float = Field(
          ...,
          description="Time taken to execute query in milliseconds"
      )
  
      class Config:
          """Pydantic configuration."""
          json_schema_extra = {
              "example": {
                  "poems": [
                      {
                          "id": "second-bridge",
                          "title": "Second Bridge Out Old Route 12",
                          "state": "completed",
                          "form": "free_verse",
                          "tags": ["water", "memory"]
                      }
                  ],
                  "total_matches": 23,
                  "query_time_ms": 45.2
              }
          }

• src/poetry_mcp/server.py:116-116 (registration)

  The @mcp.tool() decorator registers the search_poems function as an MCP tool.

  @mcp.tool()