Poetry MCP Server

Instructions

Implementation Reference

• src/poetry_mcp/server.py:83-113 (handler)

  The handler function for the 'get_poem' MCP tool, decorated with @mcp.tool() for automatic registration and schema inference from signature/docstring. Retrieves poem by ID or title from catalog index.
  @mcp.tool() async def get_poem( identifier: str, include_content: bool = True ) -> Optional[Poem]: """ Get a poem by ID or title. Args: identifier: Poem ID or exact title include_content: Whether to include full poem text Returns: Poem object or None if not found """ cat = get_catalog() # Try by ID first poem = cat.index.get_by_id(identifier.lower()) # Try by title if not found if not poem: poem = cat.index.get_by_title(identifier) if poem and not include_content: # Return copy without content poem_dict = poem.model_dump() poem_dict['content'] = None poem = Poem(**poem_dict) return poem
• src/poetry_mcp/models/poem.py:11-136 (schema)

  Pydantic BaseModel defining the structure and validation for the Poem object returned by the get_poem tool.
  class Poem(BaseModel): """ Poem model representing a single poem with metadata from frontmatter. Required frontmatter properties: - state: Production state (completed, fledgeling, etc.) - form: Structural pattern (free_verse, prose_poem, etc.) Optional frontmatter properties: - tags: Thematic tags for nexus connections - keywords: Legacy comma-separated tags Computed properties: - id: Generated from filename - word_count, line_count, stanza_count: Computed from content - created_at, updated_at: From filesystem timestamps """ # Core identity id: str = Field(..., description="Unique identifier (filename without .md)") title: str = Field(..., description="Poem title from first # heading or filename") file_path: str = Field(..., description="Relative path from vault root") # Frontmatter: Required properties state: Literal[ "completed", "fledgeling", "still_cooking", "needs_research", "risk" ] = Field(..., description="Production state of the poem") form: Literal[ "free_verse", "prose_poem", "american_sentence", "catalog_poem" ] = Field(..., description="Structural/formal pattern") # Frontmatter: Optional properties tags: list[str] = Field( default_factory=list, description="Thematic tags for nexus connections" ) keywords: Optional[str] = Field( default=None, description="Legacy comma-separated keywords (prefer tags)" ) notes: Optional[str] = Field( default=None, description="Editorial notes about the poem" ) # Computed metrics word_count: int = Field(..., description="Total word count") line_count: int = Field(..., description="Total line count") stanza_count: Optional[int] = Field( default=None, description="Number of stanzas (blank-line separated)" ) # Filesystem metadata created_at: datetime = Field(..., description="File creation timestamp") updated_at: datetime = Field(..., description="File modification timestamp") # Content (optional, for search/display) content: Optional[str] = Field( default=None, description="Full poem text (only included if requested)" ) @field_validator('state') @classmethod def validate_state(cls, v: str) -> str: """Validate state enum value.""" valid_states = { "completed", "fledgeling", "still_cooking", "needs_research", "risk" } if v not in valid_states: raise ValueError( f"Invalid state '{v}'. Must be one of: {', '.join(valid_states)}" ) return v @field_validator('form') @classmethod def validate_form(cls, v: str) -> str: """Validate form enum value.""" valid_forms = { "free_verse", "prose_poem", "american_sentence", "catalog_poem" } if v not in valid_forms: raise ValueError( f"Invalid form '{v}'. Must be one of: {', '.join(valid_forms)}" ) return v @field_validator('tags') @classmethod def normalize_tags(cls, v: list[str]) -> list[str]: """Normalize tags: lowercase, strip whitespace, remove duplicates.""" if not v: return [] normalized = [tag.lower().strip() for tag in v if tag.strip()] return list(dict.fromkeys(normalized)) # Preserve order, remove dupes class Config: """Pydantic configuration.""" json_schema_extra = { "example": { "id": "second-bridge-out-old-route-12", "title": "Second Bridge Out Old Route 12", "file_path": "catalog/Completed/second-bridge-out-old-route-12.md", "state": "completed", "form": "free_verse", "tags": ["water", "body", "memory", "Vermont"], "word_count": 358, "line_count": 42, "stanza_count": 7, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-06-20T14:22:00Z" } }