mdgraph

リポジトリのMarkdownをグラフにスキャンし、ブラウザで可視化し、Claude（または任意のMCPホスト）にナビゲーションインデックスとして公開します。

1つのデータモデル — { nodes, edges } — と3つの利用者:

              scan  (the only hard part)
                 │  emits { nodes, edges }
      ┌──────────┼───────────┐
      ▼          ▼           ▼
   graph.json  browser     MCP server
   (a file)   (viewer)   (agents read it)

分析結果（インサイト）、到達可能性、孤立ドキュメントはすべて、読み取り時にモデルから導出されます。ノードとエッジは、単なるデータであり、それ以上の意味を持ちません。

モデル

node = { id, label, path, type, cluster, content }   // type: root | ai | doc
edge = { source, target, sourceLine, context }        // context = the line the link lives on

type はファイル名のルールによって決まります（README.md → root、CLAUDE.md / AGENTS.md / *.mdc → ai、それ以外は doc）。エッジはフォルダ構成ではなく、テキスト内の実際のリンク（[x](./y.md) と [[wikilinks]]）から生成されます。そのため、docs/ 内のファイルがツリーの外を参照していても、そのリンクはツリーを越えて維持されます。フォルダは cluster（色分け / グループ化）にのみ影響します。

Related MCP server: mcp-server-markdown

インストールと実行

インストール不要です。npx でそのまま実行できます:

npx @emmd474/mdgraph scan .            # print the graph as JSON
npx @emmd474/mdgraph view .            # open the interactive graph in a browser
npx @emmd474/mdgraph scan . --out graph.json

またはグローバルインストールして、普通の mdgraph コマンドとして使うこともできます:

npm install -g @emmd474/mdgraph
mdgraph view ./my-repo
mdgraph scan ./my-repo --out graph.json

dir のデフォルトはカレントディレクトリです。view は --port（デフォルト4173）を受け付けます。

コマンド

Claude に公開する（MCP）

Claude Desktop — claude_desktop_config.json に追加してください:

{
  "mcpServers": {
    "mdgraph": {
      "command": "npx",
      "args": ["-y", "@emmd474/mdgraph", "mcp", "/abs/path/to/your/repo"]
    }
  }
}

Claude Code:

claude mcp add mdgraph -- npx -y @emmd474/mdgraph mcp /abs/path/to/your/repo

ホストを再起動すると、Claude は以下の4つのツールを利用できます:

ポイント: エージェントは get_project_map で方向を確認し、get_context("README.md") でそのタスクに必要なドキュメントだけを取得します — すべての .md を毎回コンテキストに読み込む必要はありません。

公開（メンテナー向け）

mdgraph という名前は npm で使用済みのため、このパッケージはあなたのアカウント配下のスコープ付きパッケージとして公開します:

# 1. set the scope to YOUR npm username (edit "name" in package.json if not @emmd474)
npm whoami          # confirm you're logged in; else: npm login
npm publish --access public

スコープ付きパッケージはデフォルトでプライベートなので、初回は --access public が必要です。アップデートを配信するには、バージョンを上げて再度 publish します:

npm version patch   # 0.1.0 -> 0.1.1, also creates a git tag
npm publish

npm pack --dry-run で実際に公開される内容を確認できます（現在は7ファイル、約16 kB — files の allowlist によって node_modules もテストリポジトリも含まれません）。

例で試す

git clone <this repo> && cd mdgraph && npm install
node cli.mjs view testrepo
node cli.mjs scan testrepo

実装済みと今後の予定

テスト済みで動作するもの: スキャナー（mdリンク抽出、wikilink抽出、コードフェンススキップ、ルールベースのタイプ割り当て、孤立検出）、ブラウザビューア、そして実際の stdio ハンドシェイクで動作する全4つのMCPツール。

次に実装する予定は、おおよそ以下の順です:

• リンク解析の堅牢化 — スキャナーは行ベースでフェンス付きブロックをスキップしますが、インラインコードスパン（ true`））から誤リンクが生まれる可能性があります。精度を求めるなら、実際の Markdown AST（remark + unist-util-visit）に置き換えてください。出力される形はまるです。

• 手動エッジ — ビューアが related: をファイルの frontmatter に書き込み、それを第3のエッジソースとして読み取ります。

• Frontmatter タグ — フォルダに加えて、クラスタソースとして使えるようにします。

• --watch — view でグラフ更新をサーバー送信イベント（SSE）で配信するためのオプションです。

MIT ライセンスで提供されています。