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.
node = { id, label, path, type, cluster, content } // type: root | ai | doc
edge = { source, target, sourceLine, context } // context = the line the link lives ontype 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
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.jsonO instálalo globalmente para tener un comando mdgraph simple:
npm install -g @emmd474/mdgraph
mdgraph view ./my-repo
mdgraph scan ./my-repo --out graph.jsondir usa por defecto el directorio actual. view acepta --port (por defecto 4173).
Comando | Qué hace |
| Construye el grafo, imprime JSON en stdout (o escríbelo con |
| Sirve el grafo interactivo en |
| Ejecuta el servidor MCP sobre stdio, para Claude y otros agentes. |
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/repoReinicia el host y Claude recibe cuatro herramientas:
Herramienta | Propósito |
| Resumen sin contenido: tipos, clústeres, recuentos de enlaces, indicadores de huérfano/alcanzable, aristas. La forma económica de orientarse. |
| Markdown sin procesar de un documento por ruta. |
| Todo lo alcanzable desde un documento de entrada, en orden de lectura: el conjunto exacto a cargar para entenderlo. |
| Documentos a los que nada enlaza. |
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.
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 publicLos 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 publishnpm 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).
git clone <this repo> && cd mdgraph && npm install
node cli.mjs view testrepo
node cli.mjs scan testrepoProbado 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.
This server cannot be deployed
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
Repository knowledge graph MCP server for codebase understanding and debugging.