FileScopeMCP(모델 컨텍스트 프로토콜) 서버

✨ 코드베이스 구조와 종속성을 즉시 이해하고 시각화하세요! ✨

코드베이스의 파일을 중요도에 따라 순위를 매기고, 종속성을 추적하고, 코드 구조를 이해하는 데 도움이 되는 요약을 제공하는 TypeScript 기반 도구입니다.

개요

이 MCP 서버는 코드베이스를 분석하여 종속성 관계를 기반으로 가장 중요한 파일을 식별합니다. 각 파일에 대한 중요도 점수(0~10점)를 생성하고, 양방향 종속성을 추적하며, 파일에 대한 사용자 지정 요약을 추가할 수 있도록 합니다. 이 모든 정보는 Cursor의 모델 컨텍스트 프로토콜을 통해 AI 도구에 제공됩니다.

특징

🚀 코드 이해도를 대폭 향상하세요! FileScopeMCP는 AI 어시스턴트에게 직접 인사이트를 제공합니다.

• 🎯 파일 중요도 분석
  • 코드베이스에서의 역할에 따라 0~10점 척도로 파일의 순위를 매깁니다.
  • 수신/발신 종속성을 사용하여 중요도를 계산합니다.
  • 프로젝트에서 가장 중요한 파일을 즉시 찾아냅니다.
  • 스마트 계산은 파일 유형, 위치, 이름의 중요성을 고려합니다.
• 🔗 종속성 추적
  • 파일 간의 양방향 종속 관계를 매핑합니다.
  • 주어진 파일을 가져오는 파일(종속 파일)을 식별합니다.
  • 주어진 파일이 어떤 파일을 가져왔는지 확인합니다(종속성).
  • 로컬 종속성과 패키지 종속성을 구분합니다.
  • 다국어 지원: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.
• 📊 시각화
  • 인어 다이어그램을 생성하여 파일 관계를 시각화합니다.
  • 중요도 점수에 따라 색상으로 구분된 시각화입니다.
  • 종속성 그래프, 디렉토리 트리 또는 하이브리드 뷰를 지원합니다.
  • 테마 토글 및 반응형 디자인을 포함한 내장 렌더링이 포함된 HTML 출력입니다.
  • 다이어그램 깊이를 사용자 지정하고, 중요도에 따라 필터링하고, 레이아웃 옵션을 조정합니다.
• 📝 파일 요약
  • 모든 파일에 사람이나 AI가 생성한 요약을 추가합니다.
  • 저장된 요약을 검색하여 파일의 목적을 빠르게 파악합니다.
  • 요약은 서버를 다시 시작해도 그대로 유지됩니다.
• 📚 다양한 프로젝트 지원
  • 다양한 프로젝트 영역에 대해 여러 개의 파일 트리를 만들고 관리합니다.
  • 서로 다른 기본 디렉토리로 별도의 트리를 구성합니다.
  • 다양한 파일 트리 사이를 손쉽게 전환하세요.
  • 후속 작업을 더 빠르게 하기 위해 캐시된 트리입니다.
• 💾 영구 저장소
  • 모든 데이터는 JSON 형식으로 디스크에 자동으로 저장됩니다.
  • 파일 시스템을 다시 검사하지 않고 기존 파일 트리를 로드합니다.
  • 파일 트리가 마지막으로 업데이트된 시점을 추적합니다.

설치

1. 이 저장소를 복제하세요
2. 프로젝트를 빌드하세요:빌드 스크립트는 모든 노드 종속성을 설치하고 mcp.json을 생성합니다.윈도우:지엑스피1생성된 mcp.json 구성을 프로젝트의 .cursor 디렉토리에 복사합니다.
   { "mcpServers": { "FileScopeMCP": { "command": "node", "args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }
   Linux: (커서는 Windows에 있지만 프로젝트는 Linux WSL에 있는 경우 MCP를 Linux에 넣고 빌드합니다)
   build.sh
   { "mcpServers": { "FileScopeMCP": { "command": "wsl", "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }
3. 인수 경로 --base-dir을 프로젝트의 기본 경로로 업데이트합니다.

작동 원리

종속성 감지

이 도구는 소스 코드에서 가져오기 명령문과 기타 언어별 패턴을 검색합니다.

• Python: import 및 from ... import 문
• JavaScript/TypeScript: import 문과 require() 호출
• C/C++: #include 지시어
• Rust: use 및 mod 명령문
• Lua: require 문
• Zig: @import 지시어

중요도 계산

파일에는 다음을 고려하는 가중치 공식에 따라 중요도 점수(0~10)가 지정됩니다.

• 이 파일을 가져오는 파일 수(종속 파일)
• 이 파일이 가져오는 파일 수(종속성)
• 파일 유형 및 확장자(TypeScript/JavaScript 파일이 더 높은 기본 점수를 받음)
• 프로젝트 구조 내 위치( src/ 에 있는 파일이 더 높은 가중치를 가짐)
• 파일 이름 지정('index', 'main', 'server' 등과 같은 파일은 추가 점수를 받습니다)

코드베이스의 핵심인 파일(많은 파일에서 가져옴)은 점수가 더 높습니다.

다이어그램 생성

이 시스템은 유효한 Mermaid 구문을 생성하기 위해 3단계 접근 방식을 사용합니다.

1. 수집 단계: 모든 노드와 관계 등록
2. 노드 정의 단계: 참조하기 전에 모든 노드에 대한 정의를 생성합니다.
3. 에지 생성 단계: 정의된 노드 사이에 에지를 생성합니다.

이렇게 하면 모든 다이어그램의 구문이 유효하고 올바르게 렌더링됩니다. HTML 출력에는 다음이 포함됩니다.

• 모든 기기에서 작동하는 반응형 디자인
• 시스템 환경 설정 감지를 통한 밝음/어둠 테마 전환
• 최적의 성능을 위한 클라이언트 측 Mermaid 렌더링
• 생성 타임스탬프

경로 정규화

시스템은 일관된 파일 식별을 보장하기 위해 다양한 경로 형식을 처리합니다.

• Windows 및 Unix 경로 형식
• 절대 경로와 상대 경로
• URL로 인코딩된 경로
• 크로스 플랫폼 호환성

파일 저장소

모든 파일 트리 데이터는 다음 구조의 JSON 파일에 저장됩니다.

• 구성 메타데이터(파일 이름, 기본 디렉토리, 마지막 업데이트 타임스탬프)
• 종속성, 종속 항목, 중요도 점수 및 요약을 포함한 전체 파일 트리

기술적 세부 사항

• TypeScript/Node.js : 유형 안전성과 최신 JavaScript 기능을 위해 TypeScript로 구축됨
• 모델 컨텍스트 프로토콜 : 커서와의 통합을 위한 MCP 사양을 구현합니다.
• Mermaid.js : 다이어그램 생성을 위해 Mermaid 구문을 사용합니다.
• JSON 저장소 : 지속성을 위해 간단한 JSON 파일을 사용합니다.
• 경로 정규화 : Windows 및 Unix를 지원하기 위한 크로스 플랫폼 경로 처리
• 캐싱 : 반복되는 작업을 더 빠르게 처리하기 위해 캐싱을 구현합니다.

사용 가능한 도구

MCP 서버는 다음 도구를 제공합니다.

파일 트리 관리

• list_saved_trees : 저장된 모든 파일 트리를 나열합니다.
• create_file_tree : 특정 디렉토리에 대한 새로운 파일 트리 구성을 생성합니다.
• select_file_tree : 작업할 기존 파일 트리를 선택합니다.
• delete_file_tree : 파일 트리 구성 삭제

파일 분석

• list_files : 프로젝트의 모든 파일을 중요도 순위와 함께 나열합니다.
• get_file_importance : 종속성 및 종속 항목을 포함하여 특정 파일에 대한 자세한 정보를 가져옵니다.
• find_important_files : 구성 가능한 기준에 따라 프로젝트에서 가장 중요한 파일을 찾습니다.
• read_file_content : 특정 파일의 내용을 읽습니다.
• recalculate_importance : 종속성을 기반으로 모든 파일의 중요도 값을 다시 계산합니다.

파일 요약

• get_file_summary : 특정 파일의 저장된 요약을 가져옵니다.
• set_file_summary : 특정 파일의 요약을 설정하거나 업데이트합니다.

파일 감시

• toggle_file_watching : 파일 감시 켜기/끄기
• get_file_watching_status : 파일 감시의 현재 상태를 가져옵니다.
• update_file_watching_config : 파일 감시 구성 업데이트

다이어그램 생성

• generate_diagram : 사용자 정의 가능한 옵션으로 인어 다이어그램을 만듭니다.
  • 출력 형식: 인어 텍스트( .mmd ) 또는 내장 렌더링이 포함된 HTML
  • 다이어그램 스타일: 기본, 종속성, 디렉터리 또는 하이브리드 뷰
  • 필터 옵션: 최대 깊이, 최소 중요도 임계값
  • 레이아웃 옵션: 방향(TB, BT, LR, RL), 노드 간격, 랭크 간격

사용 예

시작하는 가장 쉬운 방법은 커서에서 이 MCP를 활성화하고 커서가 이를 알아서 사용하도록 하는 것입니다. MCP가 시작되면 초기 JSON 트리가 생성됩니다. LLM에 모든 중요 파일의 요약을 작성하도록 설정하고 MCP의 set_file_summary를 사용하여 이를 추가합니다.

프로젝트 분석

1. 프로젝트에 대한 파일 트리를 만듭니다.
   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
2. 가장 중요한 파일을 찾으세요:
   find_important_files(limit: 5, minImportance: 5)
3. 특정 파일에 대한 자세한 정보를 얻으세요:
   get_file_importance(filepath: "/path/to/project/src/main.ts")

요약 작업

1. 파일의 내용을 읽어 이해하려면:
   read_file_content(filepath: "/path/to/project/src/main.ts")
2. 파일에 요약을 추가합니다.
   set_file_summary(filepath: "/path/to/project/src/main.ts", summary: "Main entry point that initializes the application, sets up routing, and starts the server.")
3. 나중에 요약을 검색하세요.
   get_file_summary(filepath: "/path/to/project/src/main.ts")

다이어그램 생성

1. 기본 프로젝트 구조 다이어그램을 만듭니다.
   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")
2. 종속성 관계가 있는 HTML 다이어그램을 생성합니다.
   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")
3. 다이어그램 레이아웃을 사용자 정의합니다.
   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

파일 감시 사용

1. 프로젝트에 대한 파일 감시를 활성화하세요.
   toggle_file_watching()
2. 현재 파일 감시 상태를 확인하세요.
   get_file_watching_status()
3. 파일 감시 구성 업데이트:
   update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })

향후 개선 사항

• 더 많은 프로그래밍 언어에 대한 지원 추가
• 더욱 정교한 중요도 계산 알고리즘 추가
• 다이어그램 사용자 정의 옵션 향상
• 다이어그램을 추가 형식으로 내보내기 위한 지원

특허

이 프로젝트는 GNU General Public License v3(GPL-3.0)에 따라 라이선스가 부여됩니다. 전체 라이선스 내용은 LICENSE 파일을 참조하세요.