MCP ts-morph Refactoring Tools

Herramientas de refactorización de MCP ts-morph

descripción general

Este servidor MCP aprovecha ts-morph para proporcionar operaciones de refactorización para bases de código TypeScript y JavaScript. Funciona con extensiones de editor como Cursor para permitir el cambio de nombre de símbolos basado en AST, el cambio de nombre de archivos/carpetas y la búsqueda de referencias.

Características proporcionadas

Este servidor MCP proporciona las siguientes funciones de refactorización: Cada función utiliza ts-morph para analizar el AST y realizar cambios manteniendo la coherencia en todo el proyecto.

Cambiar el nombre de los símbolos ( rename_symbol_by_tsmorph )

• Qué hace : cambia el nombre globalmente de un símbolo (función, variable, clase, interfaz, etc.) en una posición específica en un archivo especificado en todo el proyecto.
• Caso de uso : desea cambiar el nombre de una función o variable, pero hay muchas referencias a ella y sería difícil cambiarla manualmente.
• Información requerida : ruta del proyecto tsconfig.json , ruta del archivo de destino, posición del símbolo (línea y columna), nombre del símbolo actual, nombre del nuevo símbolo

Cambiar el nombre de un archivo o carpeta ( rename_filesystem_entry_by_tsmorph )

• Característica : cambia el nombre de varios archivos y/o carpetas especificados y actualiza automáticamente las rutas en todas las declaraciones de import / export del proyecto.
• Caso de uso : cambia la estructura de sus archivos y desea modificar las rutas de importación en consecuencia. Si desea cambiar el nombre o mover varios archivos o carpetas a la vez.
• Información requerida : ruta tsconfig.json del proyecto, matriz de operaciones de cambio de nombre ( renames: { oldPath: string, newPath: string }[] ).
• Observaciones :
  • Las referencias se resuelven principalmente mediante la resolución de símbolos.
  • Las referencias que contienen alias de ruta (como @/ ) se actualizarán pero se convertirán en rutas relativas .
  • Las importaciones que hacen referencia a un archivo de índice de directorio (por ejemplo, ../components ) se actualizan a una ruta de archivo explícita (por ejemplo ../components/index.tsx ) .
  • También realiza una verificación de colisión de rutas (duplicados en rutas existentes y dentro de la operación) antes de la operación de cambio de nombre.
• Nota (tiempo de ejecución): cuando se trabaja con muchos archivos y carpetas a la vez, o para proyectos muy grandes, el análisis y la actualización de referencias pueden llevar algún tiempo.
• NOTA (limitación conocida): Actualmente, las referencias a las exportaciones predeterminadas del formato export default Identifier; Es posible que no se actualice correctamente.

Encontrar referencias ( find_references_by_tsmorph )

• Qué hace : busca y enumera la definición de un símbolo en una ubicación particular en un archivo especificado, así como todas sus referencias en todo el proyecto.
• Caso de uso : desea saber dónde se utiliza una función o variable. Desea explorar el alcance de una refactorización.
• Información requerida : ruta tsconfig.json del proyecto, ruta del archivo de destino, posición del símbolo (línea, columna).

Eliminar un alias de ruta ( remove_path_alias_by_tsmorph )

• Función : Reemplaza los alias de ruta (como @/components ) en las declaraciones de import / export en el archivo o directorio especificado con rutas relativas (como ../../components ).
• Caso de uso : desea que su proyecto sea más portable o que se ajuste a estándares de codificación específicos.
• Información requerida : ruta tsconfig.json del proyecto, ruta del archivo o directorio a procesar.

Mover símbolos entre archivos ( move_symbol_to_file_by_tsmorph )

• Función : Mueve el símbolo especificado (función, variable, clase, interfaz, alias de tipo, enumeración) del archivo actual a otro archivo especificado. Actualice automáticamente las referencias en todo el proyecto (incluidas las rutas de importación y exportación) a medida que avanza.
• Caso de uso : desea extraer cierta funcionalidad en un archivo separado para reorganizar su código.
• Información requerida : ruta del archivo tsconfig.json del proyecto, ruta del archivo de origen, ruta del archivo de destino, nombre del símbolo a mover. Opcionalmente, puede especificar el tipo de símbolo ( declarationKindString ) para eliminar la ambigüedad de los símbolos con el mismo nombre.
• Nota : Las dependencias internas del símbolo (otras declaraciones utilizadas únicamente dentro de ese símbolo) se mueven junto con él. Las dependencias a las que también hacen referencia otros símbolos que permanecen en el archivo de origen permanecerán en el origen y se agregarán export según sea necesario y se importarán en el archivo de destino.
• Nota : los símbolos que se exportan export default no se pueden mover con esta herramienta.

construcción ambiental

Para los usuarios (cuando se utiliza como un paquete npm)

Agregue las siguientes configuraciones a mcp.json . Al usar el comando npx se utilizará automáticamente la última versión que haya instalado.

Para desarrolladores (para desarrollo y ejecución local)

Si desea ejecutar el servidor localmente desde el código fuente, primero debe compilarlo.

Después de la compilación, puede ejecutarlo directamente en node configurando lo siguiente en mcp.json :

Configuración de registro (variables de entorno)

El nivel de salida y el destino del registro de operaciones del servidor se pueden controlar mediante las siguientes variables de entorno. Configúrelo en env de mcp.json .

• LOG_LEVEL : Establece el nivel de detalle del registro.
  • Niveles disponibles: fatal , error , warn , info (predeterminado), debug , trace , silent
  • Ejemplo: "LOG_LEVEL": "debug"
• LOG_OUTPUT : especifica el destino de salida del registro.
  • console (predeterminado): registra en la salida estándar. Si está en un entorno de desarrollo ( NODE_ENV !== 'production' ) y tiene instalado pino-pretty , la salida tendrá un formato bonito.
  • file : envía el registro al archivo especificado. Configure esto para evitar afectar a los clientes de MCP.
  • Ejemplo: "LOG_OUTPUT": "file"
• LOG_FILE_PATH : si LOG_OUTPUT se establece en file , esto especifica la ruta absoluta del archivo de registro.
  • Predeterminado: [プロジェクトルート]/app.log
  • Ejemplo: "LOG_FILE_PATH": "/var/log/mcp-tsmorph.log"

Ejemplo de configuración (en mcp.json ):

Información para desarrolladores

Prerrequisitos

• Node.js (para la versión, consulte .node-version o volta en package.json )
• pnpm (consulte el campo packageManager en package.json para conocer la versión)

configuración

Clonar el repositorio e instalar las dependencias:

Construir

Compila código TypeScript en JavaScript.

Los artefactos de compilación se envían al directorio dist .

prueba

Ejecute las pruebas unitarias.

Pelusa y formato

Analiza y formatea estáticamente su código.

Uso del contenedor de depuración

Si desea verificar la secuencia de inicio, la entrada/salida estándar y la salida de errores del servidor MCP en detalle durante el desarrollo, puede usar mcp_launcher.js , que se encuentra en el directorio scripts del proyecto.

Este script contenedor inicia el proceso del servidor MCP original ( npx -y @sirosuzume/mcp-tsmorph-refactor ) como un proceso secundario y registra la información de inicio y la salida en .logs/mcp_launcher.log en la raíz del proyecto.

Modo de empleo:

1. En el archivo mcp.json , cambie mcp-tsmorph-refactor de la siguiente manera:
   • Establezca command en "node" .
   • En args , especifique la ruta a scripts/mcp_launcher.js (por ejemplo, ["path/to/your_project_root/scripts/mcp_launcher.js"] ). También puedes utilizar una ruta relativa a la raíz del proyecto ( ["scripts/mcp_launcher.js"] ).

   Ejemplo de configuración ( 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. Reinicie o recargue el cliente MCP (por ejemplo, Cursor).
3. Confirme que el registro se envíe a .logs/mcp_launcher.log en la raíz del proyecto. También puede comprobar el registro del propio servidor MCP, si está configurado (por ejemplo .logs/mcp-ts-morph.log ).

El uso de este contenedor puede ayudarle a diagnosticar por qué su servidor MCP no se inicia como se espera.

Publicación en npm

Este paquete se publicará automáticamente en npm a través de un flujo de trabajo de GitHub Actions ( .github/workflows/release.yml ).

Prerrequisitos

• Token NPM: asegúrese de tener un token de acceso npm con permisos públicos establecidos en los secretos de Acciones de su repositorio ( Settings > Secrets and variables > Actions ) con el nombre NPM_TOKEN .
• Actualice su versión: antes de publicar, actualice el campo version en package.json de acuerdo con el control de versiones semántico (SemVer).

Cómo publicar

Para activar el flujo de trabajo de lanzamiento, utilice una etiqueta Git push.

Cómo: enviar una etiqueta Git (recomendado para lanzamientos)

• Uso previsto: Lanzamientos de versiones regulares (principales, secundarias, parches). Git es el proceso de lanzamiento estándar recomendado porque proporciona una correspondencia clara entre el historial y las versiones.

1. Actualizar versión: cambie version en package.json (por ejemplo, 0.3.0 ).
2. Confirmar y enviar: confirma los cambios en package.json y envíalos a la rama principal.
3. Crear etiqueta y enviar: crea una etiqueta Git (con v ) que coincide con la versión y la envía.
   git tag v0.3.0 git push origin v0.3.0
4. Automatización: al insertar una etiqueta se activa el flujo de trabajo Release Package , que crea, prueba y publica el paquete en npm.
5. Verificar: Verifique el estado de su flujo de trabajo en la pestaña Acciones y verifique su paquete en npmjs.com.

Precauciones

• Consistencia de la versión: cuando se activa un envío de etiqueta, el nombre de la etiqueta (p. ej. v0.3.0 ) debe coincidir exactamente con version en package.json (p. ej. 0.3.0 ). Si no hay coincidencia, el flujo de trabajo fallará.
• Comprobación previa: aunque su flujo de trabajo de CI incluye pasos de compilación y prueba, recomendamos ejecutar pnpm run build y pnpm run test localmente antes de actualizar su versión para detectar posibles problemas de manera temprana.

licencia

Este proyecto se publica bajo la licencia MIT. Consulte el archivo de LICENCIA para obtener más detalles.