MCP ts-morph Refactoring-Tools

Überblick

Dieser MCP-Server nutzt ts-morph, um Refactoring-Operationen für TypeScript- und JavaScript-Codebasen bereitzustellen. Es funktioniert mit Editorerweiterungen wie Cursor, um eine AST-basierte Symbolumbenennung, Datei-/Ordnerumbenennung und Referenzsuche zu ermöglichen.

Verfügbare Funktionen

Dieser MCP-Server bietet die folgenden Refactoring-Funktionen: Jede Funktion verwendet ts-morph um den AST zu analysieren und Änderungen vorzunehmen, während die Konsistenz im gesamten Projekt gewahrt bleibt.

Symbole umbenennen ( rename_symbol_by_tsmorph )

• Was es bewirkt : Globale Umbenennung eines Symbols (Funktion, Variable, Klasse, Schnittstelle usw.) an einer bestimmten Position in einer angegebenen Datei im gesamten Projekt.

• Anwendungsfall : Sie möchten den Namen einer Funktion oder Variable ändern, es gibt jedoch viele Verweise darauf und es wäre schwierig, ihn manuell zu ändern.

• Erforderliche Informationen : tsconfig.json Pfad des Projekts, Pfad der Zieldatei, Symbolposition (Zeile und Spalte), aktueller Symbolname, neuer Symbolname

Umbenennen einer Datei/eines Ordners ( rename_filesystem_entry_by_tsmorph )

• Funktion : Benennt mehrere angegebene Dateien und/oder Ordner um und aktualisiert automatisch die Pfade in allen import / export im Projekt.

• Anwendungsfall : Sie ändern Ihre Dateistruktur und möchten die Importpfade entsprechend anpassen. Wenn Sie mehrere Dateien/Ordner gleichzeitig umbenennen/verschieben möchten.

• Erforderliche Informationen : tsconfig.json -Pfad des Projekts, Array von Umbenennungsvorgängen ( renames: { oldPath: string, newPath: string }[] ).

• Bemerkungen :

  • Referenzen werden hauptsächlich mithilfe der Symbolauflösung aufgelöst.

  • Referenzen, die Pfadaliase enthalten (wie z. @/ ), werden aktualisiert, aber in relative Pfade umgewandelt.

  • Importe, die auf eine Verzeichnisindexdatei verweisen (z. B. ../components ), werden auf einen expliziten Dateipfad aktualisiert (z. B. .

  • Außerdem wird vor der Umbenennungsoperation eine Pfadkollisionsprüfung (Duplikate in vorhandenen Pfaden und innerhalb der Operation) durchgeführt.

• Hinweis (Ausführungszeit): Wenn Sie mit vielen Dateien und Ordnern gleichzeitig arbeiten oder bei sehr großen Projekten, kann das Parsen und Aktualisieren von Referenzen einige Zeit in Anspruch nehmen.

• HINWEIS (bekannte Einschränkung): Derzeit werden Verweise auf Standardexporte des Formulars export default Identifier; wird möglicherweise nicht richtig aktualisiert.

Referenzen suchen ( find_references_by_tsmorph )

• Was es tut : Sucht und listet die Definition eines Symbols an einer bestimmten Stelle in einer angegebenen Datei sowie alle seine Referenzen im gesamten Projekt auf.

• Anwendungsfall : Sie möchten wissen, wo eine Funktion oder Variable verwendet wird. Sie möchten den Umfang eines Refactorings ausloten.

• Erforderliche Informationen : tsconfig.json Pfad des Projekts, Zieldateipfad, Symbolposition (Zeile, Spalte).

Entfernen Sie einen Pfadalias ( remove_path_alias_by_tsmorph )

• Funktion : Ersetzt Pfadaliase (wie z. @/components ) in import / export in der angegebenen Datei oder im angegebenen Verzeichnis durch relative Pfade (wie z. B. ../../components ).

• Anwendungsfall : Sie möchten Ihr Projekt portabler machen oder bestimmten Codierungsstandards entsprechen.

• Erforderliche Informationen : tsconfig.json -Pfad des Projekts, Pfad der zu verarbeitenden Datei oder des zu verarbeitenden Verzeichnisses.

Verschieben von Symbolen zwischen Dateien ( move_symbol_to_file_by_tsmorph )

• Funktion : Verschiebt das angegebene Symbol (Funktion, Variable, Klasse, Schnittstelle, Typalias, Enumeration) aus der aktuellen Datei in eine andere angegebene Datei. Aktualisieren Sie Referenzen im gesamten Projekt (einschließlich Import-/Exportpfade) automatisch, während Sie fortfahren.

• Anwendungsfall : Sie möchten bestimmte Funktionen in eine separate Datei extrahieren, um Ihren Code neu zu organisieren.

• Erforderliche Informationen : tsconfig.json Pfad des Projekts, Quelldateipfad, Zieldateipfad, Name des zu verschiebenden Symbols. Optional können Sie die Art des Symbols ( declarationKindString ) angeben, um Symbole mit demselben Namen eindeutig zu machen.

• Hinweis : Die internen Abhängigkeiten des Symbols (andere Deklarationen, die nur innerhalb dieses Symbols verwendet werden) werden ebenfalls verschoben. Abhängigkeiten, auf die auch von anderen Symbolen verwiesen wird, die in der Quelldatei verbleiben, verbleiben in der Quelle, und export werden nach Bedarf hinzugefügt und in die Zieldatei importiert.

• Hinweis : export default können mit diesem Tool nicht verschoben werden.

Umweltkonstruktion

Für Benutzer (als npm-Paket)

Fügen Sie mcp.json die folgenden Einstellungen hinzu. Wenn Sie den Befehl npx verwenden, wird automatisch die neueste Version verwendet, die Sie installiert haben.

Für Entwickler (für lokale Entwicklung und Ausführung)

Wenn Sie den Server lokal aus dem Quellcode ausführen möchten, müssen Sie ihn zuerst erstellen.

Nach dem Erstellen können Sie es direkt im node ausführen, indem Sie Folgendes in mcp.json festlegen:

Protokollierungseinstellungen (Umgebungsvariablen)

Die Ausgabeebene und das Ziel des Serverbetriebsprotokolls können mithilfe der folgenden Umgebungsvariablen gesteuert werden. Legen Sie es im env von mcp.json fest.

• LOG_LEVEL : Legt die Ausführlichkeit des Protokolls fest.

  • Verfügbare Ebenen: fatal , error , warn , info (Standard), debug , trace , silent

  • Beispiel: "LOG_LEVEL": "debug"

• LOG_OUTPUT : Gibt das Ziel der Protokollausgabe an.

  • console (Standard): Protokolliert in die Standardausgabe. Wenn Sie sich in einer Entwicklungsumgebung ( NODE_ENV !== 'production' ) befinden und pino-pretty installiert haben, erfolgt die Ausgabe in einem hübschen Format.

  • file : Gibt das Protokoll in die angegebene Datei aus. Legen Sie dies fest, um eine Beeinträchtigung der MCP-Clients zu vermeiden.

  • Beispiel: "LOG_OUTPUT": "file"

• LOG_FILE_PATH : Wenn LOG_OUTPUT auf file gesetzt ist, gibt dies den absoluten Pfad der Protokolldatei an.

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

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

Beispielkonfiguration (in mcp.json ):

Entwicklerinformationen

Voraussetzungen

• Node.js (Version siehe .node-version oder volta in package.json )

• pnpm (siehe Feld packageManager in package.json für die Version)

aufstellen

Klonen Sie das Repository und installieren Sie die Abhängigkeiten:

Bauen

Kompiliert TypeScript-Code in JavaScript.

Die Build-Artefakte werden in dist -Verzeichnis ausgegeben.

prüfen

Führen Sie die Komponententests aus.

Lintierung und Formatierung

Es analysiert und formatiert Ihren Code statisch.

Verwenden des Debugging-Wrappers

Wenn Sie während der Entwicklung die Startreihenfolge, die Standard-Ein-/Ausgabe und die Fehlerausgabe des MCP-Servers im Detail überprüfen möchten, können Sie mcp_launcher.js verwenden, das sich im scripts des Projekts befindet.

Dieses Wrapper-Skript startet den ursprünglichen MCP-Serverprozess ( npx -y @sirosuzume/mcp-tsmorph-refactor ) als untergeordneten Prozess und protokolliert die Startinformationen und die Ausgabe in .logs/mcp_launcher.log im Projektstammverzeichnis.

Anwendung:

1. Ändern Sie in der Datei mcp.json``mcp-tsmorph-refactor wie folgt:

   • Setzen Sie command auf "node" .

   • Geben Sie in args den Pfad zu scripts/mcp_launcher.js an (z. B. ["path/to/your_project_root/scripts/mcp_launcher.js"] ). Sie können auch einen Pfad relativ zum Projektstamm verwenden ( ["scripts/mcp_launcher.js"] ).

   Beispielkonfiguration ( 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. Starten Sie den MCP-Client (z. B. Cursor) neu oder laden Sie ihn neu.

3. Bitte bestätigen Sie, dass das Protokoll in .logs/mcp_launcher.log im Projektstamm ausgegeben wird. Sie können auch das Protokoll des MCP-Servers selbst überprüfen, sofern konfiguriert (z. B. .logs/mcp-ts-morph.log ).

Mithilfe dieses Wrappers können Sie diagnostizieren, warum Ihr MCP-Server nicht wie erwartet startet.

Veröffentlichen auf npm

Dieses Paket wird automatisch über einen GitHub Actions-Workflow ( .github/workflows/release.yml ) in npm veröffentlicht.

Voraussetzungen

• NPM-Token: Stellen Sie sicher, dass Sie in den Aktionsgeheimnissen Ihres Repositorys ( Settings > Secrets and variables > Actions ) ein NPM-Zugriffstoken mit öffentlichen Berechtigungen mit dem Namen NPM_TOKEN haben.

• Aktualisieren Sie Ihre Version: Aktualisieren Sie vor der Veröffentlichung das version in package.json gemäß Semantic Versioning (SemVer).

So veröffentlichen Sie

Um den Release-Workflow auszulösen, verwenden Sie einen Git-Tag-Push.

Vorgehensweise: Pushen eines Git-Tags (empfohlen für Releases)

• Verwendungszweck: Regelmäßige Versionsveröffentlichungen (Major, Minor, Patch). Git ist der empfohlene Standard-Releaseprozess, da es eine klare Entsprechung zwischen Verlauf und Versionen bietet.

1. Version aktualisieren: Ändern Sie version in package.json (z. B. 0.3.0 ).

2. Commit & Push: Commiten Sie die Änderungen an package.json und pushen Sie sie in den Hauptzweig.

3. Tag erstellen und pushen: Erstellt ein Git-Tag (mit v Präfix), das der Version entspricht, und pusht es.

   git tag v0.3.0 git push origin v0.3.0

4. Automatisierung: Durch das Pushen eines Tags wird der Release Package -Workflow ausgelöst, der das Paket erstellt, testet und auf npm veröffentlicht.

5. Überprüfen: Überprüfen Sie den Status Ihres Workflows auf der Registerkarte „Aktionen“ und überprüfen Sie Ihr Paket auf npmjs.com.

Vorsichtsmaßnahmen

• Versionskonsistenz: Beim Auslösen eines Tag-Pushs muss der Tag-Name (z. B. v0.3.0 ) genau mit version in package.json (z. B. 0.3.0 ) übereinstimmen. Wenn keine Übereinstimmung vorliegt, schlägt der Workflow fehl.

• Vorabprüfung: Obwohl Ihr CI-Workflow Build- und Testschritte umfasst, empfehlen wir, vor der Aktualisierung Ihrer Version pnpm run build und pnpm run test lokal auszuführen, um potenzielle Probleme frühzeitig zu erkennen.

Lizenz

Dieses Projekt wird unter der MIT-Lizenz veröffentlicht. Weitere Einzelheiten finden Sie in der Lizenzdatei .