Skip to content
Niro Knowledge Base

Confluence-MD

プロジェクト概要

Section titled “プロジェクト概要”

Confluence の HTML コンテンツを LLM が理解しやすい Markdown 形式に変換する専用 MCP サーバーです。

コンセプト: 「Confluence の HTML ノイズを除去し、LLM が理解しやすい形式に変換」

背景・課題

Section titled “背景・課題”
  • Confluence API から取得した HTML にはタグやマクロなどのノイズが多い
  • LLM のトークン数が無駄に増え、コストが増加する
  • HTML タグが文章として解釈され、本質的な情報が埋もれる
  • Confluence マクロの構文がノイズになる

解決アプローチ

Section titled “解決アプローチ”

Confluence の HTML を以下のように変換します：

  1. HTML をパースし、不要な要素（スクリプト、スタイル、目次マクロなど）を削除
  2. Confluence 独自マクロ（info、warning、code など）を Markdown の記法に展開
  3. クリーンな Markdown に変換
  4. 必要に応じてプレーンテキストも生成

効果:

  • トークン削減: 約50%
  • 読みやすく、LLM が理解しやすい
  • 構造を保持したまま変換

システム構成

Section titled “システム構成”
graph TB
    subgraph "Confluence"
        C[HTML Content]
    end

    subgraph "confluence-md MCP Server"
        P[HTML Parser]
        M[Macro Expander]
        MD[Markdown Converter]
        PP[Post Processor]
    end

    subgraph "Output"
        OUT[Clean Markdown]
    end

    C --> P
    P --> M
    M --> MD
    MD --> PP
    PP --> OUT

技術スタック

Section titled “技術スタック”
  • 言語: TypeScript
  • ランタイム: Bun
  • パッケージマネージャー: Bun (モノレポ対応)
  • コンテナ: Docker（開発・本番環境）
  • HTML パーサー: JSDOM
  • Markdown 変換: Turndown
  • MCP SDK: @modelcontextprotocol/sdk

デプロイ要件

Section titled “デプロイ要件”

セキュリティ制約

Section titled “セキュリティ制約”

このプロジェクトは以下のセキュリティ要件により、ローカル環境（Docker コンテナ内）での実行を前提としています：

  • ✅ 社内 Confluence への接続は社内ネットワーク内のみ
  • ✅ 外部サービスへのデータ送信は禁止
  • ✅ すべての処理を Docker コンテナ内で完結
  • ✅ Claude Desktop から stdio 経由で MCP サーバーと通信

実行環境

Section titled “実行環境”
  • 開発環境: Docker Compose + Bun（ホットリロード対応）
  • 本番環境: Docker コンテナ内で MCP サーバーを起動
  • Claude Desktop 連携: docker compose exec 経由で stdio 通信

提供ツール

Section titled “提供ツール”
  1. clean_confluence_html: 生の HTML をクリーニング
  2. clean_confluence_page: ページ ID を指定してクリーニング
  3. batch_clean_pages: 複数ページを一括クリーニング

開発フェーズ

Section titled “開発フェーズ”
  1. Phase 1: 共有ロジック実装（HTML → Markdown 変換）
  2. Phase 2: MCP サーバー実装
  3. Phase 3: Context Aggregator との統合（将来）

ドキュメント構成

Section titled “ドキュメント構成”