Writing MCP

mcp-writing

長編小説プロジェクトの推論と編集をAIで支援するMCPサービスです。

OpenClawで動作するよう設計されていますが、MCP対応のAIゲートウェイであればどれでも利用できます。

すぐに起動する

ローカルのstdio MCPクライアントでは、公開パッケージを直接実行します。

WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npx -y @hanna84/mcp-writing

CLIラッパーはデフォルトでstdioトランスポートを使用し、必要に応じてNode 22のSQLiteフラグを自動的に追加します。

VS Code拡張機能

VS Codeネイティブのセットアップ手順（文章スタイルガイドの設定を含む）には、次を使用します。

• hannasdev/mcp-writing-vscode

機能

原稿全体をAIに渡してコンテキストウィンドウに収まることを期待する代わりに、mcp-writingはシーンファイルから構造化インデックスを構築します。AIはまずそのインデックスを検索し、関連する登場人物、ビート、ログラインを見つけてから、必要な文章だけを読み込みます。

現在の状況：

• コアプラットフォーム完成： メタデータ優先の分析、SQLiteを正規データ源とする構造・関係メタデータ、互換性サイドカーの保守、確認とGit履歴を伴うAI支援の文章編集、レビュー用バンドル、Scrivener Directによる抽出をすべて実装済みです。
• 最近完了： Human Input Forgivenessにより、一部のリクエスト境界の入力をより柔軟に扱えるようにし、キーワードによるメタデータ検索の範囲を明確化しました。また、安定した正規IDを維持しながら、一時フィクスチャのリプレイ検証を記録しました。
• 開発中： 現在選択されている取り組みはありません。
• 保留中のバックログ： OpenClaw連携、クライアントに依存しないセットアップ、分割機能、埋め込み検索です。
• アイデアと未解決の質問： 今後の検討が進行中のロードマップを歪めないよう、別途管理しています。

対象ユーザー

• 多くのシーン、登場人物、連続性の制約を含む長編原稿に取り組む小説家や執筆チーム。
• 原稿全体をプロンプトに含めるのではなく、必要なコンテキストを絞り込んで取得したいAI支援編集ワークフロー。
• 草稿の進展に合わせてメタデータを同期しつつ、追跡可能で元に戻せる編集を必要とするプロジェクト。

ドキュメント

ガイド	説明
docs/guides/setup.md	前提条件、初回セットアップ、Scrivener のインポート、ネイティブ同期形式
mcp-writing-vscode	クライアントネイティブなセットアップフローに対応する VS Code 拡張機能
docs/guides/docker.md	Docker Compose、デプロイ運用、MCP ゲートウェイに関する注意事項
docs/guides/backup-recovery.md	プロジェクトのバックアップ成果物、診断、明示的な復元ワークフロー
docs/guides/sidecar-compatibility.md	サイドカーの互換性における役割、移行方針、日常業務における権限の境界
docs/foundations/managed-structure-contract.md	構造変更、生成ビュー、インポート、メンテナンスワークフローの設計上の境界
docs/agents/tools.md	ツールの完全なリファレンス — ソースから自動生成
docs/agents/README.md	エージェント向けガイダンス、例、ブートファイルの索引
docs/agents/use-cases.md	エージェント向けのトランスクリプトとプロンプト／ツール使用例
docs/guides/development.md	ローカルでの実行、テスト、環境変数、トラブルシューティング

破壊的変更

describe_workflows の仕様変更

describe_workflows では、成果を優先し、発見を重視したワークフローマップが公開されるようになりました。以前のワークフロー ID や順序にプロンプトや自動化が依存している場合、これは破壊的変更となります。新しい recommended_next_actions の階層は追加されたもので、全カタログより前に表示されます。

以下の対応関係に基づいて、連携機能を更新してください。

• manuscript_exploration -> question_driven_discovery（文章の確認がタスクの場合は targeted_scene_reading）
• prose_editing -> safe_scene_revision
• character_management -> character_understanding
• place_management -> place_understanding
• review_bundle -> review_preparation

新たに追加されたワークフロー ID：

• thread_understanding
• parity_recovery

スタイルガイドのワークフローも引き続き利用できますが、日常的な主要ワークフローの一部としては位置付けられなくなりました。

find_scenes と get_arc のレスポンス形式の統一

find_scenes と get_arc は、ページネーションを使用しない呼び出しも含め、常に構造化されたエンベロープを返すようになりました。

• エンベロープのフィールド：results、total_count。
• ページネーションが有効な場合は、ページネーション用のフィールドが含まれます。
• 該当する場合は、warning／next_step が含まれます。

ページネーションを使用しない呼び出しで、以前は生の配列を処理していた連携機能は、エンベロープを一貫して解析するよう更新してください。

安全な解析パターン：

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const scenes = parsed.results ?? [];
const totalCount = parsed.total_count ?? scenes.length;
const warning = parsed.warning ?? null;
const nextStep = parsed.next_step ?? null;

get_character_sheet、get_place_sheet、list_scene_references、get_relationship_arc のレスポンス形式の統一

これらのメタデータ読み取りツールは、フラットなオブジェクトや生の配列ではなく、構造化されたエンベロープを返すようになりました。

• get_character_sheet と get_place_sheet：以前はフィールド値のフラットなオブジェクトを返していましたが、現在は { results: [row], total_count: 1, next_step } を返します。
• list_scene_references：以前は { references, scene_id, project_id } を返していましたが、現在は { results, total_count, scene_id, project_id } を返します。
• get_relationship_arc：以前は生の JSON 配列を返していましたが、現在は { results, total_count, from_character, to_character } を返します。

シートツールの安全な解析パターン：

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const sheet = parsed.results?.[0] ?? {};
const nextStep = parsed.next_step ?? null;

リスト／アークツールの安全な解析パターン：

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const items = parsed.results ?? [];
const totalCount = parsed.total_count ?? items.length;

正規 ID と柔軟な入力

プロジェクト、章、シーン、キャラクター、場所、および関係性への書き込みでは、安定した ID が引き続き正規の識別子となります。ID がわかっている場合は、そのまま渡してください。

一部のリクエスト境界のフィールドでは、シーンタイトル、キャラクター名、場所の名前、大小文字の違いなど、一意に特定できる人間向けの入力を受け付けるようになりました。ツールが正常に処理されると、正規 ID が書き込まれて返されます。また、正規ではない値から入力が解決された場合は、resolved_from の詳細が返されます。一致候補が複数ある場合、近似一致の場合、または提案のみの値の場合は、失敗するか、正規の状態を変更せずに参考候補を返します。

タグと Save the Cat のビートは、引き続き自由形式の編集用語です。find_scenes では、既存のタグとビートの大文字・小文字の違いを一致対象にできます。また、メタデータの更新では既存の用語に近いものを提案できますが、意図的に変更しない限り、指定したタグとビートのテキストはそのまま保持されます。

search_metadata は、インデックス化されたタイトル、ログライン、タグ、キャラクター、場所、バージョンを対象とするキーワード／FTS メタデータ検索です。セマンティック検索ではなく、本文テキストも検索しません。メタデータ検索または構造化フィルターで候補となるシーンを特定した後、get_scene_prose を使用してください。セマンティック検索／本文検索は、Embedding-Based Search のバックログで対応が保留されています。

使用シナリオ

1) ベータリーダーに章を送る前の整合性チェック

目的：ページを共有する前に矛盾を見つけます。

1. 最新の執筆セッション後に sync を実行します。
2. 特定のキャラクターまたはタグが登場するシーンを find_scenes で検索します（たとえば、injury または promise タグが付いたすべてのシーン）。正規 ID が引き続き推奨されますが、キャラクター／視点フィルターではプロジェクト内で一意に特定できるキャラクター名を解決できます。また、タグとビートのフィルターでは近似候補を提案でき、chapter_id は完全一致の ID または大小文字の違いのみの ID を受け付けます。
3. get_arc を使って、原稿全体にわたるそのキャラクターの順序付きの展開を確認します。
4. 問題が疑われるシーンのみを get_scene_prose で読み込みます。
5. 整合性の修正が必要な箇所には、flag_scene でフォローアップメモを付けます。

結果：矛盾を探すために小説全体を読み直すのではなく、一度に 1 つの物語の流れを確認できます。

2) 改稿中のサブプロットのビートを計画・追跡する

目的：サブプロットの展開を意図的に進め、適切なタイミングで解決できるようにします。

1. プロジェクトの list_threads を実行します。
2. get_thread_arc を使って、各スレッドのシーンの順序とビートのラベルを確認します。
3. ビートが欠けている場合は、track_thread_arc を呼び出して、適切なシーンにビートを追加または更新します。
4. もう一度 get_thread_arc を実行して、ペース配分と網羅性を確認します。

結果：サブプロットの構成が把握・検証しやすくなり、初稿の後半でスレッドが抜け落ちるのを防げます。

3) 大幅な文章編集後のシーンメタデータの精緻化

目標：すべてに手作業でタグを付け直さず、インデックスの正確性を保ちます。

1. シーンを書き直した後、enrich_scene を呼び出して、現在の文章から軽量なメタデータを再導出します。
2. 意図的に設定する編集用フィールド（例：ビート、視点、ステータス、タグ）には update_scene_metadata を使用します。タグとビートは自由記述のままです。ツールは入力されたテキストを保持し、値が既存の語彙に似ている場合は候補を返します。シーンの characters と places は拒否されます。シーンがシートに登録されたキャラクターと場所の組み合わせを裏付ける証拠となる場合は connect_character_place_evidence、キャラクターのみの証拠には connect_scene_character_evidence、場所のみの証拠には connect_scene_place_evidence を使用します。これらの関係証拠ツールは正規 ID を優先しますが、一意に特定できるシーンタイトル、キャラクター名、場所名、大小文字の違いも受け付けます。曖昧な一致や候補として提示されただけの一致は、状態を変更せずに失敗します。保持されたサイドカー／フロントマターの関係フィールドには audit_relationship_metadata を使用します。章への配置と順序の管理には、list_chapters と assign_scene_to_chapter または move_scene を使用します。
3. インデックス化されたタイトル、ログライン、タグ、キャラクター、場所、バージョンを対象に、キーワード／FTS メタデータ検索を行うには search_metadata を使用します。また、構造化フィルターでシーンを見つけられることを確認するには find_scenes を使用します。該当しそうなシーンを特定した後、文章のコンテキストを確認するには get_scene_prose を使用します。

結果：AI アシスタントが、原稿との整合性を保ちながら、適切なシーンを確実に見つけられるようになります。

4) ロールバック可能な、安全な AI 支援による行単位の編集

目標：草稿の主導権を失うことなく、AI に文章編集を提案させます。

1. AI に、特定のシーンを対象として propose_edit を呼び出すよう依頼します。
2. ステージングされた差分を確認します。
3. commit_edit で承認するか、discard_edit で却下します。
4. 改訂履歴を確認または保持するには、list_snapshots（および必要に応じて snapshot_scene）を使用します。

結果：AI のスピードを活用しながら、適用したすべての変更について、明示的な承認と復元可能な履歴を確保できます。

5) インポートまたは大幅な書き直し後のシーンとキャラクターのリンクの更新

目標：インポートした文章の変更やメタデータのずれが発生した後、管理された方法でシーンとキャラクターのリンクを再構築します。

1. enrich_scene_characters_batch をデフォルトの dry_run=true で実行し、プロジェクト、章、または明示的に指定したシーンリストについて、推定されたリンクをプレビューします。
2. バッチジョブが完了するまで get_async_job_status をポーリングし、job.result.results で変更されたシーン、曖昧な一致、一部失敗を確認します。
3. 変更が重要な連続性やキャストの多い章に影響する場合は、影響を受けるシーンをいくつか選び、get_scene_prose で抜き取り確認します。
4. プレビューに問題がなければ、dry_run=false を指定して enrich_scene_characters_batch を再実行します。
5. 加算マージではなく破壊的な上書きを行う場合は、意図したうえで replace_mode=replace と confirm_replace=true を使用します。

結果：キャラクターリンクのメンテナンスが、場当たり的な正規表現スクリプトや手作業のサイドカー整理ではなく、プレビューを先に行う関係修復作業になります。

6) レガシー移行の警告が発生した後のアップグレード復旧

目標：レガシーアップグレードの警告により曖昧な行がスキップされたことが示された場合、インデックスへの信頼性をすばやく回復します。

1. まず get_runtime_config（または describe_workflows）を確認し、db_migration_warnings に LEGACY_JOIN_ROWS_SKIPPED が含まれているか確認します。
2. 含まれている場合は、すぐに sync を実行し、互換性サイドカーと文章メタデータからシーンの関係を再構築します。
3. 通常の検索（find_scenes、get_arc、get_thread_arc）を続け、古いメタデータに関する警告に注意します。
4. 古いシーンを編集する際は、enrich_scene(scene_id, project_id) を実行して、メタデータの整合性を段階的に回復します。
5. 古いシーンが多数残っている場合は、より広範囲に更新できる enrich_scene_characters_batch に切り替えます（まずドライランを実行してください）。

結果：アップグレードに伴うデータ損失のリスクが、見えない状態の不一致ではなく、オペレーターが明示的に確認できる復旧ワークフローになります。

ライセンス

AGPL-3.0-only