02. 要件定義

機能要件

1. 共有ロジック（@niro/shared-confluence-cleaner）

1.1 HTML パース

• JSDOM を使用: HTML を DOM 構造に変換
• 不要要素の削除: スクリプト、スタイル、目次マクロ、アイコン画像など
• セレクタベースの削除: CSS セレクタで柔軟に対象指定

1.2 Confluence マクロの展開

以下の Confluence マクロを Markdown 記法に変換：

マクロ名	変換方法
info	> ℹ️ Info: 内容
warning	> ⚠️ Warning: 内容
note	> 📝 Note: 内容
tip	> 💡 Tip: 内容
code	```language\nコード\n```
toc	削除（目次は不要）
expand	展開して通常テキスト化
panel	ブロッククォート化

1.3 Markdown 変換

• Turndown を使用: HTML を Markdown に変換
• 変換対象の要素:
  • [Must] 見出し（h1-h6）
  • [Must] リスト（ul, ol）
  • [Must] テーブル
  • [Must] コードブロック
  • [Must] リンク
  • [Must] 画像（URL のみ）
  • [Must] 基本的な装飾（太字、斜体など）

1.4 後処理

• 余分な空行削除: 3行以上の空行を2行に統一
• 文字数制限: 必要に応じて最大文字数を制限
• メタデータ生成: 単語数、処理日時、展開したマクロ数など

2. MCP サーバー（@niro/mcp-confluence-md）

2.1 clean_confluence_html

生の HTML をクリーニングする基本ツール。

パラメータ:

{
  html: string;              // 必須: クリーニング対象のHTML
  format?: string;           // "markdown" | "plaintext" (デフォルト: markdown)
  remove_unwanted?: boolean; // 不要要素を削除（デフォルト: true）
  expand_macros?: boolean;   // Confluenceマクロを展開（デフォルト: true）
  max_length?: number;       // 最大文字数制限（省略可）
}

出力:

{
  markdown: string;          // Markdown形式
  plaintext: string;         // プレーンテキスト形式
  metadata: {
    wordCount: number;       // 単語数
    processedAt: string;     // 処理日時
    macrosExpanded: number;  // 展開したマクロ数
  }
}

2.2 clean_confluence_page

ページ ID を指定してクリーニング（Confluence API との連携が必要）。

パラメータ:

{
  page_id: string;           // 必須: ConfluenceページID
  format?: string;           // "markdown" | "plaintext"
  remove_unwanted?: boolean;
  expand_macros?: boolean;
}

出力:

{
  page_info: {
    id: string;
    title: string;
    url: string;
    last_modified: string;
  },
  markdown: string,
  plaintext: string,
  metadata: { ... }
}

2.3 batch_clean_pages

複数ページを一括クリーニング。

パラメータ:

{
  page_ids: string[];        // 必須: ページIDの配列
  format?: string;
  parallel?: boolean;        // 並列処理（デフォルト: true）
}

出力:

{
  results: Array<{
    page_id: string,
    success: boolean,
    markdown?: string,
    plaintext?: string,
    error?: string
  }>,
  summary: {
    total: number,
    succeeded: number,
    failed: number
  }
}

非機能要件

1. パフォーマンス

• 処理速度: 1ページあたり1秒以内
• 並列処理: 複数ページを並列処理可能
• メモリ効率: 大量のページを処理してもメモリリークしない

2. 拡張性

• モノレポ構成: 共有ロジックと MCP サーバーを分離
• 他ツールからの利用: Context Aggregator などから簡単に利用可能
• カスタムルール: Turndown のカスタムルールを追加可能

3. 保守性

• TypeScript による型安全性: すべてのコードを TypeScript で開発
• ユニットテスト: 共有ロジックには包括的なテスト
• 明確な責務分離: HTML パース、マクロ展開、Markdown 変換を分離

4. 品質

• 正確な変換: 元の構造を損なわない
• エッジケース対応: 複雑な Confluence マクロにも対応
• エラーハンドリング: 変換失敗時の適切なエラーメッセージ

5. セキュリティ・デプロイ

• ローカル実行: Docker コンテナ内での実行を前提
• ネットワーク制約: 社内 Confluence への接続は社内ネットワーク内のみ
• データ保護: 外部サービスへのデータ送信は禁止
• 環境構築: Docker Compose で開発・本番環境を統一
• Claude Desktop 連携: stdio 経由での通信をサポート

制約条件

技術的制約

• JSDOM のメモリ使用量
• Turndown の変換精度（完璧ではない場合がある）
• Confluence API のレート制限（clean_confluence_page で利用時）

実装上の制約

• Phase 1: まずは基本的なマクロのみ対応
• Phase 2: 複雑なマクロは段階的に対応
• Confluence API 連携: clean_confluence_page は Phase 2 で実装

セキュリティ制約

• 実行環境: ローカル Docker コンテナ内のみ
• ネットワーク: 社内ネットワーク経由でのみ Confluence にアクセス
• データ転送: すべてのデータ処理をローカル環境で完結
• クラウドサービス: 外部 API やクラウドサービスの利用は禁止

成功の定義

MVP（Phase 1）

• ConfluenceCleaner クラスが HTML を Markdown に変換できる
• 基本的なマクロ（info, warning, code）が正しく展開される
• clean_confluence_html ツールが動作する
• ユニットテストが通る

完成形（Phase 2）

• すべての Confluence マクロに対応
• clean_confluence_page が動作する（Confluence API 連携）
• batch_clean_pages が並列処理で高速に動作する
• 統合テストが完備されている
• Docker 環境で問題なく動作する
• Claude Desktop から Docker 経由で MCP サーバーにアクセスできる

今後詰める必要がある詳細

1. Confluence API 連携の詳細:

   • 認証方法（Personal Access Token）
   • ページ取得の API エンドポイント
   • エラーハンドリング

2. 複雑なマクロの変換方法:

   • ネストしたマクロの処理
   • カスタムマクロへの対応
   • 変換できないマクロの扱い

3. テスト戦略:

   • 実際の Confluence ページを使ったテスト
   • 大量ページでのパフォーマンステスト
   • エッジケースの収集

4. ドキュメント:

   • API ドキュメント
   • 使用例
   • トラブルシューティング