@microsoft/jsts-upgrade-assistant

A modernization tool that helps developers upgrade their TypeScript npm dependencies and TypeScript compiler version. The package ships an MCP (Model Context Protocol) server plus a set of Agent Skills that orchestrate the upgrade workflow end-to-end.

⚠️ Pre-release. This package is currently published under the beta dist-tag. All install commands below pin @beta explicitly. Once 0.2.x ships under the latest tag, the @beta suffix will no longer be required.

Installation

# Install globally
npm install -g @microsoft/jsts-upgrade-assistant@beta

# Or install locally in your project
npm install --save-dev @microsoft/jsts-upgrade-assistant@beta

The package will automatically download the correct platform-specific binary for your system.

Supported Platforms

• Windows x64 (Intel/AMD)
• Windows ARM64
• Linux x64 (Intel/AMD)
• Linux ARM64
• macOS x64 (Intel)
• macOS ARM64 (Apple Silicon)

Requirements

• Node.js 14.0.0 or higher

Usage

The primary entry point is the MCP server. Point your MCP-capable host (Visual Studio, VS Code with Copilot, Claude Desktop, etc.) at the jsts-upgrade --mcp command:

jsts-upgrade --mcp

Example MCP host config (JSON):

{
  "mcpServers": {
    "jstsUpgradeAssistant": {
      "command": "npx",
      "args": ["-y", "@microsoft/jsts-upgrade-assistant@beta", "--mcp"]
    }
  }
}

Once connected, the server exposes tools for scanning dependencies, planning upgrades, applying package changes, compiling, and validating runtime behavior. Agent Skills (below) drive these tools through the full upgrade flow.

Agent Skills

The package bundles two Agent Skills under skills/ that an MCP-aware agent can invoke to drive an upgrade end-to-end:

• typescript-dependencies-upgrade — upgrade a project's npm dependencies to their latest versions and resolve any breaking changes (compilation, install, runtime).
• typescript-compiler-upgrade — upgrade the typescript package itself, along with the type-checker configuration, and resolve resulting type errors.

After installing the package, the skill files live at:

<install-root>/skills/typescript-dependencies-upgrade/SKILL.md
<install-root>/skills/typescript-compiler-upgrade/SKILL.md

Where <install-root> is node_modules/@microsoft/jsts-upgrade-assistant/ for local installs, or your global node_modules for -g installs. Hosts that support Agent Skills (for example, certain Copilot front-ends) can register these directories directly. Hosts that don't can read each SKILL.md and use it as a prompt template.

Programmatic Usage

To resolve the path of the underlying platform binary from Node.js (for example, to spawn it from your own tooling):

import { getExePath } from "@microsoft/jsts-upgrade-assistant";
import { spawn } from "child_process";

const executablePath = getExePath(); // throws if the platform is unsupported
const child = spawn(executablePath, ["--mcp"], { stdio: "inherit" });

child.on("exit", (code) => {
  process.exit(code ?? 0);
});

Architecture

This package uses a multi-package architecture for efficient platform-specific binary distribution:

• Main package (@microsoft/jsts-upgrade-assistant): JavaScript wrapper, CLI shim, and Agent Skill files.
• Platform packages: one per supported os-arch, each containing only its native binary:
  • @microsoft/jsts-upgrade-assistant-win32-x64
  • @microsoft/jsts-upgrade-assistant-win32-arm64
  • @microsoft/jsts-upgrade-assistant-linux-x64
  • @microsoft/jsts-upgrade-assistant-linux-arm64
  • @microsoft/jsts-upgrade-assistant-darwin-x64
  • @microsoft/jsts-upgrade-assistant-darwin-arm64

When you install the main package, npm automatically installs the appropriate platform-specific package as an optional dependency.

Package Contents

@microsoft/jsts-upgrade-assistant/
├── lib/          # JavaScript wrapper and CLI shim
├── skills/       # Agent Skill files (.md) for upgrade workflow orchestration
│   ├── typescript-dependencies-upgrade/
│   │   ├── SKILL.md
│   │   └── ...
│   └── typescript-compiler-upgrade/
│       ├── SKILL.md
│       └── ...
├── LICENSE
├── README.md
└── package.json

License

This software is licensed under the Microsoft Software License Terms for JS/TS Upgrade Assistant. Copyright (c) Microsoft Corporation.