FileScopeMCP(모델 컨텍스트 프로토콜) 서버
✨ 코드베이스 구조와 종속성을 즉시 이해하고 시각화하세요! ✨
코드베이스의 파일을 중요도에 따라 순위를 매기고, 종속성을 추적하고, 코드 구조를 이해하는 데 도움이 되는 요약을 제공하는 TypeScript 기반 도구입니다.
개요
이 MCP 서버는 코드베이스를 분석하여 종속성 관계를 기반으로 가장 중요한 파일을 식별합니다. 각 파일에 대한 중요도 점수(0~10점)를 생성하고, 양방향 종속성을 추적하며, 파일에 대한 사용자 지정 요약을 추가할 수 있도록 합니다. 이 모든 정보는 Cursor의 모델 컨텍스트 프로토콜을 통해 AI 도구에 제공됩니다.
Related MCP server: SourceSage MCP
특징
🚀 코드 이해도를 대폭 향상하세요! FileScopeMCP는 AI 어시스턴트에게 직접 인사이트를 제공합니다.
🎯 파일 중요도 분석
코드베이스에서의 역할에 따라 0~10점 척도로 파일의 순위를 매깁니다.
수신/발신 종속성을 사용하여 중요도를 계산합니다.
프로젝트에서 가장 중요한 파일을 즉시 찾아냅니다.
스마트 계산은 파일 유형, 위치, 이름의 중요성을 고려합니다.
🔗 종속성 추적
파일 간의 양방향 종속 관계를 매핑합니다.
주어진 파일을 가져오는 파일(종속 파일)을 식별합니다.
주어진 파일이 어떤 파일을 가져왔는지 확인합니다(종속성).
로컬 종속성과 패키지 종속성을 구분합니다.
다국어 지원: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.
📊 시각화
인어 다이어그램을 생성하여 파일 관계를 시각화합니다.
중요도 점수에 따라 색상으로 구분된 시각화입니다.
종속성 그래프, 디렉토리 트리 또는 하이브리드 뷰를 지원합니다.
테마 토글 및 반응형 디자인을 포함한 내장 렌더링이 포함된 HTML 출력입니다.
다이어그램 깊이를 사용자 지정하고, 중요도에 따라 필터링하고, 레이아웃 옵션을 조정합니다.
📝 파일 요약
모든 파일에 사람이나 AI가 생성한 요약을 추가합니다.
저장된 요약을 검색하여 파일의 목적을 빠르게 파악합니다.
요약은 서버를 다시 시작해도 그대로 유지됩니다.
📚 다양한 프로젝트 지원
다양한 프로젝트 영역에 대해 여러 개의 파일 트리를 만들고 관리합니다.
서로 다른 기본 디렉토리로 별도의 트리를 구성합니다.
다양한 파일 트리 사이를 손쉽게 전환하세요.
후속 작업을 더 빠르게 하기 위해 캐시된 트리입니다.
💾 영구 저장소
모든 데이터는 JSON 형식으로 디스크에 자동으로 저장됩니다.
파일 시스템을 다시 검사하지 않고 기존 파일 트리를 로드합니다.
파일 트리가 마지막으로 업데이트된 시점을 추적합니다.
설치
이 저장소를 복제하세요
프로젝트를 빌드하세요:
빌드 스크립트는 모든 노드 종속성을 설치하고 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": [] } } }인수 경로 --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단계 접근 방식을 사용합니다.
수집 단계: 모든 노드와 관계 등록
노드 정의 단계: 참조하기 전에 모든 노드에 대한 정의를 생성합니다.
에지 생성 단계: 정의된 노드 사이에 에지를 생성합니다.
이렇게 하면 모든 다이어그램의 구문이 유효하고 올바르게 렌더링됩니다. 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를 사용하여 이를 추가합니다.
프로젝트 분석
프로젝트에 대한 파일 트리를 만듭니다.
create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")가장 중요한 파일을 찾으세요:
find_important_files(limit: 5, minImportance: 5)특정 파일에 대한 자세한 정보를 얻으세요:
get_file_importance(filepath: "/path/to/project/src/main.ts")
요약 작업
파일의 내용을 읽어 이해하려면:
read_file_content(filepath: "/path/to/project/src/main.ts")파일에 요약을 추가합니다.
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.")나중에 요약을 검색하세요.
get_file_summary(filepath: "/path/to/project/src/main.ts")
다이어그램 생성
기본 프로젝트 구조 다이어그램을 만듭니다.
generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")종속성 관계가 있는 HTML 다이어그램을 생성합니다.
generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")다이어그램 레이아웃을 사용자 정의합니다.
generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")
파일 감시 사용
프로젝트에 대한 파일 감시를 활성화하세요.
toggle_file_watching()현재 파일 감시 상태를 확인하세요.
get_file_watching_status()파일 감시 구성 업데이트:
update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })
향후 개선 사항
더 많은 프로그래밍 언어에 대한 지원 추가
더욱 정교한 중요도 계산 알고리즘 추가
다이어그램 사용자 정의 옵션 향상
다이어그램을 추가 형식으로 내보내기 위한 지원
특허
이 프로젝트는 GNU General Public License v3(GPL-3.0)에 따라 라이선스가 부여됩니다. 전체 라이선스 내용은 LICENSE 파일을 참조하세요.
