MCP ts-morph Refactoring Tools

개요

이 MCP 서버는 ts-morph 를 사용하여 TypeScript 및 JavaScript 코드베이스에 대한 리팩토링 작업을 제공합니다.

Related MCP server: TypeScript Rename Helper

제공되는 기능

이 MCP 서버는 다음 리팩토링 기능을 제공합니다. 각 기능은 ts-morph 사용하여 AST를 구문 분석하고 전체 프로젝트의 무결성을 유지하면서 변경합니다.

기호 이름 변경 ( rename_symbol_by_tsmorph )

• 기능 : 지정된 파일의 특정 위치에 있는 심볼(함수, 변수, 클래스, 인터페이스 등)의 이름을 프로젝트 전체에서 일괄 변경합니다.

• 유스 케이스 : 함수명이나 변수명을 변경하고 싶지만, 참조 부분이 많고 수작업으로의 변경이 곤란한 경우.

• 필요한 정보 : 프로젝트의 tsconfig.json 경로, 대상 파일의 경로, 기호 위치 (행 / 열), 현재 기호 이름, 새 기호 이름

파일 / 폴더 이름 변경 ( rename_filesystem_entry_by_tsmorph )

• 기능 : 지정된 여러 파일 및/또는 폴더의 이름을 바꾸고 프로젝트의 모든 import / export 문 경로를 자동으로 업데이트합니다.

• 사용 사례 : 파일 구성을 변경하고 이에 따라 가져오기 경로를 수정하려는 경우 여러 파일/폴더를 한 번에 이름 바꾸기/이동합니다.

• 필수 정보 : 프로젝트의 tsconfig.json 경로, 이름 바꾸기 작업 배열( renames: { oldPath: string, newPath: string }[] ).

• 비고 :

  • 참조의 해결에는 주로 심볼 해석이 이용됩니다.

  • 경로 별칭( @/ 등)을 포함하는 참조는 업데이트되지만 상대 경로로 변환 됩니다.

  • 디렉터리의 인덱스 파일을 참조하는 가져오기(예: ../components )는 명시적 파일 경로(예: ../components/index.tsx )로 업데이트 됩니다.

  • 이름 바꾸기 작업 전에 경로 충돌 검사(기존 경로 또는 작업 내에서 중복)도 수행합니다.

• 참고(실행 시간): 많은 파일과 폴더를 한 번에 조작하거나 매우 큰 프로젝트에서는 참조 구문 분석 및 업데이트에 시간이 걸릴 수 있습니다.

• 참고(알려진 제한): 현재 export default Identifier; 참조가 올바르게 업데이트되지 않을 수 있습니다.

참조 위치 찾기 ( find_references_by_tsmorph )

• 기능 : 지정된 파일 내의 특정 위치에 있는 심볼의 정의 부분과 프로젝트 전체의 모든 참조 부분을 검색하여 나열합니다.

• 사용 사례 : 특정 함수나 변수가 어디에서 사용되는지 파악하고 싶은 경우.

• 필수 정보 : 프로젝트의 tsconfig.json 경로, 대상 파일의 경로 및 기호의 위치 (행 / 열).

경로 별칭 삭제 ( remove_path_alias_by_tsmorph )

• 기능 : 지정된 파일 또는 디렉토리내의 import / export 문에 포함되는 패스 앨리어스 ( @/components 등)를, 상대 패스 ( ../../components 등)로 치환합니다.

• 사용 사례 : 프로젝트의 이식성을 높이고 싶거나 특정 코딩 규칙에 맞추고 싶을 때.

• 필수 정보 : 프로젝트의 tsconfig.json 경로, 처리할 파일 또는 디렉토리의 경로.

심볼의 파일 간 이동 ( move_symbol_to_file_by_tsmorph )

• 기능 : 지정된 심볼(함수, 변수, 클래스, 인터페이스, 유형 별칭, Enum)을 현재 파일에서 지정된 다른 파일로 이동합니다.

• 유스 케이스 : 코드의 구성을 변경하기 위해서, 특정의 기능을 다른 파일에 잘라내고 싶은 경우.

• 필요한 정보 : 프로젝트의 tsconfig.json 경로, 원본 파일 경로 declarationKindString 대상 파일 경로 및 이동할 기호의 이름.

• 비고 : 심볼의 내부 종속성 (그 심볼 내에서만 사용되는 다른 선언) export 함께 이동합니다.

• 참고 : export default (export default)된 기호는 이 도구에서 이동할 수 없습니다.

환경 구축

사용자 전용 (npm 패키지로 사용하는 경우)

mcp.json 에 다음과 같이 설정을 추가합니다. npx 명령을 사용하면 설치된 최신 버전이 자동으로 사용됩니다.

{
 "mcpServers": {
 "mcp-tsmorph-refactor": { // 任意のサーバー名
 "command": "npx",
 "args": ["-y", "@sirosuzume/mcp-tsmorph-refactor"],
 "env": {} // 必要に応じてロギング設定などを追加
 }
 }
}

개발자용(로컬로 개발·실행하는 경우)

로컬에서 소스 코드에서 서버를 시작하는 경우 먼저 빌드가 필요합니다.

# 依存関係のインストール (初回のみ)
pnpm install

# TypeScript コードのビルド
pnpm run build

빌드 후 mcp.json 에서 다음과 같이 설정하여 node 에서 직접 실행할 수 있습니다.

{
 "mcpServers": {
 "mcp-tsmorph-refactor-dev": { // 開発用など、別の名前を推奨
 "command": "node",
 // プロジェクトルートからの相対パスまたは絶対パス
 "args": ["/path/to/your/local/repo/dist/index.js"],
 "env": {
 // 開発時のデバッグログ設定など
 "LOG_LEVEL": "debug"
 }
 }
 }
}

로깅 설정 (환경 변수)

서버의 동작 로그는 다음 환경 변수 env 사용하여 출력 레벨과 출력 대상을 제어할 mcp.json 있습니다.

• LOG_LEVEL : 로그의 상세도를 설정합니다.

  • 사용 가능한 레벨: fatal , error , warn , info (기본값), debug , trace , silent

  • 예: "LOG_LEVEL": "debug"

• LOG_OUTPUT : 로그의 출력 대상을 지정합니다.

  • console ( pino-pretty : NODE_ENV !== 'production' 에 로그를 출력합니다.

  • file : 지정된 파일에 로그를 출력합니다. MCP 클라이언트에 미치는 영향을 피할 때 설정합니다.

  • 예: "LOG_OUTPUT": "file"

• LOG_FILE_PATH : LOG_OUTPUT``file 인 경우 로그 파일의 절대 경로를 지정합니다.

  • 기본값: [プロジェクトルート]/app.log

  • 예: "LOG_FILE_PATH": "/var/log/mcp-tsmorph.log"

설정 예 ( mcp.json 내) :

// ... (mcp.json の他の設定)
 "env": {
 "LOG_LEVEL": "debug", // デバッグレベルのログを
 "LOG_OUTPUT": "file", // ファイルに出力
 "LOG_FILE_PATH": "/Users/yourname/logs/mcp-tsmorph.log" // ログファイルのパス指定
 }
// ...

개발자 정보

전제 조건

• Node.js (버전은 .node-version 또는 package.json 의 volta 필드 참조)

• pnpm (버전은 package.json 의 packageManager 필드 참조)

설정

리포지토리를 복제하고 종속성을 설치합니다.

git clone https://github.com/sirosuzume/mcp-tsmorph-refactor.git
cd mcp-tsmorph-refactor
pnpm install

빌드

TypeScript 코드를 JavaScript로 컴파일합니다.

pnpm build

빌드 아티팩트는 dist 디렉토리에 출력됩니다.

테스트

단위 테스트를 실행합니다.

pnpm test

린팅 및 포맷

코드의 정적 해석과 포맷을 실시합니다.

# Lintチェック
pnpm lint

# Lint修正
pnpm lint:fix

# フォーマット
pnpm format

디버깅 래퍼 사용

개발 중에 MCP 서버의 시작 순서, 표준 I/O 및 오류 출력을 자세히 확인하려면 프로젝트의 scripts 디렉토리에 있는 mcp_launcher.js 를 사용할 수 있습니다.

이 래퍼 스크립트는 원래 MCP 서버 프로세스( npx -y @sirosuzume/mcp-tsmorph-refactor )를 하위 프로세스로 시작하고 해당 시작 정보와 출력을 프로젝트 루트의 .logs/mcp_launcher.log 파일에 기록합니다.

사용법:

1. mcp.json 파일에서 mcp-tsmorph-refactor 서버의 설정을 다음과 같이 변경합니다.

   • command 를 "node" 로 설정합니다.

   • args 는 scripts/mcp_launcher.js``["path/to/your_project_root/scripts/mcp_launcher.js"]``["scripts/mcp_launcher.js"] )를 지정합니다.

   설정 예 ( mcp.json ) :

   {
    "mcpServers": {
    "mcp-tsmorph-refactor": {
    "command": "node",
    // scripts/mcp_launcher.js へのパス (プロジェクトルートからの相対パス or 絶対パス)
    "args": ["path/to/your_project_root/scripts/mcp_launcher.js"],
    "env": {
    // 元の環境変数設定はそのまま活かせます
    // 例:
    // "LOG_LEVEL": "trace",
    // "LOG_OUTPUT": "file",
    // "LOG_FILE_PATH": ".logs/mcp-ts-morph.log"
    }
    }
    // ... 他のサーバー設定 ...
    }
   }

2. MCP 클라이언트(예: Cursor)를 다시 시작하거나 다시 로드합니다.

3. 프로젝트 루트의 .logs/mcp_launcher.log 에 로그 .logs/mcp-ts-morph.log 출력되는지 확인하십시오.

이 래퍼를 사용하면 MCP 서버가 예상대로 부팅되지 않는 경우의 원인을 파악할 수 있습니다.

npm에 게시

이 패키지는 GitHub Actions 워크플로( .github/workflows/release.yml )를 통해 npm에 자동으로 게시됩니다.

전제 조건

• NPM 토큰: 공개 권한이 있는 npm 액세스 토큰이 리포지토리의 Actions secrets( Settings > Secrets and variables > Actions )에 NPM_TOKEN 이라는 이름으로 설정되어 있는지 확인합니다.

• 버전 업데이트 : 게시하기 전에 package.json 의 version 필드를 시맨틱 버전 관리 (SemVer)에 따라 업데이트하십시오.

게시 방법

릴리스 워크플로를 트리거하려면 Git 태그 푸시를 사용합니다.

방법: Git 태그 푸시(출시 시 권장)

• 예상되는 용도 : 일반 버전 릴리스 (주요, 사소한, 패치).

1. 버전 업데이트: package.json 의 version 을 변경합니다(예: 0.3.0 ).

2. 커밋 & 푸시: package.json 변경 사항을 커밋하고 메인 브랜치로 푸시합니다.

3. 태그 만들기 및 푸시: 버전과 일치하는 Git 태그( v 접두사 포함)를 만들고 푸시합니다.

   git tag v0.3.0
   git push origin v0.3.0

4. 자동화: 태그를 푸시하면 Release Package 가 트리거되어 패키지를 빌드, 테스트 및 npm에 게시합니다.

5. 확인: Actions 탭에서 워크플로의 상태를 확인하고 npmjs.com에서 패키지를 확인합니다.

주의사항

• 버전 일관성: 태그 푸시로 트리거하는 경우 태그 이름(예: v0.3.0 )은 package.json 의 version (예: 0.3.0 )과 정확히 일치해야 합니다 . 일치하지 않으면 워크플로가 실패합니다.

• 사전 점검: CI 워크플로에는 빌드 및 테스트 단계가 포함되어 있지만 잠재적인 문제를 조기에 발견하기 위해 버전을 업데이트하기 전에 로컬에서 pnpm run build 및 pnpm run test 를 실행하는 것이 좋습니다.

라이센스

이 프로젝트는 MIT 라이센스하에 게시됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• change_signature_by_tsmorphA
• find_references_by_tsmorphA
• find_unused_exports_by_tsmorphA
• get_type_at_position_by_tsmorphA
• move_symbol_to_file_by_tsmorphA
• remove_path_alias_by_tsmorphA
• rename_filesystem_entry_by_tsmorphA
• rename_symbol_by_tsmorphA