诗歌管理服务器

---
title: My Poem
tags: [water, bones, childhood]  # ✅ Must match nexus canonical_tags
status: fledgeling               # ✅ Workflow metadata → dedicated field
form: american-sentence          # ✅ Structural metadata → dedicated field
---

/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

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

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

# Install with dev dependencies (uv installs the dev dependency group)
uv sync

# Run all tests
uv run pytest

# Run with coverage (configured by default)
uv run pytest --cov-report=html

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

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

src/poetry_mcp/
├── __init__.py          # Package metadata
├── server.py            # Thin @mcp.tool wrappers + main() + catalog getters
├── utils.py             # Shared helpers (e.g. slugify_filename)
├── config.py            # Configuration management (51% coverage)
├── errors.py            # Custom exceptions (100% coverage)
├── models/              # Pydantic data models (90-100% coverage)
│   ├── poem.py          # Poem model with state validation
│   ├── nexus.py         # Nexus and NexusRegistry models
│   ├── quality.py       # Quality scores and QualityRegistry
│   ├── venue.py         # Venue metadata model
│   ├── submission.py    # Submission tracking model
│   ├── influence.py     # Influence lineage model
│   ├── results.py       # Search and sync results
│   └── enrichment.py    # LLM response models
├── parsers/             # Frontmatter and registry parsers
│   ├── frontmatter_parser.py  # YAML extraction (96% coverage)
│   ├── nexus_parser.py        # Nexus registry (100% coverage)
│   └── venue_parser.py        # Venue registry (97% coverage)
├── writers/             # Frontmatter modification tools
│   └── frontmatter_writer.py  # Atomic updates (100% coverage)
├── catalog/             # Catalog management and indexing
│   └── catalog.py       # Main catalog class with search
└── tools/               # Tool impls (server.py wraps these) — see docs/ARCHITECTURE.md
    ├── catalog_tools.py     # sync_catalog, get_poem, query_poems, get_server_info
    ├── submission_tools.py  # sync/list/update submissions
    ├── venue_tools.py       # sync/list/get/regenerate venues
    ├── nexus_tools.py       # refresh/validate/create/delete nexus
    ├── quality_tools.py     # commit/get quality scores
    ├── enrichment_tools.py  # nexus enrichment + tag operations
    ├── chain_tools.py       # poem chains
    └── similarity_tools.py  # find_similar_poems

tests/                   # 343 tests, 100% pass rate
├── conftest.py          # Pytest fixtures and helpers
├── test_models.py       # Model validation tests (24 tests)
├── test_config.py       # Config system tests (47 tests)
├── test_venue_parser.py # Venue parser tests (24 tests)
├── test_venue_parser_edge_cases.py # Edge case tests (12 tests)
├── test_enrichment.py   # Enrichment workflow tests (16 tests)
├── test_frontmatter_writer.py  # Writer tests (16 tests)
├── test_frontmatter_writer_errors.py # Error path tests (22 tests)
├── test_quality_scoring.py     # Quality tools tests (22 tests)
└── fixtures/            # Test data and sample poems

docs/
├── ARCHITECTURE.md           # Tool/server layering + conventions (read before editing tools)
├── FRONTMATTER_SCHEMA.md     # Frontmatter property definitions
├── IMPLEMENTATION_CHECKLIST.md  # Development progress tracking
└── TEST_STATUS.md            # Test suite status and coverage

vault:
  # Required: Absolute path to your Poetry vault
  path: /path/to/your/Poetry/vault

  # Optional: Subdirectory names (defaults shown)
  catalog_dir: catalog
  nexus_dir: nexus
  qualities_dir: Qualities
  venues_dir: venues
  influences_dir: influences

search:
  # Default number of results (1-100)
  default_limit: 50

  # Case-sensitive search
  case_sensitive: false

logging:
  # Log level: DEBUG, INFO, WARNING, ERROR
  level: INFO

  # Log file path (null = console only)
  file: null
  # file: ~/.config/poetry-mcp/poetry-mcp.log

  # Log message format
  format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

performance:
  # File watching for auto-reload (requires watchdog library)
  watch_files: false

  # Debounce time for file changes (seconds)
  watch_debounce_seconds: 2.0

  # Cache expiry (seconds)
  cache_expiry_seconds: 3600

# Tag validation settings
validation:
  # Automatically validate tags on server startup (after initial sync)
  auto_validate_on_sync: true

  # Enforce strict tag policy (tags must match nexus canonical_tags)
  strict_mode: true

export POETRY_VAULT_PATH="/path/to/your/Poetry/vault"

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

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

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

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

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

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

# 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"

# 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']}")

1. Server starts → Scans catalog/ directory → Parses frontmatter → Creates Pydantic models in RAM
2. Models stay in memory during server lifetime
3. Edit poem frontmatter in Obsidian → Models remain unchanged
4. Restart server → Re-scans files → Fresh models loaded

# No server restart needed
reload_catalog()

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