Skip to main content
Glama
Poetry MCP Server

Poetry MCP Server

Poetry MCP Server

A Model Context Protocol (MCP) server for managing poetry catalogs, nexuses, and submissions.

Status: Core functionality complete - Catalog management, enrichment tools, and LLM-powered analysis operational

Overview

Poetry MCP is a specialized MCP server that treats poems as artifacts (not knowledge graph nodes), providing:

  • State-based catalog tracking (fledgeling → completed)

  • Thematic connections via "nexuses" (themes, motifs, forms)

  • Quality scoring on multiple dimensions

  • Submission tracking to literary venues

  • Influence lineage tracking

Architecture: No database - BASE files define VIEW DEFINITIONS (queries), actual data lives in markdown frontmatter. On startup, the MCP server scans poem files and loads frontmatter into Pydantic models in memory.

Three Types of Metadata

Poetry MCP uses three complementary ways to evaluate poems:

Type

What It Measures

Example

Nexus (binary)

What does this poem contain?

Contains water imagery (yes/no)

Quality (scalar)

What does this poem achieve?

Scores 8/10 on "Surprise"

Influence (lineage)

Where does this poem come from?

Descended from William Bronk

8 Universal Quality Dimensions: Detail, Life, Music, Mystery, Sufficient Thought, Surprise, Syntax, Unity. The MCP server provides grade_poem_quality() which returns poem content and quality rubrics for agent-based scoring (0-10 scale with reasoning).

Architectural Philosophy

Poetry workflow requires catalog-based tracking (poems as artifacts with states/metadata) rather than knowledge graph systems (atomic ideas with semantic links).

Why poems aren't notes:

  • Move through production states (fledgeling → completed)

  • Connect to thematic/formal nexuses (not logical relationships)

  • Get scored on quality dimensions (scalar ratings)

  • Have submission histories (transactions with venues)

  • Descend from influences (lineage, not logic)

Vault Directory Structure

The Poetry vault organizes poems and metadata across specialized directories:

/Poetry/
├── catalog/           # State-based poem organization (381 poems)
│   ├── catalog.base   # View definition for all poems
│   ├── Completed/     # 49 poems
│   ├── Fledgelings/   # 172 poems
│   ├── Needs Research/# 10 poems
│   ├── Risks/         # 22 poems
│   └── Still Cooking/ # 65 poems
├── nexus/             # Thematic/formal connection points
│   ├── nexus.base     # Registry of available nexuses
│   ├── themes/        # 17 thematic connections
│   ├── forms/         # 4 structural patterns
│   └── motifs/        # 4 compositional patterns
├── Qualities/         # 8 universal quality dimensions
│   └── qualities.base # Quality definitions and rubrics
├── influences/        # Writer/movement/aesthetic lineage
│   └── influences.base
├── techniques/        # Generative methods and processes
│   └── techniques.base
├── venues/            # Publication venue metadata (22 venues)
│   ├── venues.base    # Venue registry (payment, response time, aesthetic)
│   └── [venue files]  # Individual venue profiles
├── Submissions/       # Historical submission records
│   ├── Submissions.base # Submission tracking
│   └── [submission files] # Date_PoemTitle_VenueName.md
├── analysis/          # Research documents and comparisons
└── craft-notes/       # Personal aphorisms and principles

Personal Directories: Users may create additional directories for personal workflow (e.g., journal/, scripts/, transitional poem collections). These are not indexed by the MCP server.

Nexus Taxonomy

Nexuses represent binary connections - a poem either contains a nexus or doesn't. The taxonomy has three categories:

  • Forms (4): Structural patterns defining how a poem is arranged (American Sentence, Free Verse, Prose Poem, Catalog Poem)

  • Themes (17): Subject matter and imagery systems (Water-Liquid Imagery, Body-Mouth, etc.)

  • Motifs (4): Cross-nexus compositional patterns requiring multiple themes (American Grotesque, Failed Transcendence, etc.)

Note: The specific nexuses evolve over time as new patterns emerge in the poetry practice. See nexus/ directory for current instances.

Architecture: Agent-Based Analysis

This MCP server follows the data provider pattern:

Server Responsibilities:

  • Catalog management (scan, index, search)

  • Data access (poems, nexuses, quality rubrics)

  • Data modification (update tags, move files)

Agent (Claude) Responsibilities:

  • Poetry analysis (theme detection)

  • Quality assessment (grading dimensions)

  • Batch processing (multiple poem analysis)

Why This Pattern?

  • ✅ No API keys needed in server

  • ✅ Server stays lightweight and data-focused

  • ✅ Agent uses natural language understanding

  • ✅ Transparent analysis (you see the reasoning)

  • ✅ Flexible - agent can adjust analysis approach

Workflow:

1. Tool call → Server returns poem + analysis context
2. Agent analyzes data using natural language reasoning
3. Agent provides structured results (themes/scores/confidence)
4. User applies results with data modification tools

Requirements

  • Python 3.10 or higher

  • FastMCP 0.2.0+

  • Pydantic 2.0+

Note: No API keys needed! The MCP server provides data, your MCP client (Claude Desktop) performs analysis.

Development Setup

Installation

# Clone repository
git clone <repository-url>
cd poetry-mcp

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=poetry_mcp --cov-report=html

# Run specific test file
pytest tests/test_models.py -v

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

Project Structure

src/poetry_mcp/
├── __init__.py          # Package metadata
├── server.py            # FastMCP server entry point and tool registration
├── config.py            # Configuration management
├── errors.py            # Custom exceptions
├── models/              # Pydantic data models
│   ├── poem.py          # Poem model with frontmatter
│   ├── nexus.py         # Nexus and registry models
│   ├── results.py       # Search and sync results
│   └── enrichment.py    # LLM response models
├── parsers/             # BASE file and frontmatter parsers
│   ├── base_parser.py   # Generic BASE file parser
│   ├── nexus_parser.py  # Nexus registry loader
│   └── frontmatter.py   # YAML frontmatter extraction
├── writers/             # Frontmatter modification tools
│   └── frontmatter_writer.py  # Atomic frontmatter updates
├── catalog/             # Catalog management and indexing
│   ├── catalog.py       # Main catalog class
│   └── index.py         # In-memory search indices
└── tools/               # MCP tool implementations
    └── enrichment_tools.py  # All enrichment operations

tests/
├── conftest.py          # Pytest fixtures
└── fixtures/            # Test data
    ├── base_files/      # Sample .base files
    └── markdown/        # Sample poem files

docs/
├── CANONICAL_TAGS.md    # Quick reference for all canonical tags (forms, themes, motifs)
└── FRONTMATTER_SCHEMA.md # Poem frontmatter property definitions

Configuration

Configuration is loaded from ~/.config/poetry-mcp/config.yaml:

vault:
  path: /path/to/Poetry
  catalog_dir: catalog
  nexus_dir: nexus

search:
  default_limit: 20
  case_sensitive: false

logging:
  level: INFO
  file: ~/.config/poetry-mcp/poetry-mcp.log

MCP Client Setup

Poetry MCP implements the Model Context Protocol (MCP) standard and can be used with any MCP-compatible client.

Configuration Format

MCP clients typically use JSON configuration to connect to servers. Add this to your MCP client's config:

{
  "mcpServers": {
    "poetry-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/poetry-mcp",
        "run",
        "poetry-mcp"
      ],
      "env": {
        "POETRY_VAULT_PATH": "/path/to/your/Poetry/vault"
      }
    }
  }
}

Alternative: Using python directly

If you have the package installed globally:

{
  "mcpServers": {
    "poetry-mcp": {
      "command": "python",
      "args": ["-m", "poetry_mcp.server"],
      "env": {
        "POETRY_VAULT_PATH": "/path/to/your/Poetry/vault"
      }
    }
  }
}

Client-Specific Setup

Claude Desktop:

  • Config location (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

  • Config location (Windows): %APPDATA%\Claude\claude_desktop_config.json

  • After updating config, restart Claude Desktop completely

Other MCP Clients:

  • Consult your client's documentation for config file location

  • Use the JSON format above with your specific vault path

Verification

After configuring your MCP client:

  1. Restart the client application

  2. Start a new conversation/session

  3. Check that poetry-mcp tools are available

  4. Try: "What poetry tools are available?"

  5. Try: "Get catalog stats" - should show your poem count

Troubleshooting

Server won't start:

  • Verify POETRY_VAULT_PATH points to correct directory

  • Check the vault has a catalog/ subdirectory

  • Review client logs for error messages

No poems found:

  • Run sync_catalog tool first to index poems

  • Verify vault path is correct

  • Check markdown files have proper frontmatter (see FRONTMATTER_SCHEMA.md)

Tools not appearing:

  • Completely restart your MCP client

  • Validate JSON config syntax

  • Verify uv or python is in system PATH

Quick Start

Basic Usage

# Start the server (auto-syncs catalog on startup)
poetry-mcp start

# Or run directly with Python
python -m poetry_mcp.server

Example Workflows

Agent-Based Theme Analysis:

# 1. Server provides poem and theme data
data = await find_nexuses_for_poem("my-poem-id", max_suggestions=3)

# 2. Agent (Claude) analyzes the poem against available themes
# Agent sees:
#   - data['poem']: {id, title, content, current_tags}
#   - data['available_themes']: [{name, canonical_tag, description}, ...]
#   - data['instructions']: Analysis guidance

# 3. Agent identifies matching themes with confidence:
# Example agent response:
# "This poem strongly engages with:
#  - Water-Liquid (0.85): 'river flows through ancient stones'
#  - Body-Bones (0.67): skeletal imagery in stanza 2"

# 4. User applies suggested tags
await link_poem_to_nexus("my-poem-id", "Water-Liquid", "theme")

Batch Theme Discovery:

# 1. Get poems needing enrichment
data = await get_poems_for_enrichment(max_poems=10)

# 2. Agent analyzes data['poems'] against data['available_themes']
# Agent suggests themes for each poem

# 3. User applies high-confidence tags
for poem in analyzed_poems:
    await link_poem_to_nexus(poem['id'], suggested_theme, "theme")

Agent-Based Quality Grading:

# 1. Server provides poem and quality rubric
data = await grade_poem_quality("my-poem-id")

# 2. Agent grades data['poem'] on data['dimensions']
# Agent sees 8 quality dimensions with descriptions
# Agent provides scores 0-10 with evidence

# Example agent response:
# "Quality Assessment:
#  - Detail: 8/10 - Strong sensory imagery ('ancient stones worn smooth')
#  - Life: 6/10 - Adequate vitality but some static passages
#  - Music: 9/10 - Excellent rhythm and sonic patterns"

Maintenance:

# Sync wikilinks with tags
result = await sync_nexus_tags("my-poem-id", direction="both")
print(f"Tags added: {result['tags_added']}")
print(f"Links added: {result['links_added']}")

# Move poem to completed state
result = await move_poem_to_state("my-poem-id", "completed")
print(f"Moved to: {result['new_path']}")

Available Tools

Catalog Management

  • sync_catalog - Scan vault and build in-memory catalog index

  • get_poem - Retrieve poem by ID or title

  • search_poems - Search with filters (query, states, forms, tags)

  • find_poems_by_tag - Find poems by tag combinations

  • list_poems_by_state - List poems in specific states

  • get_catalog_stats - Get catalog statistics and health metrics

  • get_server_info - Server status and configuration

Enrichment Tools

  • get_all_nexuses - Browse available themes, motifs, and forms

  • link_poem_to_nexus - Add nexus tags to poem frontmatter

  • sync_nexus_tags - Sync [[Nexus]] wikilinks with frontmatter tags

  • move_poem_to_state - Move poems between state directories

Agent Analysis Tools

These tools return data for YOUR (the agent's) analysis

  • find_nexuses_for_poem - Get poem + themes for agent to analyze and suggest matches

  • get_poems_for_enrichment - Get batch of poems for agent to analyze and suggest themes

  • grade_poem_quality - Get poem + quality rubric for agent to grade

Development Roadmap

  • Phase 0: Project Setup - Dependencies, structure, tooling

  • Phase 1: Core Data Models - Pydantic models for Poem, Nexus, Quality, etc.

  • Phase 2: Configuration System - YAML config loading and validation

  • Phase 3: BASE File Parser - Parse Obsidian YAML files

  • Phase 4: Catalog Management - Scan filesystem, index poems

  • Phase 5: MCP Tools Phase 1 - Core catalog/search tools

  • Phase 6: MCP Server Setup - FastMCP initialization and tool registration

  • Phase 7 (Sprint 1): Enrichment Foundation - Frontmatter writer, nexus registry

  • Phase 8 (Sprint 2): LLM Integration - Theme detection, batch enrichment

  • Phase 9 (Sprint 4): Maintenance Tools - Tag sync, state moves, quality grading

  • Phase 10 (Sprint 3): Advanced Discovery - Similarity search, cluster analysis

See IMPLEMENTATION_CHECKLIST.md for detailed progress tracking.

Data Synchronization

How BASE File Changes Work

Poetry MCP loads BASE files into memory as Pydantic models on startup. Understanding the sync behavior:

v1 (Current - Phases 0-6):

1. Server starts → Parse BASE files → Create Pydantic models in RAM
2. Models stay in memory during server lifetime
3. Edit BASE file in Obsidian → Models remain unchanged
4. Restart server → Re-parse BASE files → Fresh models loaded

To see your changes: Simply restart the MCP server (< 3 seconds). Claude Desktop will reconnect automatically.

Future Convenience Features (v2+)

Manual Reload Tool

Call from Claude when you've made BASE file changes:

# No server restart needed
reload_catalog()

Benefits:

  • Instant refresh without disconnecting Claude

  • Selective reloading (only changed files)

  • Maintains conversation context

Automatic File Watching

Real-time synchronization using the watchdog library:

# config.yaml
performance:
  watch_files: true
  watch_debounce_seconds: 2.0

Features:

  • Detects BASE file changes automatically

  • Debouncing (waits for all saves to complete)

  • Smart reload (only changed files)

  • Handles concurrent modifications safely

When you edit in Obsidian:

  1. Save changes → File watcher detects change

  2. Waits 2 seconds (Obsidian may save multiple files)

  3. Reloads changed BASE files

  4. Updates Pydantic models in memory

  5. Changes visible in next Claude query

Why Not in v1?

Complexity trade-offs:

  • File watching adds dependencies (watchdog library)

  • Requires debouncing logic (multiple rapid saves)

  • Needs concurrent modification handling

  • Adds error recovery complexity

Current approach prioritizes:

  • ✅ Simple implementation for Phases 0-6

  • ✅ Fast manual restart (2-3 seconds total)

  • ✅ Reliable data consistency

  • ✅ Easier debugging during development

v2 can add these features based on user feedback.

License

MIT

Available Tools

14 tools
find_nexuses_for_poemA

Prepare poem and theme data for analysis by the MCP agent.

Returns poem content and available themes for YOU (the agent) to analyze. YOU identify which themes match the poem and provide confidence scores.

Args: poem_id: Poem identifier (ID or title) max_suggestions: Maximum number of theme suggestions requested

Returns: Dictionary with: - poem: Poem data (title, content, current_tags) - available_themes: Theme options with descriptions - instructions: Analysis guidance

Example workflow: ``` # 1. Get data for analysis data = await find_nexuses_for_poem("antlion", max_suggestions=3)

# 2. YOU analyze data['poem'] against data['available_themes']
# 3. YOU identify matching themes with confidence scores
# 4. User applies tags with link_poem_to_nexus()
```

Inputs: poem_id (required), max_suggestions. Returns: object

find_poems_by_tagC

Find poems by tags.

Args: tags: List of tags to match match_mode: "all" (poems must have all tags) or "any" (at least one tag) states: Optional filter by states limit: Maximum number of results

Returns: List of matching poems

Inputs: tags (required), match_mode, states, limit. Returns: result

get_all_nexusesA

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}")

Inputs: no named parameters. Returns: Complete nexus registry organized by category. Returned by get_all_nexuses() to…

get_catalog_statsC

Get catalog statistics.

Returns: CatalogStats with counts, metrics, and health information

Inputs: no named parameters. Returns: Catalog statistics and health metrics. Returned by get_catalog_stats() tool.

get_poemC

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

Inputs: identifier (required), include_content. Returns: result

get_poems_for_enrichmentA

Get batch of poems needing theme enrichment for agent analysis.

Returns poems with minimal or no tags for YOU (the agent) to analyze. YOU suggest which themes apply to each poem.

Args: poem_ids: List of poem IDs (None = all untagged/lightly-tagged poems) max_poems: Maximum poems to return (default 50)

Returns: Dictionary with: - poems: List of poem data (id, title, content, current_tags) - available_themes: Theme options with descriptions - instructions: Batch analysis guidance

Example workflow: ``` # 1. Get poems needing enrichment data = await get_poems_for_enrichment(max_poems=10)

# 2. YOU analyze data['poems'] against data['available_themes']
# 3. YOU suggest 1-3 themes for each poem with confidence scores
# 4. User applies high-confidence tags with link_poem_to_nexus()
```

Inputs: poem_ids, max_poems. Returns: object

get_server_infoB

Get server information and status.

Returns: Dictionary with server metadata

Inputs: no named parameters. Returns: object

grade_poem_qualityA

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
```

Inputs: poem_id (required), dimensions. Returns: object

list_poems_by_stateB

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

Inputs: state (required), sort_by, limit. Returns: result

move_poem_to_stateA

Move a poem to a different state directory and update frontmatter.

Moves the poem file between state directories (Completed, Fledgelings, etc.) and updates the frontmatter state field. Handles backup files automatically.

Args: poem_id: Poem identifier (ID or title) new_state: Target state (completed, fledgeling, still_cooking, etc.)

Returns: Dictionary with move operation results

Example: Promote a poem to completed: result = await move_poem_to_state( poem_id="antlion", new_state="completed" ) print(f"Moved from {result['old_state']} to {result['new_state']}") print(f"New path: {result['new_path']}")

Inputs: poem_id (required), new_state (required). Returns: object

search_poemsB

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

Inputs: query (required), states, forms, tags, +2 more. Returns: Result from search_poems operation. Contains matched poems and query metadata.

sync_catalogA

Synchronize catalog from filesystem.

Scans all markdown files in catalog/ directory and builds in-memory indices. This should be called before using other catalog tools.

Args: force_rescan: If True, rescan all files even if already loaded

Returns: SyncResult with statistics about the sync operation

Inputs: force_rescan. Returns: Result from sync_catalog operation. Reports statistics about catalog synchroniz…

sync_nexus_tagsA

Synchronize [[Nexus]] links in poem body with frontmatter tags.

Analyzes the poem's content for [[Nexus Name]] wikilinks and syncs them with the frontmatter tags field. Can sync in either direction or both.

Args: poem_id: Poem identifier (ID or title) direction: Sync direction - "links_to_tags", "tags_to_links", or "both"

Returns: Dictionary with sync results and any conflicts found

Example: Sync wikilinks to tags: result = await sync_nexus_tags( poem_id="antlion", direction="links_to_tags" ) print(f"Tags added: {result['tags_added']}") print(f"Conflicts: {result['conflicts']}")

Inputs: poem_id (required), direction. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists: find_nexuses_for_poem and get_poems_for_enrichment both prepare poems for theme analysis by the agent, differing mainly in single vs. batch processing. Similarly, get_poem and list_poems_by_state both retrieve poems but with different filtering approaches. The descriptions help clarify these distinctions, preventing major confusion.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern with clear, descriptive names. Verbs like get, find, list, sync, link, move, grade, and search are used appropriately and predictably throughout the set. There are no deviations in naming conventions, making the tool set highly readable and intuitive.

    Tool Count5/5

    With 14 tools, the server is well-scoped for managing a poetry catalog, covering CRUD operations (get, search, list), state management (move_poem_to_state), tagging (link_poem_to_nexus, sync_nexus_tags), analysis preparation (find_nexuses_for_poem, grade_poem_quality), and system tasks (sync_catalog, get_server_info). Each tool serves a clear purpose without redundancy, fitting the domain's complexity.

    Completeness5/5

    The tool set provides complete coverage for poetry catalog management, including poem retrieval (get_poem, search_poems, list_poems_by_state), state transitions (move_poem_to_state), tagging workflows (link_poem_to_nexus, sync_nexus_tags, get_all_nexuses), analysis support (find_nexuses_for_poem, grade_poem_quality, get_poems_for_enrichment), and system operations (sync_catalog, get_server_info, get_catalog_stats). There are no obvious gaps; agents can perform end-to-end tasks without dead ends.

    Related MCP Connectors