Poetry MCP Server

Instructions

Implementation Reference

• src/poetry_mcp/tools/enrichment_tools.py:687-808 (handler)

  Core handler function that implements the grade_poem_quality tool logic: retrieves the poem, loads its content, defines the 8 quality dimensions, prepares data and instructions for the MCP agent to perform the actual grading.
  async def grade_poem_quality( poem_id: str, dimensions: Optional[List[str]] = None, ) -> dict: """Prepare poem and quality rubric for grading by the MCP agent. Returns poem content and quality dimension descriptions for the agent to grade. Agent provides scores (0-10) and reasoning for each dimension. Quality dimensions: - Detail: Vividness and specificity of imagery - Life: Living, breathing quality and vitality - Music: Sound quality and rhythmic elements - Mystery: Ambiguity, layers, reader engagement - Sufficient Thought: Intellectual depth and insight - Surprise: Unexpected elements, fresh perspectives - Syntax: Sentence structure and line breaks - Unity: Coherence and wholeness Args: poem_id: Poem identifier (ID or title) dimensions: Optional list of specific dimensions to grade (default: all 8) Returns: Dictionary with: - poem: Poem data (id, title, content) - dimensions: Quality dimensions with descriptions - instructions: Grading guidance for agent Example: >>> result = await grade_poem_quality("antlion") >>> # Agent grades result['poem'] on result['dimensions'] >>> # Agent returns scores 0-10 with reasoning for each """ if _catalog is None: raise RuntimeError("Enrichment tools not initialized.") # Get poem poem = _catalog.index.get_poem(poem_id) if not poem: return { "success": False, "error": f"Poem not found: {poem_id}", } # Load content if needed content = poem.content if not content: try: poem_path = Path(poem.file_path) full_content = poem_path.read_text(encoding='utf-8') if '---' in full_content: parts = full_content.split('---', 2) if len(parts) >= 3: content = parts[2].strip() else: content = full_content else: content = full_content except Exception as e: return { "success": False, "error": f"Failed to load poem content: {e}", } # Define all quality dimensions all_dimensions = { "Detail": "Vividness and specificity of imagery - concrete sensory details vs abstract generalities", "Life": "Living, breathing quality - vitality, energy, movement vs static or lifeless", "Music": "Sound quality - rhythm, sonic patterns, musicality of language", "Mystery": "Ambiguity and layers - capacity to engage reader in meaning-making", "Sufficient Thought": "Intellectual depth - insight, wisdom, meaningful observation", "Surprise": "Unexpected elements - fresh perspectives, original connections", "Syntax": "Sentence structure and line breaks - how grammar serves meaning", "Unity": "Coherence and wholeness - integration of parts into cohesive whole", } # Filter to requested dimensions if specified if dimensions: dimensions_to_grade = {k: v for k, v in all_dimensions.items() if k in dimensions} if not dimensions_to_grade: return { "success": False, "error": f"Invalid dimensions. Valid options: {list(all_dimensions.keys())}", } else: dimensions_to_grade = all_dimensions # Format dimensions for agent dimensions_data = [ {"name": name, "description": desc} for name, desc in dimensions_to_grade.items() ] instructions = """Grade this poem on each quality dimension. For each dimension, provide: - **dimension**: Dimension name (exactly as listed) - **score**: Integer 0-10 - 0-3: Absent or poor - 4-6: Adequate, functional - 7-8: Strong, effective - 9-10: Exceptional, masterful - **reasoning**: Brief evidence (1-2 sentences, cite specific lines) Be precise and evidence-based. Reference specific techniques or lines when explaining scores.""" logger.info(f"Prepared quality grading data for '{poem.title}' ({len(dimensions_to_grade)} dimensions)") return { "success": True, "poem": { "id": poem.id, "title": poem.title, "content": content, "state": poem.state, }, "dimensions": dimensions_data, "instructions": instructions, "dimensions_count": len(dimensions_to_grade), }
• src/poetry_mcp/server.py:496-540 (registration)

  MCP registration of the grade_poem_quality tool using @mcp.tool() decorator. This wrapper delegates to the core implementation imported as _grade_poem_quality from enrichment_tools.py.
  @mcp.tool() async def grade_poem_quality( poem_id: str, dimensions: Optional[List[str]] = None, ) -> dict: """ Prepare poem and quality rubric for grading by the MCP agent. Returns poem content and quality dimension descriptions for YOU (the agent) to grade. YOU provide scores (0-10) and reasoning for each dimension. 8 Quality Dimensions: - Detail: Vividness and specificity of imagery - Life: Living, breathing quality and vitality - Music: Sound quality and rhythmic elements - Mystery: Ambiguity, layers, reader engagement - Sufficient Thought: Intellectual depth and insight - Surprise: Unexpected elements, fresh perspectives - Syntax: Sentence structure and line breaks - Unity: Coherence and wholeness Args: poem_id: Poem identifier (ID or title) dimensions: Optional list of specific dimensions to grade (default: all 8) Returns: Dictionary with: - poem: Poem data (title, content) - dimensions: Quality dimensions with descriptions - instructions: Grading guidance Example workflow: ``` # 1. Get poem and rubric data = await grade_poem_quality("antlion") # 2. YOU grade data['poem'] on data['dimensions'] # 3. YOU provide scores 0-10 with reasoning for each dimension # - 0-3: Absent/poor # - 4-6: Adequate # - 7-8: Strong # - 9-10: Exceptional ``` """ return await _grade_poem_quality(poem_id, dimensions)
• src/poetry_mcp/tools/enrichment_tools.py:753-762 (helper)

  Helper dictionary defining the 8 quality dimensions with descriptions, used to prepare grading rubric for the agent.
  all_dimensions = { "Detail": "Vividness and specificity of imagery - concrete sensory details vs abstract generalities", "Life": "Living, breathing quality - vitality, energy, movement vs static or lifeless", "Music": "Sound quality - rhythm, sonic patterns, musicality of language", "Mystery": "Ambiguity and layers - capacity to engage reader in meaning-making", "Sufficient Thought": "Intellectual depth - insight, wisdom, meaningful observation", "Surprise": "Unexpected elements - fresh perspectives, original connections", "Syntax": "Sentence structure and line breaks - how grammar serves meaning", "Unity": "Coherence and wholeness - integration of parts into cohesive whole", }
• src/poetry_mcp/server.py:23-32 (registration)

  Import of the grade_poem_quality function from enrichment_tools.py, aliased as _grade_poem_quality for use in the MCP tool wrapper.
  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, )