mcp-adr-analysis-server

지능형 개발 워크플로우를 위한 AI 기반 아키텍처 분석. 다른 곳에 제출할 프롬프트가 아닌 실제 분석 결과를 반환합니다.

**Model Context Protocol (MCP)**는 AI 어시스턴트와 외부 도구 및 데이터 소스 간의 원활한 통합을 가능하게 하는 개방형 표준입니다. 이를 Claude, Cline, Cursor와 같은 AI 어시스턴트가 전문 분석 서버에 연결할 수 있게 해주는 범용 어댑터라고 생각하면 됩니다. 이 서버는 AI 어시스턴트에 심층적인 아키텍처 분석 능력을 부여하여, 지능적인 코드 생성, 의사결정 추적 및 개발 워크플로우 자동화를 가능하게 합니다.

무엇인가 (What): AI 기반 아키텍처 결정 분석 및 ADR (Architectural Decision Record) 관리를 제공하는 MCP 서버

누구를 위한 것인가 (Who): AI 코딩 어시스턴트 (Claude, Cline, Cursor), 엔터프라이즈 아키텍트, 개발 팀

왜 필요한가 (Why): 프롬프트 대신 95%의 신뢰도 점수와 함께 즉각적인 아키텍처 통찰력을 얻기 위해

어떻게 사용하는가 (How): npm install -g mcp-adr-analysis-server

→ OpenRouter API로 구성 → 분석 시작

주요 기능 (Key Features): Tree-sitter AST (Abstract Syntax Tree) 분석 • 보안 콘텐츠 마스킹 (Security content masking) • 테스트 주도 개발 (TDD) • 배포 준비성 검증 (Deployment readiness validation)

주요 용어 (Key Terms)

용어 (Term)	정의 (Definition)
ADR	Architectural Decision Record (아키텍처 결정 기록) — 중요한 아키텍처 결정 사항을 그 맥락, 고려된 대안, 그리고 결과와 함께 기록하는 문서입니다.
MCP	Model Context Protocol (모델 컨텍스트 프로토콜) — AI 어시스턴트가 외부 도구 및 데이터 소스에 연결할 수 있도록 지원하는 개방형 표준입니다.
Tree-sitter	50개 이상의 언어에 대해 AST (Abstract Syntax Tree, 추상 구문 트리) 분석을 제공하는 증분 파싱 (Incremental parsing) 라이브러리입니다. 의미론적 코드 이해, 함수 시그니처 추출, 아키텍처 패턴 식별에 사용됩니다.
Knowledge Graph (지식 그래프)	ADR, 코드 구현, 아키텍처 결정 간의 관계를 추적하기 위해 서버에서 유지 관리하는 그래프 데이터베이스입니다. 지능적인 코드 연결 및 영향 분석 (Impact analysis)을 가능하게 합니다.
Smart Code Linking (스마트 코드 연결)	키워드 추출 및 의미론적 검색 (Semantic search)을 사용하여 ADR 및 아키텍처 결정과 관련된 코드 파일을 AI 기반으로 찾아내는 기능입니다.
Firecrawl	선택적 연구 도구(FIRECRAWL_API_KEY)에서 사용되는 웹 페이지 추출/검색 서비스입니다.
ADR Aggregator	팀 간에 ADR 컨텍스트를 동기화하고 공유하기 위한 선택적 SaaS 통합 기능입니다 (ADR_AGGREGATOR_API_KEY).

저자 (Author): Tosin Akinosho | 저장소 (Repository): GitHub

🤖 AI 기반 분석 (AI-Powered Analysis) - OpenRouter.ai 통합을 통한 즉각적인 아키텍처 통찰력 제공
🏗️ 기술 탐지 (Technology Detection) - 모든 기술 스택 및 아키텍처 패턴 식별
📋 ADR 관리 (ADR Management) - 아키텍처 결정 기록 (Architectural Decision Records) 생성, 제안 및 유지 관리
🔗 스마트 코드 연결 (Smart Code Linking) - ADR 및 결정과 관련된 코드 파일을 AI 기반으로 탐색
🛡️ 보안 및 준수 (Security & Compliance) - 민감한 콘텐츠를 자동으로 탐지하고 마스킹 처리
🧪 TDD 통합 (TDD Integration) - 검증을 포함한 2단계 주도 개발 (Test-Driven Development)
🚀 배포 준비성 (Deployment Readiness) - 강력한 차단 기능을 갖춘 제로 톨러런스 (Zero-tolerance) 테스트 검증

📖 전체 기능 보기 → · 📜 릴리스 정책 → · 🗒️ 변경 이력 (Changelog) →

설치하기 전에 다음 사항을 확인하십시오:

node --version # v20.0.0 이상이어야 합니다
npm --version # 9.0.0 이상이어야 합니다 (Node.js 20+에 포함됨)

필수 사항:

Node.js 20.0.0 이상— 다운로드하거나 nvm/fnm을 사용하십시오
npm 9.0.0 이상(Node.js 20+에 포함됨)
MCP 호환 클라이언트 (MCP-compatible client)— Claude Desktop, Cline, Cursor 또는 Windsurf

npm install 실행 중 인터넷 접속이 필요합니다

네이티브 모듈 컴파일(YAML 및 TypeScript용 tree-sitter 증분 코드 파서)을 위해 필요합니다. 만약 기업용 프록시(corporate proxy) 환경 뒤에 있다면, HTTP_PROXY 및 HTTPS_PROXY 환경 변수를 설정하십시오. 오프라인 폴백 (Offline fallback): 네이티브 빌드에 실패할 경우, 서버는 tree-sitter 코드 분석 기능이 제외된 축소 모드(reduced mode)로 작동합니다.

# 옵션 1: 전역 설치 (자주 사용하는 경우 권장)
npm install -g mcp-adr-analysis-server
# 옵션 2: npx 사용 (설치 불필요)
...

참고: 소스에서 설치할 때는 bin이 ./dist/src/index.js를 가리키므로, 서버를 실행하기 전에 npm run build가 반드시 필요합니다.

📖 상세 설치 가이드 (Detailed Installation Guide) → | RHEL 설정 (RHEL Setup) →

API 키 가져오기: OpenRouter.ai/keys에서 가입하십시오 — OpenRouter는 단일 키를 통해 여러 AI 모델(Claude, GPT 등)에 대한 접근을 제공하는 API 게이트웨이(API gateway)입니다. API 키가 없습니까? 서버는 여전히 프롬프트 전용 모드(prompt-only mode)로 작동합니다 — 아래의 실행 모드(Execution Modes)를 참조하십시오.

환경 변수 설정 (Set Environment):
OPENROUTER_API_KEY=your_key

+EXECUTION_MODE=full

클라이언트 설정 (Configure Client): Claude Desktop, Cline, Cursor 또는 Windsurf에 추가하십시오.

{
"mcpServers": {
"adr-analysis": {
...

Claude Desktop 사용자:
이 JSON을 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 저장하십시오.

기타 클라이언트의 설정 위치 (Config locations for other clients)

기타 클라이언트의 설정 위치 (Config locations for other clients)

Client	Config file location
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cline (VS Code)	VS Code 설정 → Cline → MCP Servers (또는 .vscode/cline_mcp_settings.json)
Cursor	Cursor 설정 → MCP → 서버 추가 (Add Server)

ADR Aggregator 사용 시 (선택 사항)

{
"mcpServers": {
"adr-analysis": {
...

API 키는 adraggregator.com에서 받으세요.

📖 전체 설정 가이드 → | 클라이언트 설정 →

전체 모드 (Full Mode)	프롬프트 전용 모드 (Prompt-Only Mode)
요구되는 API 키?	예 (OPENROUTER_API_KEY)
반환값	신뢰 점수가 포함된 실제 분석 결과
설정 방법	EXECUTION_MODE=full
최적의 용도	프로덕션 사용, 자동화
사용 가능한 기능	모든 73개 도구, AI 분석, 신뢰 점수 산정, 스마트 코드 링크(Smart Code Linking), 지식 그래프(Knowledge Graph)
사용 불가능한 기능	—

팁: 도구 카탈로그를 탐색하려면 프롬프트 전용 모드부터 시작하세요. API 키 없이 프로젝트 분석, ADR 발견 및 템플릿 생성이 가능합니다. AI 기반 분석과 신뢰 점수 산정이 필요할 때 API 키를 추가하세요.

MCP 클라이언트에게 자연어로 질문하기만 하면 됩니다. 코드는 필요 없습니다:

"이 React 프로젝트의 아키텍처를 분석하고 암시적인 결정에 대한 ADR을 제안해 주세요"

"PRD.md 파일에서 ADR을 생성하고 구현 작업을 담은 todo.md 파일을 만들어 주세요"

"이 코드베이스의 보안 문제를 확인하고 마스킹 권장 사항을 제공해 주세요"

서버는 다른 곳에 제출할 프롬프트가 아닌 실제 분석 결과를 반환합니다!

프로그래밍 방식 사용 (고급)

MCP SDK를 통해 서버를 자체 도구에 통합하는 경우:

// 기본 프로젝트 분석
const analysis = await analyzeProjectEcosystem({
projectPath: '/path/to/project',
...

📖 전체 사용 가이드 (Complete Usage Guide) → | API 레퍼런스 (API Reference) →

직접 시도해 보세요: 이 저장소에는 예시 ADR 및 소스 코드가 포함된 sample-project/ 디렉토리가 포함되어 있습니다. 자신의 코드베이스에 영향을 주지 않고 실험하려면 PROJECT_PATH를 해당 디렉토리로 지정하세요.

참고: 샘플 프로젝트는 소스에서 클론할 때만 사용할 수 있습니다(위의 옵션 3). 만약 npm을 통해 설치했다면(옵션 1 또는 2), 샘플에 접근하기 위해 직접 테스트 프로젝트를 생성하거나 저장소를 별도로 클론하세요: git clone --depth 1 https://github.com/tosin2013/mcp-adr-analysis-server.git sample-test

👨💻 AI 코딩 어시스턴트 (AI Coding Assistants) - Claude, Cline, Cursor를 아키텍처 지능으로 강화

💬 대화형 AI (Conversational AI) - 신뢰도 점수(confidence scoring)와 함께 아키텍처 질문에 답변

🤖 자율 에이전트 (Autonomous Agents) - 지속적인 분석 및 규칙 강제 적용

🏢 엔터프라이즈 팀 (Enterprise Teams) - 포트폴리오 분석 및 마이그레이션 계획

런타임 (Runtime): Node.js 20+ • 언어 (Language): TypeScript • 프레임워크 (Framework): MCP SDK • 테스트 (Testing): Jest (>80% 커버리지)
검색 (Search): ripgrep (빠른 재귀적 텍스트 검색) + fast-glob (파일 매칭) • AI 통합 (AI Integration): OpenRouter.ai • 웹 리서치 (Web Research): Firecrawl (웹 페이지 추출 API) • 코드 분석 (Code Analysis): tree-sitter (증분 코드 파서) + Smart Code Linking

📖 기술 세부 사항 (Technical Details) → | CE-MCP 마이그레이션 플레이북 (CE-MCP Migration Playbook) →

src/tools/ # 분석을 위한 73개의 MCP 도구
docs/adrs/ # 아키텍처 결정 기록 (Architectural Decision Records)
tests/ # >80% 테스트 커버리지
...

npm test # 모든 테스트 실행 (>80% 커버리지)
npm run test:coverage # 커버리지 보고서

포괄적인 아키텍처 분석을 위한 강화된 웹 리서치 기능.

참고: 기본적인 ADR 분석에는 Firecrawl가 필요하지 않습니다. 서버는 Firecrawl 없이도 완전히 작동합니다. 외부 소스를 사용하는 perform_research 도구와 같은 웹 리서치 기능이 필요한 경우에만 Firecrawl을 구성하세요.

Firecrawl은 언제 유용한가요?

ADR 리서치 (ADR research)— ADR을 생성할 때 공식 문서로부터 베스트 프랙티스(best practices)를 자동으로 가져옵니다
기술 평가 (Technology evaluation)— 프레임워크의 문서와 변경 로그(changelog)를 크롤링하여 비교합니다
보안 감사 (Security audits)— 의존성(dependencies)에 대한 CVE 데이터베이스 및 보안 권고 사항을 확인합니다
마이그레이션 계획 (Migration planning)— 업스트림(upstream) 프로젝트로부터 마이그레이션 가이드와 중대한 변경 사항(breaking-change) 노트를 수집합니다

# Option 1: Cloud service (recommended)
export FIRECRAWL_ENABLED="true"
export FIRECRAWL_API_KEY="fc-your-api-key-here"
...

ADR Aggregator는 팀 간 ADR 가시성(visibility)과 거버넌스(governance)를 위한 플랫폼입니다. 다음과 같은 기능을 제공합니다:

교차 리포지토리 지식 그래프 (Cross-repository knowledge graphs)— 프로젝트 전반에 걸쳐 아키텍처 결정이 어떻게 연관되어 있는지 확인합니다
거버넌스 대시보드 (Governance dashboards)— ADR 준수 여부, 노후화(staleness), 검토 주기(review cycles)를 추적합니다
템플릿 라이브러리 (Template library)— 도메인별 ADR 템플릿(보안, API, 데이터베이스 등)에 접근합니다
팀 협업 (Team collaboration)— 조직 전체에 아키텍처 결정을 공유합니다

참고: ADR Aggregator는 선택 사항입니다. 모든 핵심 분석 기능은 이것 없이도 작동합니다.

# Set your API key (get one at adraggregator.com)
export ADR_AGGREGATOR_API_KEY="agg_your_key_here"

도구 (Tool)	설명 (Description)	Free	Pro+	Team
sync_to_aggregator	로컬 ADR을 플랫폼으로 푸시(Push)	✅	✅	✅
get_adr_context	플랫폼에서 ADR 컨텍스트를 가져옴 (Pull)	✅	✅	✅
get_staleness_report	ADR 거버넌스/상태 보고서 획득	✅	✅	✅
get_adr_templates	도메인별 템플릿 검색	✅	✅	✅
get_adr_diagrams	ADR을 위한 Mermaid 다이어그램 획득	—	✅	✅
validate_adr_compliance	ADR 구현 준수 여부 검증	—	✅	✅
get_knowledge_graph	교차 리포지토리 지식 그래프	—	—	✅

# 1. 암시적 아키텍처 결정을 위해 코드베이스 분석
suggest_adrs(analysisType: 'implicit_decisions')
# 2. 제안된 내용을 바탕으로 ADR 파일 생성
...

이점 (Benefits): 팀 간 가시성 • 노후화 알림 • 준수 사항 추적 • 조직 전체 지식 그래프

📖 ADR Aggregator 가이드 → | 📖 MCP 통합 가이드 →

git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install && npm run build && npm test

품질 표준 (Quality Standards): TypeScript strict mode • ESLint • 80% 이상의 테스트 커버리지 (test coverage) • Pre-commit hooks

API 문서는 TypeDoc으로 생성됩니다:

npm install # 클론 후 최초 1회 실행 필요 (typedoc 설치)
npm run docs:build # docs/api/ 경로에 API 문서 생성
npm run docs:serve # Python HTTP 서버를 통해 로컬에서 실행

그 다음 브라우저에서 http://localhost:8080을 여세요. Markdown 문서는 docs/ 디렉토리에 있으며 GitHub에서 직접 찾아볼 수 있습니다.

📖 개발 가이드 (Development Guide) → | 기여하기 (Contributing) →

일반적인 문제 (Common Issues):

RHEL 시스템: 전용 설치 스크립트를 사용하세요
도구가 프롬프트를 반환하는 경우: EXECUTION_MODE=full로 설정하세요

• API 키
  모듈을 찾을 수 없음 (Module not found): npm install && npm run build를 실행하세요

권한 거부 (Permission denied): 파일 권한 및 프로젝트 경로를 확인하세요

보안 (Security): 자동 비밀 정보 탐지 (Automatic secret detection) • 콘텐츠 마스킹 (Content masking) • 로컬 처리 (Local processing) • 제로 트러스트 (Zero trust)

성능 (Performance): 다단계 캐싱 (Multi-level caching) • 증분 분석 (Incremental analysis) • 병렬 처리 (Parallel processing) • 메모리 최적화 (Memory optimization)

📖 보안 가이드 (Security Guide) → | 성능 (Performance) →

보안 문제를 발견하셨나요? 책임 있는 공개 절차를 위해 보안 정책 (Security Policy)을 읽어주세요. 보안 취약점에 대해 공개 이슈 (public issues)를 생성하지 마십시오.

여러분의 기여를 환영합니다! 버그 수정, 기능 추가, 또는 문서 개선 등 어떤 형태든 여러분의 도움은 큰 힘이 됩니다.

**저장소를 포크 (Fork)**하세요
**포크한 저장소를 클론 (Clone)**하세요: git clone https://github.com/YOUR_USERNAME/mcp-adr-analysis-server.git

**브랜치를 생성 (Create)**하세요: git checkout -b feature/your-feature-name

**테스트와 함께 변경 사항 적용 (Make)**하세요
테스트 (Test): npm test (80% 이상의 커버리지를 유지하세요)

풀 리퀘스트 (Pull Request) 제출

적절한 첫 번째 이슈를 찾고 계신가요? 우리의 good first issues를 확인해 보세요. 시작하기에 완벽한 초보자 친화적인 작업들입니다!

오픈 소스가 처음이신가요? 우리의 기여 가이드 (Contributing Guide)가 전체 과정을 단계별로 안내해 드립니다.