Poetry MCP Server

Instructions

Implementation Reference

• src/poetry_mcp/tools/enrichment_tools.py:38-59 (handler)

  Core handler function that returns the global _nexus_registry after checking initialization. This contains the actual tool logic.

  async def get_all_nexuses() -> NexusRegistry:
      """Get all nexuses (themes/motifs/forms) from the registry.
  
      Returns complete registry with all nexus entries, organized by category.
      Use this to discover available themes, motifs, and forms for tagging poems.
  
      Returns:
          NexusRegistry with themes, motifs, and forms
  
      Example:
          >>> registry = await get_all_nexuses()
          >>> registry.total_count
          25
          >>> [t.name for t in registry.themes[:3]]
          ['Water-Liquid', 'Body-Bones', 'Childhood']
          >>> registry.themes[0].canonical_tag
          'water-liquid'
      """
      if _nexus_registry is None:
          raise RuntimeError("Enrichment tools not initialized. Call initialize_enrichment_tools() first.")
  
      return _nexus_registry

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

  MCP tool registration using @mcp.tool() decorator. Delegates to the core handler in enrichment_tools.py.

  @mcp.tool()
  async def get_all_nexuses() -> NexusRegistry:
      """
      Get all nexuses (themes/motifs/forms) from the registry.
  
      Returns complete registry with all nexus entries, organized by category.
      Use this to discover available themes, motifs, and forms for tagging poems.
  
      Returns:
          NexusRegistry with themes, motifs, and forms
  
      Example:
          Get all available themes:
          ```
          registry = await get_all_nexuses()
          for theme in registry.themes:
              print(f"{theme.name} → #{theme.canonical_tag}")
          ```
      """
      return await _get_all_nexuses()

• src/poetry_mcp/models/nexus.py:88-114 (schema)

  Pydantic model defining the return type NexusRegistry, including fields for themes, motifs, forms, and total_count.

  class NexusRegistry(BaseModel):
      """
      Complete nexus registry organized by category.
  
      Returned by get_all_nexuses() tool.
      """
  
      themes: list[Nexus] = Field(
          default_factory=list,
          description="Thematic nexuses (imagery systems, subjects)"
      )
  
      motifs: list[Nexus] = Field(
          default_factory=list,
          description="Motif nexuses (compositional patterns)"
      )
  
      forms: list[Nexus] = Field(
          default_factory=list,
          description="Form nexuses (structural patterns)"
      )
  
      total_count: int = Field(
          ...,
          description="Total number of nexuses across all categories"
      )

• src/poetry_mcp/tools/enrichment_tools.py:24-36 (helper)

  Helper function that initializes the global _nexus_registry by loading from config.vault.path, required before calling get_all_nexuses.

  def initialize_enrichment_tools(catalog: Catalog) -> None:
      """Initialize global state for enrichment tools.
  
      Args:
          catalog: Catalog instance to use for lookups
      """
      global _catalog, _nexus_registry
      _catalog = catalog
  
      # Load nexus registry on initialization
      config = load_config()
      _nexus_registry = load_nexus_registry(config.vault.path)

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

  Import and alias of get_all_nexuses from enrichment_tools.py for use in server tool wrappers.

  from .tools.enrichment_tools import (
      initialize_enrichment_tools,
      get_all_nexuses as _get_all_nexuses,
      link_poem_to_nexus as _link_poem_to_nexus,
      find_nexuses_for_poem as _find_nexuses_for_poem,
      get_poems_for_enrichment as _get_poems_for_enrichment,
      sync_nexus_tags as _sync_nexus_tags,
      move_poem_to_state as _move_poem_to_state,
      grade_poem_quality as _grade_poem_quality,
  )