# A31_新システム利用ガイド（MCP版）
> ℹ️ **CLI移行メモ**: このドキュメントに登場する `novel` コマンドは歴史的記述です。現在の運用では `./bin/noveler` および MCP ツールを使用してください。詳細は [docs/migration/novel_to_noveler.md](migration/novel_to_noveler.md) を参照してください。


本ガイドは、MCPサーバー移行後の最新利用法に基づく実践ガイドです。Claude Code 連携を前提に、MCPツールを入口とする運用を標準とし、必要に応じてCLI例を補足します。

---

## 1. クイックスタート（MCP）

- 前提:
  - Python 3.11+
  - 仮想環境（任意）
  - リポジトリ直下で実行

```bash
# MCPサーバーを起動（開発）
noveler mcp-server --dev --port 3001 --debug

# Claude Code 側で codex.mcp.json の設定を読み込み、noveler MCP サーバーを有効化
# 以後は Claude Code から MCP ツール（run_quality_checks 等）を呼び出し
```

---

## 2. 典型フロー（MCPツール中心）

1) プロジェクト初期化（CLI補足）
```bash
noveler create "プロジェクト名"
```

2) 話別プロット作成 → A28参照（テンプレートあり）

3) 執筆フロー（A30）
```bash
# Claude Code 側でタスク駆動（例）
noveler mcp call get_writing_tasks '{"episode_number":1}'
noveler mcp call execute_writing_step '{"episode_number":1,"additional_params":{"step":"draft"}}'
```

4) 品質チェック（A33/B33）
```bash
# 要約のみ（軽量）
noveler mcp call run_quality_checks '{"exclude_dialogue_lines": true,
  "episode_number": 1,
  "additional_params": {"format": "summary", "severity_threshold": "medium"}
}'

# NDJSON + フェイルゲート（CI）
python scripts/ci/run_quality_checks_ndjson.py --episode 1 \
  --severity-threshold medium --fail-on-score-below 80 --out reports/quality.ndjson
```

5) 自動修正・反復改善
```bash
# 安全な自動修正（約物/短文長文の安全調整など）
noveler mcp call fix_quality_issues '{"episode_number":1,"additional_params":{"dry_run":true}}'

# 目標スコアまで自動改善（反復）
noveler mcp call improve_quality_until '{"episode_number":1,"additional_params":{"target_score":80}}'
```

---

## 3. MCPツール連携の要点

- 対応ツール（例）:
  - `get_writing_tasks`: 18ステップのタスクリスト取得
  - `execute_writing_step`: 指定ステップの実行
  - `get_task_status`: 進捗・結果取得

- ベストプラクティス:
  - ツール呼び出し前に対象ファイル（プロット・設定）を最新化
  - ステップ間での中間生成物（yaml/json）を破棄しない（キャッシュ効率化）
  - エラーは「階層的エラーハンドリング」により自動復旧を試行 → 復旧不可のみ手動対応

詳細な使用例は「MCPツール統合ガイド（docs/B33_MCPツール統合ガイド.md, [MCPツール活用ベストプラクティス](mcp/tools_usage_best_practices.md)）」を参照してください。
また、よくある問題と対処は [A35_トラブルシューティングガイド.md](A35_トラブルシューティングガイド.md) を参照してください。

> 互換メモ（CLI）: 旧 `novel/noveler check` は `run_quality_checks`（MCP）に対応。CLI例は歴史的記述として参照可。

---

## 4. ジャンル拡張（例: SF/ミステリー）

`src/noveler/docs/A30_執筆ガイド.yaml` にジャンル特化仕様（genre_specifications）を定義します。CLI/ツールは自動的に該当ルールを取り込み、テンプレートに反映します。

- 反映されるもの:
  - 特化ルール（語彙・構成・テンポ）
  - テンプレート追加事項（導入/山場/結語の作法）
  - 使用例（プロンプト例）

---

## 5. トラブルシューティング（抜粋）

- 禁止表現の混入:
  - A30テンプレートの `forbidden_expressions` を確認
  - `run_quality_checks` の結果（MCP）で警告/エラー内容を確認し修正

- 連続短文でリズムが単調:
  - `.novelerrc.yaml` のしきい値・weights を見直し
  - `improve_quality_until` で安全修正を反復

- YAMLガイドが見つからない:
  - `src/noveler/docs/A30_執筆ガイド.yaml` の配置・権限を確認

---

## 6. 参考

- A30_執筆ワークフロー.md（段階的執筆の全体像）
- A32_執筆コマンドガイド.md（コマンド詳細・オプション早見表）
- A33_執筆品質管理チェック.md（ゲート制御・品質メトリクス）
- [MCPツール活用ベストプラクティス](mcp/tools_usage_best_practices.md)（MCP活用の実践集）
