# MCPサーバー noveler - バージョン管理ガイド

**最終更新**: 2025-10-28
**バージョン**: v0.0.3
**ステータス**: 安定版

---

## 概要

novelerMCPサーバーのバージョン管理と配布戦略をまとめたドキュメントです。

### 目的

- 複数プロジェクト（夢遊病等）で **特定バージョンのnovelerを固定利用**
- noveler開発の継続と、プロジェクトの安定性を両立
- 複数バージョンの並行管理に対応

### 全体構成

```
C:\Users\bamboocity\Dropbox\noveler
├── ハブ: MCPサーバーの開発・ビルド
├── git tags: v0.0.3, v0.0.4, ...（セマンティックバージョニング）
└── pyproject.toml: version = "0.0.3"

       ↓ ビルド配布

C:\Users\bamboocity\OneDrive\Documents\9_小説\00_ガイド
├── ハブ: ビルド済みMCPサーバーの一元管理
├── dist/mcp_servers/noveler/（本番版 v0.0.3）
├── src/mcp_servers/noveler/（開発版 dev追従）
└── codex.mcp.json（バージョン情報付き）

       ↓ 参照

C:\Users\bamboocity\OneDrive\Documents\9_小説\11_夢遊病
├── プロジェクト: noveler v0.0.3を固定利用
└── codex.mcp.json（バージョン固定明示）
```

---

## 3階層のバージョン管理

### Layer 1: novelerリポジトリ（開発ハブ）

#### ブランチ戦略

```bash
main
  ├── 安定版ブランチ
  ├── git tag: v0.0.3 (現在の安定版)
  └── 定期的にdevからマージ

dev
  ├── 開発ブランチ
  ├── 機能追加・修正が行われる
  └── main にマージ後、タグ付けしてリリース
```

#### バージョン定義

```toml
# pyproject.toml (Line 9)
[project]
version = "0.0.3"
```

**重要**: `pyproject.toml` のバージョンと git タグは **必ず同期** させます。

### Layer 2: 00_ガイド（配布・管理ハブ）

#### ディレクトリ構成

```
C:\Users\bamboocity\OneDrive\Documents\9_小説\00_ガイド
├── src/mcp_servers/noveler/        ← ソース参照（開発用）
├── dist/mcp_servers/noveler/       ← ビルド済み本番版 v0.0.3
└── codex.mcp.json                  ← MCP設定（全プロジェクト共有）
```

#### バージョン記録

```json
// codex.mcp.json (新規追加: 2025-10-28)
{
  "_metadata": {
    "noveler_version": "0.0.3",
    "pinned_date": "2025-10-28"
  },
  "mcpServers": {
    "noveler": {
      "description": "本番版 v0.0.3",
      "_metadata": {
        "version": "0.0.3",
        "branch": "main",
        "built_from": "dist/mcp_servers/noveler"
      }
    }
  }
}
```

**用途**:
- **noveler**: 本番版 v0.0.3（全プロジェクト共有）
- **noveler-dev**: 開発版（dev追従）

### Layer 3: 利用プロジェクト（夢遊病等）

#### バージョン明示

```json
// codex.mcp.json (新規追加: 2025-10-28)
{
  "_metadata": {
    "noveler_pinned_version": "0.0.3",
    "pinned_date": "2025-10-28"
  },
  "mcpServers": {
    "noveler": {
      "_metadata": {
        "version": "0.0.3",
        "pinned": true,
        "source": "C:/Dropbox/noveler (main / tag v0.0.3)"
      }
    }
  }
}
```

**用途**: プロジェクトが利用している noveler バージョンを明確に記録。

---

## 運用フロー（3パターン）

### パターンA: 通常開発（最新版を自動追従）

**用途**: novelerの小さな修正・改善を頻繁に行う場合

**手順**:
```bash
# 1. novelerで機能追加
cd C:\Users\bamboocity\Dropbox\noveler
git checkout dev
# ... コード変更 ...
git commit -m "feat: 新機能追加"
git push origin dev

# 2. 00_ガイドで再ビルド（自動でdistが更新）
cd C:\Users\bamboocity\OneDrive\Documents\9_小説\00_ガイド
bin/build  # または python scripts/build.py

# 3. 夢遊病は自動的に最新版を参照
# codex.mcp.jsonのpathは変わらないので、VSCode再読み込みで反映
```

**メリット**:
- 開発のサイクルが高速
- バージョン管理の手続きが最小限

**デメリット**:
- プロジェクトの安定性がnovelerの開発に影響される

---

### パターンB: 安定版リリース（バージョン固定）

**用途**: novelerの新機能が完成し、複数プロジェクトで使い分けたい場合

**手順**:
```bash
# 1. novelerの安定版を確定
cd C:\Users\bamboocity\Dropbox\noveler
git checkout main
git merge dev

# 2. バージョン更新
#    pyproject.toml の version を 0.0.3 → 0.0.4 に変更
vim pyproject.toml
# [project]
# version = "0.0.4"

git add pyproject.toml
git commit -m "chore: bump version to v0.0.4"

# 3. タグ付け（重要！）
git tag v0.0.4
git push origin main --tags

# 4. 00_ガイドで新バージョンをビルド
cd C:\Users\bamboocity\OneDrive\Documents\9_小説\00_ガイド
bin/build

# 5. codex.mcp.json を更新（バージョン情報）
#    "_metadata": { "noveler_version": "0.0.4", "pinned_date": "2025-10-XX" }
vim codex.mcp.json
git add codex.mcp.json
git commit -m "chore: noveler version updated to v0.0.4"

# 6. 必要に応じて夢遊病のcodex.mcp.jsonも更新
#    "_metadata": { "noveler_pinned_version": "0.0.4" }
```

**メリット**:
- 複数プロジェクト間でバージョンを明確に分離可能
- 安定性と開発の両立が可能

**デメリット**:
- 手作業が増える

---

### パターンC: 複数バージョン並行管理（拡張オプション）

**用途**: 異なるバージョンを複数プロジェクトで使い分ける場合

**例**:
```
dist/
└── mcp_servers/
    ├── noveler/           ← 最新版 v0.0.4
    ├── noveler_v0.0.3/    ← 夢遊病専用（旧版）
    └── noveler_v0.0.2/    ← テスト用（互換性確認）
```

**実装方法**:
1. ビルド時に `dist/noveler_vX.Y.Z/` にディレクトリを作成
2. 各プロジェクトの `codex.mcp.json` で異なるパスを指す

**現在の推奨度**: ⭐ (将来の必要に応じて実装)

---

## チェックリスト

### 新機能追加時（パターンA）
- [ ] noveler の dev ブランチで開発
- [ ] git commit & push
- [ ] 00_ガイドで bin/build 実行
- [ ] 夢遊病で動作確認

### 安定版リリース時（パターンB）
- [ ] noveler の main にマージ
- [ ] pyproject.toml の version を更新
- [ ] git tag vX.Y.Z を付与
- [ ] git push origin main --tags
- [ ] 00_ガイドで bin/build 実行
- [ ] 00_ガイドの codex.mcp.json を更新
- [ ] （必要に応じて）夢遊病の codex.mcp.json を更新

---

## トラブルシューティング

### 問題: 夢遊病が古いバージョンのnovelerを使っている

**原因**:
- 00_ガイドの dist/mcp_servers/noveler がビルドされていない
- VS Codeがキャッシュしている

**解決**:
```bash
# 1. ビルド実行
cd C:\Users\bamboocity\OneDrive\Documents\9_小説\00_ガイド
bin/build

# 2. VS Code再起動
# (Ctrl+Shift+P → "Developer: Reload Window")

# 3. 確認
noveler --version
```

### 問題: 新機能がすぐに夢遊病に反映されない

**原因**: 00_ガイドで bin/build が実行されていない

**解決**:
```bash
cd C:\Users\bamboocity\OneDrive\Documents\9_小説\00_ガイド
bin/build

# ログを確認
cat build.log
```

### 問題: タグが付かれていない

**確認**:
```bash
cd C:\Users\bamboocity\Dropbox\noveler
git tag -l
git describe --tags
```

**修正**:
```bash
# 現在のmainをv0.0.3にタグ付け（未実施の場合）
git tag v0.0.3
git push origin --tags
```

---

## よくある質問

### Q1. 複数プロジェクトで異なるバージョンを使いたい

**A**: 現在のセットアップでは、00_ガイドの `dist/mcp_servers/noveler/` は共有です。
異なるバージョンを使う場合は、パターンC（複数バージョン並行管理）を実装します。

### Q2. noveler の開発中、夢遊病で試したい

**A**: 以下の選択肢があります：

**オプション1**（推奨）: 00_ガイドの `noveler-dev` を夢遊病で使う
```json
// codex.mcp.json
{
  "mcpServers": {
    "noveler": { ... },           // 本番版 v0.0.3
    "noveler-dev": { ... }        // 開発版（最新dev）
  }
}
```

**オプション2**: 00_ガイドで dev ブランチをビルドして使う

### Q3. タグの命名規則は？

**A**: セマンティックバージョニングに従います：
```
v0.0.3          # パッチリリース
v0.1.0          # マイナーリリース（新機能）
v1.0.0          # メジャーリリース（破壊的変更）
v0.0.4-beta     # ベータ版（オプション）
```

### Q4. タグを削除・修正したい

**A**: 以下の手順を実行します：
```bash
# ローカルで削除
git tag -d v0.0.3

# リモートで削除
git push origin --delete tag v0.0.3

# 再度作成・push
git tag v0.0.3
git push origin --tags
```

---

## 関連ドキュメント

- [CLAUDE.md](../CLAUDE.md) - プロジェクト全体のガイドライン
- [MCP設定管理](./mcp/config_management.md) - MCP設定の詳細
- [00_ガイド README](../00_ガイド/README.md) - 配布ハブのセットアップ

---

## 変更履歴

| 日付 | 版 | 変更内容 |
|------|-----|---------|
| 2025-10-28 | 1.0 | 初版作成。3階層バージョン管理の確立 |

---

**最終確認**: 2025-10-28 夢遊病プロジェクトで v0.0.3 として利用開始
