adrkit MCP의 개요
adrkit은 아키텍처 결정 기록(ADR, 설계상의 선택과 그 이유를 적은 짧은 문서)을 타입이 있는 데이터로 다룹니다. git에 있는 Markdown 파일에 YAML 프런트매터, accepted·rejected·superseded 같은 상태, 각 결정을 경로나 패키지에 연결하는 affects 필드를 둡니다. @adrkit/mcp 패키지는 로컬 stdio 서버로, 에이전트가 이 코퍼스를 검색하고, 기록을 가져오고, 여러 파일을 규율하는 결정을 나열하고, 대체된 결정을 나열할 수 있게 합니다.
프로젝트는 Mark Beacom(GitHub 사용자 mbeacom)이 만들었고, Apache-2.0 라이선스이며 Node 22 이상용 TypeScript로 작성되었습니다. 공식 MCP 레지스트리에는 dev.adrkit/mcp로 등록되어 있습니다. 버전 0.20.0은 2026년 10월 11일에 나왔고, 저장소의 스타는 24개, 마지막 push는 11월 7일이었습니다. 같은 모노레포에는 CLI, 풀 리퀘스트에 해당 결정을 댓글로 다는 GitHub Action, Claude Code와 Copilot용 플러그인도 들어 있습니다.
adrkit MCP 설치 방법
npx -y @adrkit/mcp --cwd /path/to/repo --dir docs/adradrkit MCP, 쓸 만한 가치가 있습니까?
adrkit 서버의 핵심은 '무덤'입니다. list_superseded와 get_decision_context의 이력 섹션은 채택된 결정과 함께 기각되거나 대체된 결정도 돌려줍니다. 그래서 src/db/ 변경을 계획하는 에이전트는 MySQL을 다시 제안하기 전에 MySQL이 시도되었다가 교체되었다는 사실을 봅니다. 일반적인 메모리 서버는 에이전트가 저장하기로 한 것을 보관하지만, 이 서버는 사람이 검토하고 병합한 기록을 읽습니다.
제공하는 도구는 4개이며, 모두 읽기 전용이자 닫힌 세계(closed-world)로 표시되어 있습니다. search_decisions(id, 제목, 태그, 본문에 대한 문자 그대로의 부분 문자열 검색), get_decision, 저장소 기준 상대 경로 파일 최대 256개를 다루는 get_decision_context, list_superseded입니다. get_decision_context는 경로를 각 기록의 affects 패턴과 비교할 뿐 파일을 열지 않습니다. 결과는 기본 20개, 최대 100개씩 페이지로 나뉘며, 64 KiB를 넘는 기록은 잘라 내지 않고 경고와 함께 제외됩니다. 덕분에 컨텍스트 비용이 작고 예측 가능합니다.
주의할 점: 가치는 대부분의 팀에 없는 코퍼스에 전적으로 달려 있습니다. 기록에는 adrkit 프런트매터가 필요하고, 파일 매칭을 위해서는 잘 관리된 affects 필드도 필요합니다. adr migrate --from madr가 기존 MADR 코퍼스에 이를 추가해 주지만, 패턴은 여전히 누군가 써야 합니다. 프로젝트는 1.0 이전이며 README 스스로 버전을 고정하라고 권합니다. 검색은 문자 그대로의 부분 문자열 일치이며 설계상 순위나 임베딩이 없으므로, 에이전트는 기록에 쓰인 단어를 짐작해야 합니다. 에이전트 플러그인은 일부러 MCP 설정을 포함하지 않는데, Copilot CLI가 플러그인 서버를 저장소 밖에서 실행하기 때문입니다. 그래서 프로젝트마다 서버를 직접 연결해야 합니다.
보안 면에서는 MCP 서버가 가질 수 있는 거의 가장 좁은 범위입니다. 하나의 git 워크트리 안 한 디렉터리 아래의 Markdown만 읽고, 심볼릭 링크를 통한 탈출을 거부하며, 모델이나 네트워크를 호출하지 않고, 포트를 열지 않으며, 아무것도 쓰지 않습니다. 프롬프트 인젝션 노출 지점은 기록 본문 자체이며, 저장소에 병합할 수 있는 사람이면 누구나 이를 고칠 수 있습니다. 컨테이너 이미지에 있는 별도의 REST 서버는 사정이 다릅니다. 누구도 인증하지 않으며, README는 그 포트에 닿을 수 있는 사람이면 누구나 제공되는 모든 코퍼스를 읽을 수 있다고 경고합니다.
제 역할을 하는 곳
docs/adr에 ADR 60개를 둔 8명 규모의 플랫폼 팀
팀이 작년에 기각한 큐 시스템을 코딩 에이전트가 다시 제안하지 못하게 하기
프로젝트의 .vscode/mcp.json이나 Claude 설정에 서버를 추가하고, 계획 전에 파일에 대해 get_decision_context를 호출하라고 에이전트에 지시합니다. 기각된 기록이 이력에 나타납니다. 무료이며, migrate 한 번 실행과 affects 패턴 몇 개 작성이 필요합니다.
에이전트가 쓴 계획을 검토하는 스태프 엔지니어
제안된 변경이 어떤 채택된 결정에 걸리는지 확인하기
에이전트가 계획이 바꾸는 파일을 나열하고 get_decision_context를 호출한 뒤, 해당하는 각 기록에 get_decision을 호출해 제약을 인용하게 합니다. 같은 답을 풀 리퀘스트에 올려 주는 GitHub Action과 잘 맞습니다.
MADR 파일이 있는 고객 코드베이스를 넘겨받은 컨설팅 회사
지식 베이스를 따로 만들지 않고 고객의 결정 이력을 에이전트에 제공하기
adr migrate --from madr를 실행해 adrkit 프런트매터를 제자리에 추가하고, --cwd로 adrkit-mcp를 저장소에 지정합니다. 스키마가 상위 집합이므로 기존 MADR 도구도 계속 작동합니다.
도입 전 확인할 점
- 설정
- Node 22+에서 npx -y @adrkit/mcp --cwd /path/to/repo --dir docs/adr를 실행하거나, ghcr.io/mbeacom/adrkit 이미지를 mcp와 읽기 전용 마운트로 씁니다. README 설정 예시는 Claude Desktop, VS Code, Cursor, GitHub Copilot CLI를 다룹니다. --cwd는 git 워크트리의 루트여야 합니다.
- 연동
- 읽기 전용 도구 4개: search_decisions, get_decision, get_decision_context, list_superseded입니다. stdio로 2025년판과 2026-07-28판 MCP 프로토콜을 모두 지원합니다. 프로젝트 전체로는 CLI, 풀 리퀘스트용 Action, Spec Kit 확장, 에이전트 플러그인이 더 있습니다.
- 데이터와 개인정보
- 한 저장소 안 한 ADR 디렉터리 아래의 Markdown 기록을 읽으며, 심볼릭 링크 탈출을 realpath로 검사합니다. 쓰기, 모델 호출, 네트워크 접근, 영구 색인이 없고 포트도 없습니다. 에이전트는 기록 본문을 신뢰하므로 docs/adr에 대한 병합 권한을 그에 맞게 관리하세요. 컨테이너의 별도 REST 서버에는 인증이 없습니다.
- 대규모 사용 시 비용
- Apache-2.0으로 무료입니다. tools/call마다 코퍼스를 다시 읽으므로 비용은 로컬 파일 읽기뿐이며, 출력 페이지는 최대 100개 항목입니다.
- 제한
- 열린 이슈는 약 12개입니다. 검색은 문자 그대로만 되고, 대체 관계는 한 단계만 따라가며, 연합 log:id 참조는 인식하지만 해석하지 않습니다. 서버 하나당 코퍼스 하나이며, Copilot CLI 플러그인 호스트에서는 실행할 수 없습니다.
좋은 점
- 기각되거나 대체된 결정을 보여 줌
- 읽기 전용 도구 4개, 네트워크·모델·쓰기 없음
- 패턴으로 파일과 규율하는 결정을 연결
- 제한되고 페이지로 나뉜 출력으로 컨텍스트를 작게 유지
아쉬운 점
- adrkit 형식의 ADR 코퍼스가 없으면 쓸모없음
- 문자 그대로의 부분 문자열 검색만 지원, 순위 없음
- 1.0 이전이며 프로젝트가 버전 고정을 권함
- 프로젝트마다 서버를 직접 연결해야 함
추천 대상
이미 git에 아키텍처 결정 기록을 두고 있고, 코딩 에이전트가 설계를 제안하기 전에 이를 확인하게 하려는 팀에 맞습니다.
adrkit MCP 대안
adrkit MCP: 자주 묻는 질문
- adrkit MCP, 쓸 만한 가치가 있습니까?
- 팀이 이미 기각한 길로 에이전트가 가지 않게 막는 한 가지 일을 잘하는 작고 엄격한 읽기 전용 서버이지만, 결정이 adrkit 형식으로 적혀 있어야 합니다. 평점은 5점 만점에 3.6점입니다.
- adrkit MCP의 가격은 얼마입니까?
- 무료 오픈소스(Apache-2.0, 스키마는 CC0이기도 함)입니다. 호스팅 서비스나 유료 요금제가 없습니다.
- adrkit MCP의 단점은 무엇입니까?
- adrkit 형식의 ADR 코퍼스가 없으면 쓸모없음; 문자 그대로의 부분 문자열 검색만 지원, 순위 없음; 1.0 이전이며 프로젝트가 버전 고정을 권함; 프로젝트마다 서버를 직접 연결해야 함.
- adrkit MCP에 적합한 사람은 누구입니까?
- 이미 git에 아키텍처 결정 기록을 두고 있고, 코딩 에이전트가 설계를 제안하기 전에 이를 확인하게 하려는 팀에 맞습니다.
- 팀이나 프로덕션 환경에서 adrkit MCP의 비용은 얼마입니까?
- Apache-2.0으로 무료입니다. tools/call마다 코퍼스를 다시 읽으므로 비용은 로컬 파일 읽기뿐이며, 출력 페이지는 최대 100개 항목입니다.
- adrkit MCP에 회사 데이터를 맡겨도 안전합니까?
- 한 저장소 안 한 ADR 디렉터리 아래의 Markdown 기록을 읽으며, 심볼릭 링크 탈출을 realpath로 검사합니다. 쓰기, 모델 호출, 네트워크 접근, 영구 색인이 없고 포트도 없습니다. 에이전트는 기록 본문을 신뢰하므로 docs/adr에 대한 병합 권한을 그에 맞게 관리하세요. 컨테이너의 별도 REST 서버에는 인증이 없습니다.
- adrkit MCP의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 MCP Memory Keeper, Memory (reference server) 및 codebase-memory-mcp입니다.
답변 확인일: 2026년 11월 11일.