mdgraph

저장소의 마크다운을 그래프로 스캔하고, 브라우저에서 시각화하며, Claude(또는 모든 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)를 받습니다.

명령어

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에 네 가지 도구가 제공됩니다:

요점: 에이전트는 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 kB — files 허용 목록 덕분에 node_modules나 테스트 저장소 없음).

예제에서 사용해 보기

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

실제 구현된 것 vs. 다음 단계

테스트 완료 및 작동: 스캐너(md + wikilink 추출, 코드 펜스 건너뛰기, 규칙 기반 타입 지정, 고아 문서 감지), 브라우저 뷰어, 그리고 실제 stdio 핸드셰이크를 통한 네 가지 MCP 도구 모두.

다음 단계, 대략적인 우선순위:

• 링크 파싱 강화 — 스캐너는 줄 기반이며 펜스 블록을 건너뛰지만, 인라인 코드 스팬(`[x](y)`)은 여전히 잘못된 링크를 생성할 수 있습니다. 정밀도가 필요하면 실제 마크다운 AST(remark + unist-util-visit)로 교체하세요. 출력 형태는 동일하게 유지됩니다.

• 수동 엣지 — 뷰어가 파일의 frontmatter에 related:를 작성하고, 이를 세 번째 엣지 소스로 읽습니다.

• Frontmatter 태그를 폴더와 함께 클러스터 소스로 사용.

• view의 --watch 로 서버 전송 이벤트를 통해 그래프 업데이트를 푸시.

MIT 라이선스.