MCP ts-morph Refactoring Tools

Instructions

Implementation Reference

• src/ts-morph/remove-path-alias/remove-path-alias.ts:82-121 (handler)

  Core implementation of the path alias removal logic using ts-morph. Processes target files or directories, identifies import/export declarations with path aliases, resolves them, and replaces with relative paths.
  export async function removePathAlias({ project, targetPath, dryRun = false, baseUrl, paths, }: { project: Project; // Project インスタンスは呼び出し元で作成・管理 targetPath: string; dryRun?: boolean; baseUrl: string; paths: Record<string, string[]>; }): Promise<{ changedFiles: string[] }> { let filesToProcess: SourceFile[] = []; const directory = project.getDirectory(targetPath); if (directory) { filesToProcess = directory.getSourceFiles("**/*.{ts,tsx,js,jsx}"); } else { const sourceFile = project.getSourceFile(targetPath); if (!sourceFile) { throw new Error( `指定されたパスはプロジェクト内でディレクトリまたはソースファイルとして見つかりません: ${targetPath}`, ); } filesToProcess.push(sourceFile); } const changedFilePaths: string[] = []; for (const sourceFile of filesToProcess) { const modified = processSourceFile(sourceFile, baseUrl, paths, dryRun); if (!modified) { continue; } changedFilePaths.push(sourceFile.getFilePath()); } return { changedFiles: changedFilePaths }; }
• src/mcp/tools/register-remove-path-alias-tool.ts:9-106 (registration)

  Registers the 'remove_path_alias_by_tsmorph' MCP tool with schema and handler that wraps the core removePathAlias function.
  server.tool( "remove_path_alias_by_tsmorph", `[Uses ts-morph] Replaces path aliases (e.g., '@/') with relative paths in import/export statements within the specified target path. Analyzes the project based on \`tsconfig.json\` to resolve aliases and calculate relative paths. ## Usage Use this tool to convert alias paths like \`import Button from '@/components/Button'\` to relative paths like \`import Button from '../../components/Button'\`. This can be useful for improving portability or adhering to specific project conventions. 1. Specify the **absolute path** to the project\`tsconfig.json\`. 2. Specify the **absolute path** to the target file or directory where path aliases should be removed. 3. Optionally, run with \`dryRun: true\` to preview the changes without modifying files. ## Parameters - tsconfigPath (string, required): Absolute path to the project\`tsconfig.json\` file. **Must be an absolute path.** - targetPath (string, required): The absolute path to the file or directory to process. **Must be an absolute path.** - dryRun (boolean, optional): If true, only show intended changes without modifying files. Defaults to false. ## Result - On success: Returns a message containing the list of file paths modified (or scheduled to be modified if dryRun). - On failure: Returns a message indicating the error.`, { tsconfigPath: z .string() .describe("Absolute path to the project's tsconfig.json file."), targetPath: z .string() .describe("Absolute path to the target file or directory."), dryRun: z .boolean() .optional() .default(false) .describe( "If true, only show intended changes without modifying files.", ), }, async (args) => { const startTime = performance.now(); let message = ""; let isError = false; let duration = "0.00"; const project = new Project({ tsConfigFilePath: args.tsconfigPath, }); try { const { tsconfigPath, targetPath, dryRun } = args; const compilerOptions = project.compilerOptions.get(); const tsconfigDir = path.dirname(tsconfigPath); const baseUrl = path.resolve( tsconfigDir, compilerOptions.baseUrl ?? ".", ); const pathsOption = compilerOptions.paths ?? {}; const result = await removePathAlias({ project, targetPath, dryRun, baseUrl, paths: pathsOption, }); if (!dryRun) { await project.save(); } const changedFilesList = result.changedFiles.length > 0 ? result.changedFiles.join("\n - ") : "(No changes)"; const actionVerb = dryRun ? "scheduled for modification" : "modified"; message = `Path alias removal (${ dryRun ? "Dry run" : "Execute" }): Within the specified path '${targetPath}', the following files were ${actionVerb}:\n - ${changedFilesList}`; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); message = `Error during path alias removal process: ${errorMessage}`; isError = true; } finally { const endTime = performance.now(); duration = ((endTime - startTime) / 1000).toFixed(2); } const finalMessage = `${message}\nStatus: ${ isError ? "Failure" : "Success" }\nProcessing time: ${duration} seconds`; return { content: [{ type: "text", text: finalMessage }], isError: isError, }; }, );
• src/mcp/tools/register-remove-path-alias-tool.ts:33-47 (schema)

  Zod schema defining input parameters: tsconfigPath, targetPath, dryRun.
  { tsconfigPath: z .string() .describe("Absolute path to the project's tsconfig.json file."), targetPath: z .string() .describe("Absolute path to the target file or directory."), dryRun: z .boolean() .optional() .default(false) .describe( "If true, only show intended changes without modifying files.", ), },
• src/ts-morph/remove-path-alias/remove-path-alias.ts:29-77 (helper)

  Helper function that processes a single source file: scans import/export declarations, replaces path aliases with relative paths if applicable.
  function processSourceFile( sourceFile: SourceFile, baseUrl: string, paths: Record<string, string[]>, dryRun: boolean, ): boolean { let changed = false; const sourceFilePath = sourceFile.getFilePath(); const alias = Object.keys(paths); const declarations: (ImportDeclaration | ExportDeclaration)[] = [ ...sourceFile.getImportDeclarations(), ...sourceFile.getExportDeclarations(), ]; for (const declaration of declarations) { const moduleSpecifierNode = declaration.getModuleSpecifier(); if (!moduleSpecifierNode) continue; const moduleSpecifier = moduleSpecifierNode.getLiteralText(); if (!isPathAlias(moduleSpecifier, alias)) { continue; } // TypeScript/ts-morph の解決結果を使用 const resolvedSourceFile = declaration.getModuleSpecifierSourceFile(); if (!resolvedSourceFile) { // console.warn(`[remove-path-alias] Could not resolve module specifier: ${moduleSpecifier} in ${sourceFilePath}`); continue; // 解決できないエイリアスはスキップ } const targetAbsolutePath = resolvedSourceFile.getFilePath(); const relativePath = calculateRelativePath( sourceFilePath, targetAbsolutePath, { simplifyIndex: false, removeExtensions: true, }, ); if (!dryRun) { declaration.setModuleSpecifier(relativePath); } changed = true; } return changed; }
• src/ts-morph/remove-path-alias/remove-path-alias.ts:12-24 (helper)

  Helper function to check if a module specifier matches any path alias from tsconfig paths.
  function isPathAlias(moduleSpecifier: string, alias: string[]): boolean { // paths のキー（例: "@/*", "@components/*", "exact-alias"）に基づいて判定 return alias.some((alias) => { if (moduleSpecifier === alias) { return true; // 完全一致 } if (!alias.endsWith("/*")) { return false; // ワイルドカードエイリアスでない場合は false } const prefix = alias.substring(0, alias.length - 1); // 末尾の '*' を除く (例: "@/", "@components/") return moduleSpecifier.startsWith(prefix); }); }