코드베이스가 그래프로 보입니다 — codebase-memory-mcp의 숨은 화면 localhost:9749

미리 3줄로 보면

몰랐던 것: 이 MCP에는 브라우저로 여는 그래프 화면이 딸려 있다. 기본값이 켜짐이라 이미 돌고 있을 수도 있다
켜는 법: --ui=true --port=9749 후 브라우저로 localhost:9749
진짜 쓸모: 그래프보다 AI가 내 코드에 무엇을 물었는지 로그로 보이는 것이 컸다

딱따구리 선생님이 벽에 걸린 커다란 코드 지도를 올려다보며, 실이 이어진 자리들을 손끝으로 짚어보는 모습 (AI 생성 삽화)

이 도구에 화면이 있는 줄 몰랐습니다

지난 글에서 코드베이스를 통째로 색인해두는 MCP를 설치하고 쓰는 법을 정리했습니다. 그때는 AI에게 말로 묻는 것만 다뤘어요. “이 함수 누가 호출해?” 하면 AI가 답하는 방식이죠.

그런데 도움말을 다시 읽다가 이런 줄을 봤습니다.

--ui=true    Enable HTTP graph visualization (persisted)
--port=N     Set UI port (default 9749, persisted)

브라우저로 여는 화면이 따로 있었습니다. 저는 몇 주를 쓰면서 몰랐어요.

켜는 법 — 이미 켜져 있을 수도 있습니다

먼저 설정부터 확인해 보세요.

codebase-memory-mcp config list

제 경우엔 이렇게 나왔습니다.

auto_index      = false
auto_watch      = true
ui_enabled      = true
ui_port         = 9749

ui_enabled가 이미 true였습니다. 켤 필요도 없이 돌고 있었던 거예요. 꺼져 있다면 이렇게 켭니다.

codebase-memory-mcp --ui=true --port=9749

그리고 브라우저에서 http://localhost:9749를 엽니다.

이 화면은 바이너리에 내장돼 있습니다. 따로 설치할 게 없고, 인터넷으로 나가지도 않아요. 내 PC 안에서만 도는 주소(127.0.0.1)입니다.

무엇이 보이나

첫 화면은 인덱싱해둔 프로젝트 목록입니다. 제 저장소는 이렇게 잡혔습니다.

Database healthy
501 nodes, 785 edges, 2.8 MB

이 숫자는 카드의 상태 점에 붙어 있습니다. 화면 위쪽 요약 타일은 그래프를 실제로 불러오기 전까지 0으로 보이는데, 고장이 아니라 아직 안 읽어온 것입니다.

인덱싱해둔 프로젝트 목록 — 저장소 경로와 함께 그래프 열기 버튼이 붙어 있다 — 인덱싱해둔 프로젝트 목록 — 저장소 경로와 함께 View Graph 버튼이 붙어 있다

View Graph를 누르면 본론입니다. 왼쪽에 필터가 붙는데, 내 코드가 어떤 종류의 조각으로 이뤄져 있는지가 숫자로 나옵니다.

노드 종류	개수
Section	203
Function	101
Variable · File · Module · EnvVar · Folder · Route · Branch	나머지

관계도 종류별로 갈라집니다 — defines 429 · calls 139 · usage 127 · imports · http calls 등. 원하는 관계만 켜서 볼 수 있어요. 호출 관계만 보고 싶으면 calls만 남기는 식입니다.

그래프 화면 — 왼쪽에 노드 종류·관계별 필터와 죽은 코드 표시, 아래쪽에 불러온 노드·엣지 수가 나온다

눈에 띈 기능이 하나 더 있었습니다. Dead code 항목인데, 아무도 호출하지 않는 코드를 세어 줍니다. 제 저장소는 0 dead였어요. 안 쓰는 코드가 없다는 뜻이라 반가웠습니다.

진짜 쓸모는 그래프가 아니라 로그에 있었습니다

솔직히 그래프 자체는 “예쁘다” 이상의 감흥은 없었습니다. 제 마음을 잡은 건 상단의 Control 탭이었어요.

여기엔 이 도구가 지금 무엇을 하고 있는지가 실시간 로그로 흐릅니다. 그리고 거기에 AI가 내 코드베이스에 던진 질문이 전부 찍혀 있었습니다.

mcp.request method=tools/call tool=list_projects      status=ok duration_ms=0
mcp.request method=tools/call tool=index_repository   status=ok duration_ms=10536
mcp.request method=tools/call tool=get_architecture   status=ok duration_ms=24
mcp.request method=tools/call tool=trace_path         status=ok duration_ms=28
mcp.request method=tools/call tool=trace_path         status=ok duration_ms=14

제가 AI에게 말로 부탁한 것들이 어떤 도구로 번역돼 몇 밀리초 걸렸는지까지 남습니다.

Control 탭 — 위쪽 자원 요약 아래로 프로세스 로그가 쌓인다. 화면에 보이는 줄은 전부 UI가 자기 자신을 폴링한 기록이다

다만 오래 못 봅니다 — 직접 재본 한계

위 화면을 보세요. 로그가 전부 component=graph_ui, 즉 이 화면이 스스로를 폴링한 기록입니다. 제가 던진 질의는 한 줄도 없어요.

이 페이지를 열어두면 초당 두 번씩 자기 요청을 로그에 씁니다. 버퍼는 100~200줄이고요. 계산이 그대로 나옵니다 — 도구 호출 기록은 1분 남짓이면 밀려납니다.

제가 조회한 실측입니다.

현재 로그 100줄
  UI 폴링(component=graph_ui) : 100줄 (100%)
  도구 호출(tool=)            : 0줄

그래서 질의를 던진 직후에 열어야 보입니다. 켜두고 나중에 보면 늦어요.

말 한마디가 어디를 거쳐 가나

제가 “이 함수 누가 호출해?”라고 부탁하면, 그 사이에 여러 단계가 있습니다. 평소에는 하나도 안 보이는 단계예요.

내 질문이 AI의 도구 선택과 데몬 조회를 거쳐 답으로 돌아오는 사이, 로그에 기록이 남는 흐름

AI는 제 말을 듣고 어떤 도구를 쓸지 스스로 고릅니다. 호출 관계를 물었으니 trace_path를 골랐고, 구조 개요를 물었을 땐 get_architecture를 골랐어요. 저는 도구 이름을 말한 적이 없습니다.

로그는 그 가운데 토막을 보여줍니다. 어떤 도구가 골라졌는지, 성공했는지, 몇 밀리초 걸렸는지. 답만 받아 보면 절대 알 수 없는 것들이죠.

쓰는 법은 이렇게 정리했습니다

AI에게 일을 시킬 때 가장 답답한 게 쟤가 지금 뭘 하고 있나를 모르는 것입니다. 이 로그가 그걸 덜어주긴 하는데, 켜두고 지켜보는 용도가 아니라 직후에 확인하는 용도입니다.

느린 작업을 하나 시키고 → 바로 Control을 열어 어느 도구에서 시간이 갔는지 본다. 이 순서면 제값을 합니다.

여기서 확인된 숫자들

지난 글에서 처음 한 번만 인덱싱하면 그 뒤로는 알아서 따라간다고 썼습니다. 그 문장의 증거가 이 로그에 있었습니다.

watcher.watch    project=... path=C:\Users\<사용자>\...
watcher.changed  strategy=git
index.supervisor.reap outcome=clean exit_code=0

watcher.changed → reap clean 쌍이 여섯 번 반복돼 있었습니다. 제가 파일을 고칠 때마다 자동으로 다시 색인한 기록이에요. 제가 시킨 적이 없습니다.

속도도 로그가 말해 줍니다.

작업	걸린 시간
첫 인덱싱(전체)	10,536ms ≈ 10.5초
구조 개요 조회	24ms
호출 관계 추적	28ms · 14ms

첫 한 번이 10초, 그 뒤 질의는 수십 밀리초. 목차를 만드는 데 10초 쓰고, 그다음부터는 목차를 넘겨보는 셈입니다.

자원도 찍힙니다. mem.init budget_mb=1958 total_ram_mb=7833 — 전체 램의 4분의 1쯤을 상한으로 잡고, 실제 사용은 Self RAM 12.7MB 수준이었습니다.

자주 묻는 질문

Q. 이 화면을 남이 볼 수 있나요?
아니요. 127.0.0.1은 내 PC 안에서만 닿는 주소입니다. 외부에서 접속되지 않습니다.

Q. 켜두면 무거운가요?
제 경우 자체 메모리 사용이 12~30MB 수준이었습니다. 로그에 physical_job_limit=4처럼 스스로 상한을 두는 값들도 보입니다.

Q. 여러 에이전트를 동시에 쓰면 화면이 여러 개 뜨나요?
아니요. 문서에 공유 데몬이 UI를 소유한다고 적혀 있습니다. 세션이 여럿이어도 HTTP 서버는 하나입니다.

Q. 그래프를 꼭 봐야 하나요?
안 봐도 도구는 잘 돕니다. 다만 처음 도입할 때 한 번은 열어보시길 권합니다. 인덱싱이 제대로 됐는지, 내 코드가 어떻게 잡혀 있는지를 눈으로 확인하는 데 5분이면 충분합니다.

그래서 뭘 하면 되나

상황	할 것
인덱싱이 됐는지 모르겠다	🔴 `localhost:9749` 열어 노드·엣지 수 확인
AI가 왜 느린지 모르겠다	🔴 시킨 직후에 `Control` 탭 열기 — 늦으면 폴링에 밀린다
자동 갱신이 도는지 궁금하다	🟡 로그에서 `watcher.changed` 찾기
안 쓰는 코드를 찾고 싶다	🟡 그래프 필터의 `Dead code`

한 문장으로 요약하면 이렇습니다. AI에게 도구를 붙였으면, 그 도구가 무엇을 하고 있는지 볼 창구도 함께 열어두세요.

말로 묻고 답을 받는 것만으로도 도구는 굴러갑니다. 하지만 뭔가 이상할 때 들여다볼 곳이 없으면 원인을 짐작으로만 좁히게 됩니다. 이 도구는 그 창구를 기본으로 켜둔 채 조용히 돌고 있었고, 저는 몇 주 동안 그걸 모르고 썼습니다.