`code-scanner-server`

정의(클래스, 함수 등)를 위해 코드 파일을 스캔하고, .gitignore를 준수하고, 줄 번호를 제공하고, LLM 친화적 형식(XML/Markdown)을 출력하는 CLI 도구 및 MCP 서버입니다.

이 프로젝트는 TypeScript와 Node.js로 구축된 다재다능한 코드 스캐닝 도구를 제공합니다. Tree-sitter 파싱 라이브러리를 활용하여 소스 코드를 분석하고 구조 정보를 추출합니다. 명령줄 인터페이스(CLI) 도구와 MCP(Model Context Protocol) 서버로 모두 작동할 수 있습니다.

참고: 이 도구는 현재 개발 중입니다. 핵심 기능은 작동 중이지만, 일부 기능이나 특정 언어 파서는 완전히 테스트되지 않았으며 버그나 제한 사항이 있을 수 있습니다.

특징

코드 정의 추출: 함수, 클래스, 변수, 인터페이스, 메서드 등을 식별합니다.
다국어 지원: Tree-sitter를 통해 JavaScript( .js , .jsx ), TypeScript( .ts , .tsx ), C#(. .cs ), PHP( .php ), CSS( .css ), Python( .py )을 구문 분석합니다.
.gitignore 인식: .gitignore 파일에 정의된 규칙을 자동으로 준수합니다.
유연한 필터링: 정의 유형, 수정자( public , private ), 이름 패턴(정규식) 및 파일 경로 패턴으로 결과를 필터링합니다.
다양한 출력 형식: 마크다운(기본값), XML 또는 JSON으로 결과를 생성합니다.
구성 가능한 세부 수준: 출력 세부 정보: minimal , standard (기본값), detailed .
듀얼 모드 작동: 독립형 CLI 도구 또는 통합 MCP 서버로 실행합니다.

사용 모드

1. 명령줄 인터페이스(CLI)

터미널에서 스캐너를 직접 실행하세요. 이 모드에서는 대상 코드베이스를 지정하는 --directory 인수가 필요합니다.

기본 사용법:

지엑스피1

일반적인 옵션:

-d, --directory <path> : (필수) 스캔할 디렉토리의 절대 경로 또는 상대 경로입니다.
-p, --patterns <patterns...> : 파일 확장자에 대한 Glob 패턴(예: "**/*.ts"``"**/*.js" )입니다. JS, TSX, CS, PHP, CSS, PY 파일이 기본값입니다.
-f, --format <format> : 출력 형식( xml , markdown , json ). 기본값: markdown .
-l, --detail <level> : 세부 수준( minimal , standard , detailed ). 기본값: standard .
--include-types <types...> : 특정 정의 유형(예: class , method )만 포함합니다.
--exclude-types <types...> : 특정 정의 유형을 제외합니다.
--include-modifiers <modifiers...> : 특정 수정자(예: public )가 있는 정의만 포함합니다.
--exclude-modifiers <modifiers...> : 특정 수정자가 있는 정의를 제외합니다.
--name-pattern <regex> : JavaScript 정규식 패턴과 일치하는 정의를 포함합니다.
--exclude-name-pattern <regex> : JavaScript 정규식 패턴과 일치하는 정의를 제외합니다.
--include-paths <paths...> : 포함할 추가 파일 경로 패턴(glob).
--exclude-paths <paths...> : 제외할 파일 경로 패턴(glob).
-h, --help : 모든 옵션에 대한 자세한 도움말 정보를 표시합니다.

예시( src 에 있는 TypeScript 파일을 스캔하여 자세한 JSON을 출력):

node build/index.js -d ./src -p "**/*.ts" -f json -l detailed

2. MCP 서버 모드( `scan_code` 도구)

--directory 인수 없이 실행하면 도구는 MCP 서버로 시작되어 표준 입출력(SIO)을 통해 요청을 수신합니다. 이를 통해 AI 어시스턴트와 같은 MCP 클라이언트와 통합할 수 있습니다.

도구 이름: scan_code
설명: 지정된 디렉토리에서 코드 파일을 스캔하고 제공된 필터에 따라 정의 목록을 반환합니다.
입력 스키마: CLI 옵션에 해당하는 인수를 받습니다. directory 속성은 필수입니다.
{ "type": "object", "properties": { "directory": { "type": "string", "description": "Absolute path to the directory to scan." }, "filePatterns": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns for files.", "default": ["**/*.js", ..., "**/*.py"] }, "outputFormat": { "type": "string", "enum": ["xml", "markdown", "json"], "default": "markdown" }, "detailLevel": { "type": "string", "enum": ["minimal", "standard", "detailed"], "default": "standard" }, "includeTypes": { "type": "array", "items": { "type": "string" } }, "excludeTypes": { "type": "array", "items": { "type": "string" } }, "includeModifiers": { "type": "array", "items": { "type": "string" } }, "excludeModifiers": { "type": "array", "items": { "type": "string" } }, "namePattern": { "type": "string", "description": "Regex pattern for names." }, "excludeNamePattern": { "type": "string", "description": "Regex pattern to exclude names." }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": ["directory"] }
AI Assistant를 사용한 사용 예: "디렉토리 /path/to/project에 code-scanner-server scan_code를 사용하여 xml 형식으로 출력합니다."

설치

필수 조건: Node.js와 npm이 설치되어 있는지 확인하세요.
복제(선택 사항): 코드가 없으면 저장소를 복제합니다.
# git clone <repository_url> # cd code-scanner-server
종속성 설치:
npm install
빌드: TypeScript 코드를 컴파일합니다.
npm run build
이렇게 하면 build/index.js 에 실행 가능한 JavaScript 파일이 생성됩니다.

구성(MCP 서버)

MCP 서버 모드를 사용하려면 MCP 클라이언트의 구성 파일(예: 데스크톱 앱의 경우 claude_desktop_config.json , VS Code 확장 프로그램의 경우 cline_mcp_settings.json )에 추가하세요.

중요: 아래 예시에서 /path/to/code-scanner-server 사용자 시스템의 이 프로젝트 디렉토리에 대한 절대 경로 로 바꾸세요.

예시( claude_desktop_config.json / cline_mcp_settings.json ):

{
  "mcpServers": {
    "code-scanner-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/code-scanner-server/build/index.js" // <-- Replace this path! (e.g., "C:\\Users\\YourUser\\Projects\\code-scanner-server\\build\\index.js" on Windows)
      ],
      "env": {},
      "disabled": false,
      "autoApprove": [] // Add tool names here for auto-approval if desired
    }
  }
}

구성을 수정한 후에는 변경 사항을 적용하기 위해 MCP 클라이언트 애플리케이션(IDE, 데스크톱 앱)을 다시 시작해야 합니다.

개발

감시 모드: 소스 파일이 변경되면 프로젝트를 자동으로 다시 빌드합니다.
npm run watch
디버깅(MCP 모드): stdio를 통해 MCP 서버를 디버깅하는 것은 복잡할 수 있습니다. MCP Inspector 도구를 사용하면 디버깅을 더 쉽게 수행할 수 있습니다.
npm run inspector
이렇게 하면 Node.js 검사기가 첨부된 서버가 시작되고 디버깅 도구(예: Chrome DevTools)에 연결할 수 있는 URL이 제공됩니다.

감사의 말

이 프로젝트는 주로 Visual Studio Code용 Roo Code 확장을 통해 접근하는 Google의 Gemini 2.5 Pro 모델을 사용하여 AI의 도움을 받아 상당히 개발되었습니다.

특허

이 프로젝트는 GNU General Public License v3.0에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.

code-scanner-server

특징