索引だけを入れ、本文を必要な分だけ読ませ、CLI と同じ処理をツールで呼ぶ流れ
Claude Code のプラグインが、mdmark の使い方と操作を Claude Code に渡す考え方。 入れ方と使い方は プラグインを入れる と MCP のツールを使う。
プラグインの SessionStart のフックが、セッションの開始で使い方集の索引を Claude Code に渡す。 索引は、名前・読むとき・概要の表だけで、本文を含めない。 索引は事実として書き、命令の文にしない。
Claude Code は、フックが渡す文が 10,000 文字を超えると先頭 2,000 文字だけを使う。 そのため、索引の文字数が 10,000 文字を超える使い方集は、プラグインをビルドする時点で止める。
本文は索引に入れず、MCP のツール read_guide に索引の名前を渡したときに返す。
返す本文は、mdmark serve を起動したパッケージに同梱した docs/ の使い方・リファレンスのページ。
作業に要るページだけを読むため、セッションの文脈は索引の分しか増えない。
1 回に返す本文は合計 50,000 文字まで。 Claude Code は、これを超えた結果をファイルに逃がして本文を渡さないため、超えるときは名前を分けて呼ばせる。
export_html・build_site・check は、CLI の mdmark export・build・check と同じ処理を呼ぶ。
同じ文書・設定・索引では、CLI と同じ結果になる。
find_docs と list_tags は設定の index の索引を引き、update_index は書き換える。
find_docs は、全ての文書ではなく既定の件数ずつ返し、タグの全てを持つ（AND）かどれかを持つ（OR）かで絞り、返す量と形式を引数で選ばせる。
update_index は、書く前に索引のスキーマで検査し、合わなければ書かない。
作業のフォルダを使うツールは、作業のフォルダの絶対パスを引数 project_dir で受ける。
常駐サーバーにはセッションの作業のフォルダが環境変数で渡らないため、プラグインの PreToolUse のフックが、ツールの呼び出しのたびにセッションのフォルダを project_dir に入れる。
設定ファイルは、そのフォルダから上のフォルダへ順に探す。
ツールの config に別のパスを渡すと、そのファイルを使う。
MCP サーバーは、文書を書く人が mdmark serve で起動する常駐のサーバー。
127.0.0.1 の Streamable HTTP で待ち受け、プラグインの .mcp.json がその URL へつなぐ。
並行して開いたセッションが同じプロセスを共有するため、サーバーはセッションごとの状態を持たず、呼び出しごとに処理する。
起動の手順は MCPサーバーを起動する。
サーバーが起動していないと、そのセッションでは MCP サーバーだけが接続に失敗する。
起動してから /mcp で接続し直すと、セッションを開き直さずにツールを呼べる。
フックは、CLI と同じ処理を束ねた JavaScript で、node が起動する。
プラグインは束ねたフックだけを持ち、依存を入れない。
使い方集の索引は、リポジトリの guide/index.yaml が正。
プラグインのビルドが、索引の検査を通してから、索引と本文のページを plugin/guide/ に写す。
無いページを指す行と、索引の文字数が上限を超えるときは、ビルドが止まる。
フックと MCP サーバーは、写した方だけを読み、作業のフォルダのファイルは読まない。