ts-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ts-mcp-server contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# ts-mcp-server
+
+A lightweight [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for **TypeScript and JavaScript refactoring**. Rename or move files and folders across your codebase and have every `import`, `require`, and re-export updated automatically — powered by the same TypeScript language service that drives VS Code.
+
+## Why
+
+AI coding assistants can read and write code, but they struggle with **structural changes** that ripple across many files. Moving a React component, renaming a utility module, or reorganizing a folder means updating every import that references it. Miss one and the build breaks.
+
+`ts-mcp-server` gives any MCP-compatible client — [VS Code Copilot](https://code.visualstudio.com/), [Claude Desktop](https://claude.ai/), [Cursor](https://cursor.sh/), [Windsurf](https://codeium.com/windsurf), [Continue](https://continue.dev/), and others — the ability to perform these refactors **correctly and completely**, using TypeScript's own compiler infrastructure.
+
+## Features
+
+- **Rename / move files** — `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`
+- **Rename / move folders** — all imports referencing files inside the folder are updated
+- **Automatic project discovery** — `tsconfig.json` is detected automatically; no configuration needed
+- **Multi-project support** — monorepos, project references, and composite builds work out of the box
+- **Preview mode** — see exactly what would change before applying anything
+- **Cross-platform** — Windows, macOS, and Linux
+
+## How It Works
+
+Under the hood, `ts-mcp-server` communicates with TypeScript's `tsserver` over Node IPC. When you rename a file or folder, it calls [`getEditsForFileRename`](https://github.com/microsoft/TypeScript/wiki/Standalone-Server-%28tsserver%29) — the same API that VS Code uses — to compute every import path that needs updating, applies the edits to disk, then moves the file or folder.
+
+There is no regex, no custom path resolution, no heuristics. The TypeScript compiler does all the work.
+
+## Quick Start
+
+### Install
+
+```bash
+npx ts-mcp-server
+```
+
+### Configure Your MCP Client
+
+Add `ts-mcp-server` to your client's MCP configuration.
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "ts-mcp-server": {
+      "command": "npx",
+      "args": ["ts-mcp-server"]
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ts-mcp-server": {
+      "command": "npx",
+      "args": ["ts-mcp-server"]
+    }
+  }
+}
+```
+
+**Cursor, Windsurf, Continue** — follow each client's MCP server documentation using the same `npx ts-mcp-server` command.
+
+## Tool Reference
+
+### `rename_file_or_dir`
+
+Rename or move a TypeScript/JavaScript file or folder and update all import paths across the project.
+
+| Parameter | Type      | Required | Description                                                                                   |
+| --------- | --------- | -------- | --------------------------------------------------------------------------------------------- |
+| `from`    | `string`  | ✅       | Current file or folder path (absolute or relative to cwd)                                     |
+| `to`      | `string`  | ✅       | New file or folder path (absolute or relative to cwd)                                         |
+| `preview` | `boolean` | —        | If `true`, returns a summary of what would change without applying anything. Default: `false` |
+
+**Examples:**
+
+```
+# Rename a file
+rename_file_or_dir  from="src/utils/helpers.ts"  to="src/utils/string-helpers.ts"
+
+# Move a file to a different directory
+rename_file_or_dir  from="src/Button.tsx"  to="src/components/ui/Button.tsx"
+
+# Rename a folder
+rename_file_or_dir  from="src/components/primitives"  to="src/components/ui"
+
+# Preview changes without applying
+rename_file_or_dir  from="src/old-name.ts"  to="src/new-name.ts"  preview=true
+```
+
+## Supported Languages & Frameworks
+
+`ts-mcp-server` works with any project that TypeScript's language service understands:
+
+- **TypeScript** (`.ts`, `.tsx`, `.mts`, `.cts`)
+- **JavaScript** (`.js`, `.jsx`, `.mjs`, `.cjs`)
+- **React** / **Next.js** / **Remix** / **Astro**
+- **Vue** (script blocks)
+- **Node.js** / **Express** / **Fastify** / **NestJS**
+- **Angular**
+- **Svelte** (script blocks)
+- **Electron**
+- **React Native**
+- **Monorepos** (Turborepo, Nx, Lerna, pnpm workspaces)
+
+If your project has a `tsconfig.json` (or `jsconfig.json`), it works.
+
+## System Requirements
+
+| Requirement    | Version                                       |
+| -------------- | --------------------------------------------- |
+| **Node.js**    | 22 or later (current LTS)                     |
+| **TypeScript** | 5.x (installed automatically as a dependency) |
+| **OS**         | Windows, macOS, Linux                         |
+
+No additional dependencies or global tools are required. The server bundles everything it needs.
+
+## FAQ
+
+**Does it work without a `tsconfig.json`?**
+Yes. TypeScript will create an inferred project, but explicit configuration gives better results.
+
+**Does it update `package.json` or non-code files?**
+No. It updates TypeScript/JavaScript import and export statements, and path-related entries in `tsconfig.json` (`files`, `include`, `exclude`, `paths`).
+
+**Can I use it with JavaScript-only projects?**
+Yes. Add a `jsconfig.json` (which is equivalent to `tsconfig.json` with `allowJs: true`) and the server will discover your project.
+
+**Does it work with path aliases (`@/components/...`)?**
+Yes. `tsserver` resolves path aliases defined in `tsconfig.json`'s `paths` and `baseUrl` settings.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fork } from "child_process";
+import { createRequire } from "module";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "fs";
+import { dirname, resolve, join } from "path";
+import { z } from "zod";
+function toAbsolutePath(base, input) {
+    return resolve(base, input);
+}
+let seq = 0;
+const pending = new Map();
+const tsserver = fork(createRequire(import.meta.url).resolve("typescript/lib/tsserver.js"), ["--useNodeIpc", "--disableAutomaticTypingAcquisition"], { silent: true });
+tsserver.on("message", (msg) => {
+    if (msg.type === "response" && msg.request_seq !== undefined) {
+        const p = pending.get(msg.request_seq);
+        if (p) {
+            pending.delete(msg.request_seq);
+            msg.success ? p.resolve(msg.body) : p.reject(new Error(msg.message));
+        }
+    }
+});
+function send(command, args) {
+    const id = ++seq;
+    tsserver.send({ seq: id, type: "request", command, arguments: args });
+    return new Promise((resolve, reject) => {
+        pending.set(id, { resolve: resolve, reject });
+    });
+}
+// ── Query: ensure project is loaded, then ask for rename edits ──
+//
+// tsserver is an editor service — it only knows about projects whose
+// files have been "opened." We handle that here so callers never
+// need to think about it.
+async function getEditsForRename(oldPath, newPath, fileToOpen) {
+    await send("open", { file: fileToOpen });
+    return send("getEditsForFileRename-full", {
+        oldFilePath: oldPath,
+        newFilePath: newPath,
+    });
+}
+// ── Apply edits to file text (bottom-up to preserve offsets) ────
+function applyEdits(text, edits) {
+    return edits.reduceRight((t, { span, newText }) => t.slice(0, span.start) + newText + t.slice(span.start + span.length), text);
+}
+// ── Boot ────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "ts-mcp-server",
+    version: "1.0.0",
+});
+server.registerTool("rename_file_or_dir", {
+    title: "Rename / Move File or Folder",
+    description: "Rename or move a TypeScript/JavaScript file OR folder and automatically update all import paths across the project. Supports .ts, .tsx, .js, .jsx. tsserver auto-discovers the relevant tsconfig.json. For folders, all imports referencing files inside the folder are updated.",
+    inputSchema: z.object({
+        from: z
+            .string()
+            .describe("Current file or folder path (absolute or relative to cwd)"),
+        to: z
+            .string()
+            .describe("New file or folder path (absolute or relative to cwd)"),
+        preview: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, show what would change without applying anything"),
+    }),
+}, async ({ from, to, preview }) => {
+    try {
+        const oldPath = toAbsolutePath(process.cwd(), from);
+        const newPath = toAbsolutePath(process.cwd(), to);
+        const stat = statSync(oldPath, { throwIfNoEntry: false });
+        if (!stat) {
+            return {
+                content: [{ type: "text", text: `Not found: ${oldPath}` }],
+                isError: true,
+            };
+        }
+        if (existsSync(newPath)) {
+            return {
+                content: [
+                    { type: "text", text: `Destination already exists: ${newPath}` },
+                ],
+                isError: true,
+            };
+        }
+        const isDir = stat.isDirectory();
+        const fileToOpen = isDir ?
+            readdirSync(oldPath, { withFileTypes: true }).find((e) => e.isFile())
+            : undefined;
+        if (isDir && !fileToOpen) {
+            return {
+                content: [{ type: "text", text: `No files found in ${oldPath}` }],
+                isError: true,
+            };
+        }
+        const edits = await getEditsForRename(oldPath, newPath, isDir ? join(oldPath, fileToOpen.name) : oldPath);
+        const withChanges = edits.filter((e) => e.textChanges.length > 0);
+        if (preview) {
+            const totalEdits = withChanges.reduce((n, e) => n + e.textChanges.length, 0);
+            const summary = withChanges.length === 0 ?
+                `No import updates needed.`
+                : `Would update ${totalEdits} import(s) across ${withChanges.length} file(s).`;
+            return { content: [{ type: "text", text: summary }] };
+        }
+        // Apply edits to each affected file on disk
+        const updated = [];
+        for (const fileEdit of withChanges) {
+            try {
+                const original = readFileSync(fileEdit.fileName, "utf-8");
+                writeFileSync(fileEdit.fileName, applyEdits(original, fileEdit.textChanges), "utf-8");
+                updated.push(fileEdit.fileName);
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error updating ${fileEdit.fileName}: ${e}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        // Move the file/folder itself
+        mkdirSync(dirname(newPath), { recursive: true });
+        renameSync(oldPath, newPath);
+        const what = isDir ? "folder" : "file";
+        const summary = updated.length > 0 ?
+            `Done. Renamed ${what}. Updated imports in ${updated.length} file(s).`
+            : `Done. Renamed ${what}. No import updates needed.`;
+        return { content: [{ type: "text", text: summary }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: String(e) }], isError: true };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ts-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server that renames/moves TypeScript files and updates all imports via tsserver",
+  "type": "module",
+  "bin": {
+    "ts-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "typescript",
+    "javascript",
+    "react",
+    "tsx",
+    "jsx",
+    "refactor",
+    "refactoring",
+    "rename",
+    "move-file",
+    "import-update",
+    "tsserver",
+    "language-server",
+    "code-automation",
+    "ai-tools",
+    "copilot",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "author": "andyliner",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@types/node": "^22"
+  }
+}