KAIRAN

Claude Code / Codex などの agent が生成した markdown / HTML を、tool call ひとつでブラウザに表示するローカル MCP サーバー。

• 何個の agent から接続されても、表示サーバーは 1 つ・port は 1 つ（初回 tool call で自動起動、全員がいなくなると自動停止）

• URL は http://localhost:5766/<セッションID>/<ファイル名>。全 URL が deep link

• 同じ名前で再 publish すると新リビジョンとして積まれ、リビジョン間の差分（unified / side-by-side）が見られる

• 3 ペイン UI（セッション / ファイル / ビュー）+ SSE live update。新着 publish への自動追従は「新着に追従」トグルで制御

• agent が終了したセッションは自動で archive され、サイドバーの「archived」トグルで表示できる

• markdown は GFM + shiki シンタックスハイライト + mermaid 図に対応。HTML は iframe でそのまま実行（ローカル用途のため制限なし）

• publish 時に macOS 通知センターへ通知（設定で off 可）。terminal-notifier が入っていれば通知クリックでそのファイルをブラウザで開ける（brew install terminal-notifier。無ければ osascript 通知にフォールバック、クリック遷移なし）

• 人間 → agent のフィードバックにも対応。文書にインラインコメントを付けて GitHub PR レビューのように一括送信でき（request_review で agent が受け取る）、agent からの選択肢つき質問（ask_user）にブラウザ上で回答できる

セットアップ

bun install
bun link   # `kairan` コマンドをグローバルに登録

Claude Code

claude mcp add --scope user kairan -- kairan mcp

Codex CLI

# ~/.codex/config.toml
[mcp_servers.kairan]
command = "kairan"
args = ["mcp"]

Related MCP server: feedback-mcp-server

tool

publish

markdown / HTML をブラウザに表示する。path（ファイルパス）か content（文字列）のどちらかを渡す。

戻り値: { url, sessionId, fileId, revision, pendingFeedback }（pendingFeedback は未受領フィードバック件数）

list_files

自セッション（または session で指定した名前付きセッション）の publish 済みファイル一覧。

request_review

人間にブラウザでのレビューを依頼し、送信されるまでブロックする。人間側はコメントを下書きとして溜め、総評とともに「送信」した時点でまとめて返る（GitHub PR レビューと同じモデル。コメント 0 件 + 総評空の「コメントなしで返す」も可）。timeout（デフォルト 20 分、timeout_seconds で変更可）で「まだフィードバックなし」が返るので、続けて待つ場合は再度呼ぶ（再呼び出しループで何時間でも待てる）。

戻り値には各コメントの commentId・対象ファイル・引用文（選択範囲）・本文と、総評・スレッド返信・未回収の質問回答が含まれる。

ask_user

選択肢つきの質問カードをブラウザに表示し、回答されるまでブロックする。複数 question を 1 カードに積め、各 question は選択肢 + 自由記述（常設）を持つ。人間は全問に答えてから送信する。file を渡すとその質問がどのファイルの話かサイドバーにバッジ表示される。timeout 後に同じ質問で再度呼ぶと既存カードを再利用して待ち直す（カードは増えない）。

reply_comment

request_review / list_feedback が返した commentId へのスレッド返信。resolve: true でコメントを解決済みにできる（人間側から再オープン可）。

list_feedback

ブロックせずに、送信済み・未受領のフィードバック（レビュー・質問回答）を回収する。agent が待っていない間に送信されたぶんの回収用。各項目は一度だけ返る。

CLI

kairan status    # デーモンの稼働確認
kairan restart   # デーモンの再起動（コード・設定変更の反映用）
kairan stop      # デーモンの停止（通常は不要: 全接続が消えると自動停止する）
kairan daemon    # デーモンをフォアグラウンド起動（通常は自動起動されるため不要）

コード変更の反映

• デーモン側（Web UI・API・レンダリング・通知など大半のロジック）: kairan restart で反映される

• stdio ランチャー側（tool 定義・入力解決）: ランチャープロセスは agent が起動・保持しているため kairan 側からは再起動できない。agent の MCP 再接続で反映される（Claude Code は /mcp → Reconnect、または新しいセッションを開始）

設定

~/.kairan/config.json（すべて任意）と環境変数で上書きできる。優先度: 環境変数 > config.json > デフォルト。

設定ファイルのパス自体は KAIRAN_CONFIG_PATH で変更できる。

アーキテクチャ

agent (Claude Code / Codex)
  │ stdio MCP
  ▼
kairan mcp（agent ごとに 1 プロセス。port は使わない）
  │ HTTP（初回 tool call 時にデーモンを自動 spawn・生存申告の SSE を維持）
  ▼
kairan daemon（全体で 1 つ・port 1 つ）── SQLite (~/.kairan/kairan.db)
  │ HTTP + SSE
  ▼
browser（3ペイン UI）

• stdio プロセス = 1 セッション。プロセス終了（= agent 終了）で TCP が切れ、デーモンがセッションを archive する

• デーモンは「active セッション 0 かつ 閲覧タブ 0」になると自動停止する。データは SQLite に永続化されているため、次回起動時も過去セッションを閲覧できる

• 設計判断の経緯: .local/docs/adr/0001-stdio-launcher-shared-daemon.md

開発

bun test            # テスト
bun run typecheck   # tsc
bun run lint        # biome
bun run dev         # デーモンをフォアグラウンド起動