mdgraph

Сканирует markdown-файлы репозитория в граф, визуализирует его в браузере и предоставляет его Клоду (или любому MCP-хосту) как навигационный индекс.

Одна модель данных — { nodes, edges } — с тремя потребителями:

              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).

Команды

Предоставление Клоду (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

Перезапустите хост, и Клод получит четыре инструмента:

Суть: агент вызывает 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 требуется при первой публикации. Чтобы выпустить обновление, увеличьте версию и опубликуйте снова:

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

npm pack --dry-run показывает, что именно попадёт в пакет (сейчас 7 файлов, ~16 кБ — без node_modules и тестового репозитория, благодаря списку files).

Попробуйте на примере

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

Что уже работает, а что в планах

Проверено и работает: сканер (извлечение md и вики-ссылок, пропуск блоков кода, типизация по соглашениям, обнаружение осиротевших файлов), браузерный просмотрщик и все четыре MCP-инструмента через живое stdio-соединение.

Далее, примерно в порядке:

• Улучшить разбор ссылок — сканер построчный и пропускает блоки кода, но инлайн-код (`[x](y)`) всё ещё может дать ложную ссылку. Замените на настоящий markdown-AST (remark + unist-util-visit), когда понадобится точность; формат вывода останется прежним.

• Ручные рёбра — позволить просмотрщику записывать related: в frontmatter файла, читать его как третий источник рёбер.

• Теги frontmatter как источник кластеров наряду с папками.

• --watch в view для отправки обновлений графа через server-sent events.

Лицензия MIT.