mdgraph

Escanea el markdown de un repositorio para convertirlo en un grafo, visualízalo en el navegador y expónlo a Claude (o cualquier host MCP) como índice de navegación.

Un único modelo de datos — { nodes, edges } — con tres consumidores:

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

Los análisis, la alcanzabilidad y los huérfanos se derivan todos del modelo en el momento de la lectura. Los nodos y las aristas se mantienen inertes.

El modelo

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

type se asigna por convención de nombre de archivo (README.md → root, CLAUDE.md/AGENTS.md/*.mdc → ai, de lo contrario, doc). Las aristas provienen de enlaces reales en el texto — [x](./y.md) estándar y [[wikilinks]] — no de la pertenencia a carpetas, así que un archivo en docs/ que enlaza a través del árbol sigue conectando a través del árbol. Las carpetas solo determinan cluster (color/agrupación).

Related MCP server: mcp-server-markdown

Instalación y ejecución

No hace falta instalación — ejecútalo directamente con 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

O instálalo globalmente para tener un comando mdgraph simple:

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

dir usa por defecto el directorio actual. view acepta --port (por defecto 4173).

Comandos

Exponer a Claude (MCP)

Claude Desktop — añádelo a 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

Reinicia el host y Claude recibe cuatro herramientas:

La idea: un agente llama a get_project_map para orientarse y luego a get_context("README.md") para traer solo los documentos que necesita la tarea — en lugar de volcar todos los .md al contexto.

Publicación (para mantenedores)

El nombre mdgraph está ocupado en npm, así que esto se publica con scope bajo tu cuenta:

# 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

Los paquetes con scope son privados por defecto, por lo que --access public es necesario la primera vez. Para publicar una actualización, sube la versión y publica de nuevo:

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

npm pack --dry-run muestra exactamente lo que se publica (actualmente 7 archivos, ~16 kB — sin node_modules, sin repo de prueba, gracias a la lista de permitidos files).

Pruébalo con el ejemplo

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

Lo que está hecho vs. lo que viene

Probado y funcionando: el escáner (extracción de md + wikilinks, omisión de bloques de código, tipado por convención, detección de huérfanos), el visor del navegador y las cuatro herramientas MCP mediante un handshake stdio real.

A continuación, aproximadamente en orden:

• Endurecer el análisis de enlaces — el escáner se basa en líneas y omite bloques delimitados, pero un tramo de código en línea (`[x](y)`) aún puede producir un enlace falso. Sustituye por un AST de markdown real (remark + unist-util-visit) cuando quieras precisión; la forma emitida sigue siendo idéntica.

• Aristas manuales — permitir que el visor escriba related: en el frontmatter de un archivo, leído como tercera fuente de aristas.

• Etiquetas de frontmatter como fuente de clúster junto a las carpetas.

• --watch en view para enviar actualizaciones del grafo mediante eventos enviados por el servidor.

Con licencia MIT.