诗歌MCP服务器

用于管理诗歌目录、连结和提交的模型上下文协议（MCP）服务器。

状态： 生产就绪-实施了17个工具，通过了343次测试（覆盖率85%），所有核心功能均已运行

概述

Poetry MCP是一个专门的MCP服务器，它将诗歌视为 人工制品 （非知识图节点），提供：

基于状态的目录跟踪（fledgeling→ 已完成）
通过“nexuses”（主题、图案、形式）进行主题连接
多维度质量评分
文学场所的投稿跟踪
影响谱系追踪

架构： 没有数据库，所有数据都存在于markdown frontmatter中。启动时，MCP服务器扫描诗歌文件，并将frontmatter加载到内存中的Pydantic模型中。

元数据的三种类型

诗歌MCP使用三种互补的方法来评估诗歌：

类型	测量内容	示例
纽带（二进制）	这首诗是什么包含？	包含水图像（是/否）
质量（标量）	这首诗是什么实现？	“惊喜”得分8/10
影响（世系）	这首诗在哪里来自？	威廉·布朗克的后裔

8通用质量尺寸： 细节、生活、音乐、神秘、充分思考、惊喜、句法、统一。MCP服务器提供 grade_poem_quality() 它返回诗歌内容和质量量规，用于基于主体的评分（0-10分，带推理）。

建筑哲学

诗歌工作流程需要 基于目录的跟踪 （诗歌作为具有状态/元数据的人工制品）而不是知识图系统（具有语义链接的原子思想）。

为什么诗不是笔记：

在生产状态中移动（萌芽→ 已完成）
连接到主题/正式的关系（不是逻辑关系）
在质量维度上获得评分（标量评级）
有提交历史记录（与场馆的交易）
受影响的后裔（血统，而非逻辑）

Vault目录结构

诗歌库跨专业目录组织诗歌和元数据：

/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

个人目录： 用户可以为个人工作流创建附加目录（例如。， journal/, scripts/，过渡诗集）。MCP服务器不会对这些内容进行索引。

Nexus分类学

Nexuse代表二元连接——一首诗要么包含一个连接，要么不包含。分类法有三个类别：

表单（4）：定义诗歌排列方式的结构模式（美国句子、自由诗、散文诗、目录诗）
主题（17）：主题和成像系统（水液成像、体口等）
主题（4）：需要多个主题的交叉关系构图模式（美国怪诞、失败的超越等）

注：随着诗歌实践中新模式的出现，特定的关系会随着时间的推移而演变。看 nexus/ 当前实例的目录。

架构：基于代理的分析

此MCP服务器遵循 数据提供程序 图案：

服务器职责：

目录管理（扫描、索引、搜索）
数据访问（诗歌、无性恋、质量评价标准）
数据修改（更新标签、移动文件）

代理人（克劳德）职责：

诗歌分析（主题检测）
质量评估（分级尺寸）
批处理（多首诗分析）

为什么是这种模式？

✅ 服务器中不需要API密钥
✅ 服务器保持轻量级和以数据为中心
✅ Agent使用自然语言理解
✅ 透明的分析（你可以看到推理）
✅ 灵活-代理可以调整分析方法

工作流程：

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

需求

Python 3.10或更高版本
FastMCP 0.2.0+
Pydantic 2.0+
PyYAML用于配置

注：不需要API密钥！MCP服务器提供数据，您的MCP客户端（Claude Desktop）执行分析。

测试与质量

测试覆盖范围： 85%（343次测试，100%通过率）
测试框架： 带夹具的pytest和参数化测试
质量工具： 黑色，褶边，mypy
CI/CD： 已准备好与GitHub Actions集成

看 TEST_STATUS.md 有关详细的测试套件信息。

开发环境设置

安装

# Clone repository
git clone 
cd poetry-mcp

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

运行测试

# 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

代码质量

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

项目结构

src/poetry_mcp/
├── __init__.py          # Package metadata
├── server.py            # FastMCP server (8 core tools, 61% coverage)
├── 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/               # MCP tool implementations
    └── enrichment_tools.py  # All enrichment operations (90% coverage)

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/
├── CANONICAL_TAGS.md         # Canonical tag reference
├── FRONTMATTER_SCHEMA.md     # Frontmatter property definitions
├── IMPLEMENTATION_CHECKLIST.md  # Development progress tracking
└── TEST_STATUS.md            # Test suite status and coverage

配置

Poetry MCP支持多种配置方法，并具有自动回退功能：

配置优先级（从高到低）

YAML配置文件 -最灵活，支持所有选项
环境变量 -快速设置vault路径
交互式设置 -首次运行向导（在终端中运行时）
默认位置 - ~/.local/share/obsidian/art/Poetry （如果存在）

配置文件位置

Poetry MCP按顺序检查这些位置：

$POETRY_MCP_CONFIG -指向配置文件的环境变量
~/.config/poetry-mcp/config.yaml -XDG配置目录（推荐）
~/.poetry-mcp/config.yaml -主目录回退

完整配置文件示例

看 config.yaml.example 在完整模板的存储库中：

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: 20

  # 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

使用环境变量快速设置

仅使用环境变量的最低配置：

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

所有其他设置将使用默认值。这是最快的开始方式。

MCP客户端设置

Poetry MCP实现了模型上下文协议（MCP）标准，可以与任何兼容MCP的客户端一起使用。

配置格式

MCP客户端通常使用JSON配置连接到服务器。将此添加到MCP客户端的配置中：

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

替代方案：直接使用python

如果您已全局安装该软件包：

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

客户端特定设置

克劳德桌面：

配置位置（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
配置位置（Windows）： %APPDATA%\Claude\claude_desktop_config.json
更新配置后，完全重新启动Claude Desktop

其他MCP客户端：

有关配置文件的位置，请参阅客户的文档
将上面的JSON格式与您的特定vault路径一起使用

验证

配置MCP客户端后：

重新启动客户端应用程序
开始新的对话/会话
检查诗歌mcp工具是否可用
试试：“有什么诗歌工具？”
试试：“获取目录统计数据”-应该显示你的诗数

故障排除

服务器无法启动：

验证 POETRY_VAULT_PATH 指向正确的目录
检查保险库是否有 catalog/ 子目录
查看客户端日志中的错误消息

未找到诗歌：

跑 sync_catalog 诗歌索引的首选工具
验证vault路径是否正确
检查markdown文件是否具有正确的frontmatter（请参阅frontmatter_SCHEMA.md）

工具未出现：

完全重新启动MCP客户端
验证JSON配置语法
验证 uv 或 python 在系统路径中

快速开始

基本用法

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

可用工具

目录管理

同步目录 -扫描vault并构建内存目录索引
get_poem -按ID或标题检索诗歌
搜索对象 -使用过滤器（查询、状态、表单、标签）进行搜索
find_poems_by_tag -按标签组合查找诗歌
list_poems_by_state -列出特定州的诗歌
get_catalog_stats -获取目录统计信息和运行状况指标
get_server_info -服务器状态和配置

丰富工具

获取所有信息 -浏览可用的主题、图案和形式
link_poem_to_nexos -将nexus标签添加到诗歌封面
sync_nexus_tags -将\[\[Nexus\]\]维基链接与frontmatter标签同步
move_poem_to_state -在州目录之间移动诗歌

代理分析工具

*这些工具返回数据供您（代理）分析*

find_nexoses_for_poem -获取诗歌+主题，供代理人分析和建议匹配
get_poems_for_enrichment -收集一批诗歌，供代理人分析和建议主题
质量等级 -获得诗歌+质量量规，供代理人评分

质量评分工具

*管理8个通用维度的诗歌质量分数*

委托_质量_核心 -为诗歌正面写质量分数并进行验证
get_quality_scores -从一首诗中检索现有的质量分数
发现高得分 -按质量维度和最低分数查询诗歌
列表_质量_尺寸 -获取可用的质量尺寸和描述

提交跟踪工具

*追踪文学场所的提交历史*

获取_菜单 -按名称检索场地详细信息
list_venues -使用过滤器浏览所有跟踪的场馆
get_submission_history -查看诗歌或场地的提交历史记录
计划_提交 -创建计划提交记录

发展路线图

已完成的阶段

\[x\] 阶段0： 项目设置-依赖关系、结构、工具、测试基础设施
\[x\] 第一阶段： 核心数据模型-诗歌、关系、质量、地点、提交的双关语模型
\[x\] 第二阶段： 配置系统-具有多源发现功能的YAML配置（覆盖率51%）
\[x\] 第三阶段： 解析器-前线（96%）、场地（97%）、Nexus（100%）覆盖
\[x\] 第四阶段： 目录管理-扫描文件系统、索引诗歌、搜索操作
\[x\] 第五阶段： MCP工具-核心目录/搜索工具（已实施17个工具）
\[x\] 第6阶段： MCP服务器-FastMCP初始化和工具注册
\[x\] 第7阶段： Enrichment Foundation-Frontmatter撰稿人（100%），nexus注册表
\[x\] 第8阶段： 富集发现-主题检测、批量富集工作流
\[x\] 第9阶段： 维护工具-标签同步、状态移动、质量分级
\[x\] 第10阶段： 质量评分-4种具有验证功能的质量管理工具
\[x\] 第11阶段： 场地和提交跟踪-场地登记、提交历史
\[x\] 第12阶段： 测试覆盖率增强-错误路径、边缘情况（实现85%的覆盖率）

当前状态

测试覆盖范围： 85%（343次测试，100%通过率）
已实施的工具： 所有类别的17个MCP工具
生产就绪： 核心功能可操作

未来增强功能（v2+）

\[ \] 高级发现工具 -相似性搜索、主题聚类、主题检测
\[ \] 备份和回滚 -显式快照、批量回滚、git集成
\[ \] 性能特点 -文件监视、热重新加载、批处理操作
\[x\] 附加保险范围 -已实现85%的目标✅

看实施_CHECKLIST.md 和 TEST_STATUS.md 以获取详细的进度跟踪。

数据同步

数据变化是如何工作的

Poetry MCP在启动时将诗歌前体作为Pydantic模型加载到内存中。了解同步行为：

当前行为（v1）：

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

要查看您的更改： 只需重新启动MCP服务器（\<3秒）。Claude Desktop将自动重新连接。

未来便利功能（v2+）

手动重新加载工具

更改后，请致电克劳德：

# No server restart needed
reload_catalog()

优点：

无需断开克劳德的连接即可立即刷新
选择性重新加载（仅更改文件）
维护对话上下文

自动文件监视

使用实时同步 watchdog 库（可在中配置 config.yaml):

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

特征：

自动检测markdown文件更改
取消公告（等待所有保存完成）
智能重新加载（仅更改文件）
安全地处理并发修改

在黑曜石中编辑时：

保存更改→ 文件监视器检测到更改
等待2秒（黑曜石可能会保存多个文件）
重新加载更改的markdown文件
更新内存中的Pydantic模型
在下一个Claude查询中可见的更改

为什么不是v1？

复杂性权衡：

文件监视会添加依赖项（监视器库）
需要去抖动逻辑（多次快速保存）
需要并发修改处理
增加了错误恢复的复杂性

目前的方法优先考虑：

✅ 简单实现
✅ 快速手动重启（总共2-3秒）
✅ 可靠的数据一致性
✅ 在开发过程中更容易调试

v2可以根据用户反馈添加这些功能。

许可证

麻省理工学院

Poetry MCP

快速接入

详细介绍