upgrade-guide

name	upgrade-guide
description	Generate a migration guide for upgrading fa-mcp-sdk to the latest version. Use when user asks to upgrade/update fa-mcp-sdk, mentions 'обновить sdk', 'upgrade sdk', 'migration guide', 'обновление fa-mcp-sdk', or wants to see what changed between SDK versions.
disable-model-invocation	true
allowed-tools	Bash(yarn *) Bash(npm *) Bash(node *) Bash(git *) Bash(cat *) Bash(diff *) Bash(ls *) Bash(find *) Bash(mkdir *) Read Write Glob Grep WebFetch Agent
argument-hint	[from-version] [to-version] [language hint]

FA-MCP-SDK Upgrade Guide Generator

Generate a comprehensive migration guide for upgrading the fa-mcp-sdk dependency in the current project.

Overview

This skill analyzes the differences between the currently installed version of fa-mcp-sdk and the latest (or specified) version, then produces a detailed migration guide as a markdown file.

Argument Parsing

Parse $ARGUMENTS to extract a target version and an optional language hint.

Language detection

Look for a natural-language phrase anywhere in the arguments that indicates the desired output language. Examples:

• "на русском", "по-русски", "in Russian", "ru" → Russian
• "in English", "en" → English
• Any similar phrase or ISO 639-1 code

Remove the language hint from the arguments before parsing the target version.

Default: English if no language hint is found.

The detected language determines ALL human-readable text in the generated guide (headings, descriptions, recommendations). Technical content (file paths, YAML keys, code snippets, commands) stays as-is regardless of language.

Version/commit references

After stripping the language hint, the remaining arguments are version or commit references.

An argument is a commit hash if it contains 7+ hex characters and does not match semver pattern. Otherwise it is treated as a version (with or without v prefix — 0.4.30 and v0.4.30 are equivalent).

Scope of references: PROJECT (default) vs SDK

By default, all versions and commit hashes refer to THIS project (the repository where the skill is invoked), NOT to fa-mcp-sdk.

A reference is treated as referring to fa-mcp-sdk ONLY if the user's phrasing explicitly says so. Trigger phrases for SDK scope (case-insensitive, English or Russian):

• "sdk", "fa-mcp-sdk", "of sdk", "sdk commit", "sdk version"
• "sdk", "fa-mcp-sdk", "версия sdk", "комит sdk", "коммит sdk", "хеш sdk"

Examples:

• /upgrade-guide 1.2.3 1.2.7 → project versions (look up which SDK version was used in each)
• /upgrade-guide от версии 0.2.3 SDK до 0.4.5 SDK → SDK versions directly
• /upgrade-guide от комита sdk abc1234 до комита sdk def5678 → SDK commits directly
• /upgrade-guide abc1234 def5678 → project commits (look up which SDK version was pinned in each)

Resolving PROJECT references to SDK versions

When a reference is PROJECT-scoped (the default), resolve it to an SDK version/commit before computing the diff:

1. Project commit hash — run git show <hash>:package.json and extract the fa-mcp-sdk dependency value.
2. Project version (e.g. 1.2.3) — find the project git tag (v1.2.3 or 1.2.3), then git show <tag>:package.json and extract the fa-mcp-sdk value.
3. If the dependency value is a semver (e.g. ^0.4.30, ~0.4.30, 0.4.30), strip range operators to get the exact SDK version.
4. If the dependency value is a git URL with a commit hash (e.g. github:Bazilio-san/fa-mcp-sdk#abc1234), extract the commit hash as the SDK ref.
5. If the project tag/commit cannot be found, report an error and stop.

Show the user the resolution result before proceeding:

Resolved project references to SDK:
  FROM: project <ref> → SDK <version-or-commit>
  TO:   project <ref> → SDK <version-or-commit>

Argument count

Two arguments — explicit FROM and TO (resolved per scope rules above).

One argument — it is treated as FROM; TO defaults to the latest published fa-mcp-sdk version (fetched via yarn info fa-mcp-sdk version / npm view fa-mcp-sdk version). The point is to upgrade to the newest existing SDK release.

Alternative TO=HEAD mode. If the user explicitly says "to HEAD", "до HEAD", "до последнего коммита SDK", "to latest commit", "до master", or supplies the literal HEAD/master as the second argument, TO becomes the tip of master on Bazilio-san/fa-mcp-sdk (resolved via https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/master), not the latest published version. This is useful for diffing against unreleased commits. In this mode yarn add must use the git-URL form with the resolved commit hash (see Step 2).

No arguments — FROM is the current installed SDK version (from the project's current package.json); TO is the latest published SDK version.

Step 1: Determine SDK Versions

1. Read the current project's package.json and extract the installed fa-mcp-sdk version — this is the default FROM (SDK).
2. Run yarn info fa-mcp-sdk version (or npm view fa-mcp-sdk version) to get the latest published version — this is the default TO (SDK).
3. Apply argument parsing rules above (scope, count) to determine FROM and TO.
4. If any argument is PROJECT-scoped, resolve it to an SDK version/commit by reading the project's git history (see "Resolving PROJECT references to SDK versions").
5. Validate that both SDK refs actually exist before doing any diff work — fail fast with a clear message instead of letting a later GitHub API call return 404. For each of FROM-SDK and TO-SDK:
   • If it's a version (e.g. 0.4.30 / v0.4.30) — probe the GitHub tag endpoint: https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/git/refs/tags/v<version> (also try without the v prefix). Fall back to yarn info fa-mcp-sdk@<version> version — if that also fails, report Cannot resolve SDK version <X>: not found on GitHub or npm and stop.
   • If it's a commit hash — probe https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/<hash>. If it returns 404, report Cannot resolve SDK commit <hash>: not found in repo and stop.
   • If GitHub API is rate-limited, fall back to git ls-remote https://github.com/Bazilio-san/fa-mcp-sdk.git for tag/branch existence, and skip commit-hash validation with a warning.
6. If FROM-SDK equals TO-SDK — inform the user (e.g. "Both project commits pin the same SDK version X.Y.Z — nothing to diff") and stop.

Display to the user:

From: <project or SDK ref> → SDK <version-or-commit>  ✓ validated
To:   <project or SDK ref> → SDK <version-or-commit>  ✓ validated

Step 2: Upgrade the Dependency

If TO is a published version (not a commit hash), run:

yarn add fa-mcp-sdk@<TO-version>

If TO is a commit hash, run:

yarn add fa-mcp-sdk@https://github.com/Bazilio-san/fa-mcp-sdk#<TO-commit>

Wait for completion. If it fails, report the error and stop.

Step 3: Update SDK Documentation

Run:

node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js

This copies the latest FA-MCP-SDK-DOC/ and .claude/ from the SDK into the project.

Pinned folders. Any folder under the project's .claude/ that contains a direct file named pin is preserved as-is — the script neither deletes it nor overwrites it with template content. Drop a pin file into .claude/skills/<your-skill>/ (or any other .claude/ subdirectory) to protect local customizations from being reset on upgrade.

Step 4: Analyze Changes in SDK Between Versions

Use the public GitHub repository https://github.com/Bazilio-san/fa-mcp-sdk to analyze what changed.

4.1 Get the commit log between versions

Fetch the GitHub compare URL to understand what changed:

https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/compare/<FROM-ref>...<TO-ref>

Where <FROM-ref> and <TO-ref> are version tags (try both v0.4.30 and 0.4.30 formats) or commit hashes.

If version tags don't exist, use the commits API to find commits between versions, or search git log for version bump commit messages.

Alternative approach — use the npm registry to get git metadata, or simply read the changelog if available.

Explicit commit-message review. The compare endpoint returns a commits[] array — extract commit.message (subject + body) for every commit in the range, not just the file diffs. Commit messages capture the why of each change (motivation, fixed issue, design rationale) which is invisible from file diffs alone. In the generated guide, include a "Changelog" subsection that lists each commit's short hash + first line of its message in chronological order. Use these messages to:

• Spot intent (e.g. "fix: ...", "BREAKING CHANGE: ...", "refactor: ...") — flag any conventional-commit BREAKING markers prominently in the Breaking Changes section.
• Group related file changes under a single narrative ("These three files changed because of ").
• Reach out for missing context: if a file diff is non-obvious and the commit message is terse, note it in the guide as "rationale unclear — check commit <hash> directly".

If the compare API is rate-limited, fall back to fetching commits one page at a time via https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits?sha=<TO>&until=<TO-date>&since=<FROM-date>.

4.2 Analyze changes in config files

These config files in the SDK may have changed and require corresponding updates in the project:

• config/default.yaml — main configuration defaults
• config/_local.yaml — local config template (the CLI scaffolder copies this to the project's config/_local.yaml and derives config/local.yaml from it with {{param}} substitutions)
• config/custom-environment-variables.yaml — env var mappings
• config/development.yaml — dev overrides
• config/production.yaml — production overrides
• config/local.yaml (SDK's own) — reference only, not shipped to projects

For each config file, compare the SDK's version (at node_modules/fa-mcp-sdk/config/<file>) with the project's version (at config/<file>).

Identify:

• New keys added in the SDK that are missing in the project
• Removed keys that existed in the old SDK but are gone now
• Changed defaults where the SDK's default value has changed
• New sections that represent new features

Correlate changes across config files. When config/default.yaml has changes (new keys, restructured sections, changed defaults), you MUST also check config/_local.yaml for analogous changes. The _local.yaml file mirrors the structure of default.yaml but contains local-override values — if a section was added or restructured in default.yaml, the same section likely needs updating in _local.yaml.

Compare both files in the SDK's node_modules/fa-mcp-sdk/config/:

• node_modules/fa-mcp-sdk/config/default.yaml — the canonical defaults
• node_modules/fa-mcp-sdk/config/_local.yaml — the template that was used to generate the project's config/local.yaml

If default.yaml changed but _local.yaml did NOT, explicitly note this in the guide: the project's config/_local.yaml may still need manual updates to stay consistent with the new default.yaml structure.

Config file mapping (SDK source → project destination):

SDK source (in config/)	Project destination	Action
config/default.yaml	config/default.yaml	Add new keys; do NOT remove existing keys the project may have customized
config/_local.yaml	config/_local.yaml	Update to match SDK — this is the template users derive their local.yaml from
config/_local.yaml (via CLI)	config/local.yaml	Derived by CLI from _local.yaml with {{param}} substitutions — check for needed adjustments
config/custom-environment-variables.yaml	config/custom-environment-variables.yaml	Add new env var mappings
config/local.yaml (SDK's own)	(not shipped — reference only)	Use as reference for what the SDK itself overrides locally

4.3 Analyze changes in cli-template files

The SDK ships a project template at node_modules/fa-mcp-sdk/cli-template/ (after yarn add fa-mcp-sdk@<TO>). This is the canonical source for any template files in the project — when generating instructions for the user, always point to this path as the place to copy the latest version from.

Map of template file → project file (the CLI bin/fa-mcp.js applies these transformations when creating new projects — upgrades must respect the same mapping):

Template (source of truth)	Project (destination)	Notes
node_modules/fa-mcp-sdk/cli-template/package.json	package.json	Merge carefully — see rule below
node_modules/fa-mcp-sdk/cli-template/tsconfig.json	tsconfig.json	overwrite (unless customized)
node_modules/fa-mcp-sdk/cli-template/eslint.config.js	eslint.config.js	overwrite (unless customized)
node_modules/fa-mcp-sdk/cli-template/CLAUDE.md	CLAUDE.md	merge — project may add custom sections
node_modules/fa-mcp-sdk/cli-template/jest.config.js	jest.config.js	overwrite (unless customized)
node_modules/fa-mcp-sdk/cli-template/deploy/	deploy/	merge per file
node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/	.claude/skills/<skill>/	overwrite unless locally customized
node_modules/fa-mcp-sdk/cli-template/r/<name>.xml	.run/<name>.run.xml	Renamed — see rule below
node_modules/fa-mcp-sdk/cli-template/gitignore	.gitignore	source has no leading dot
node_modules/fa-mcp-sdk/cli-template/FA-MCP-SDK-DOC/	FA-MCP-SDK-DOC/	auto-updated by update-sdk.js

Rule: package.json — ADD ONLY new dependencies, do NOT touch anything else

The project's package.json has evolved since generation (project-specific name, version, scripts, dependencies the team has added). When the SDK's template package.json changes:

1. Diff node_modules/fa-mcp-sdk/cli-template/package.json (TO) against the same file at the FROM version.
2. Identify ONLY dependencies/devDependencies that were added (not changed versions of existing ones, not removed).
3. The generated guide must instruct the user: "Add these NEW entries to your package.json dependencies/devDependencies sections. Do NOT touch any other field — name, version, scripts, existing deps stay as they are."
4. If a dep was removed from the template, mention it as informational only — do not instruct deletion from the project (it may still be in use).
5. Do NOT suggest overwriting scripts, engines, type, or any other field.

Provide a copy-pasteable JSON snippet with only the new keys:

{
  "dependencies": {
    "<new-dep>": "<version>"
  }
}

Rule: r/ → .run/ with filename transformation

The project has no r/ directory — it was renamed to .run/ at project generation, and each <name>.xml inside was renamed to <name>.run.xml. When the SDK template ships new or changed files in cli-template/r/:

• Source: node_modules/fa-mcp-sdk/cli-template/r/<name>.xml
• Destination: .run/<name>.run.xml
• Action for NEW files: copy <name>.xml → .run/<name>.run.xml
• Action for CHANGED files: copy with the same rename, overwriting the existing .run.xml file (warn the user to back up any customizations)
• Action for REMOVED files: informational only — do not delete the project's .run/<name>.run.xml automatically

The generated guide must show the exact source → destination mapping for each changed file, with the filename transformation applied.

Rule: .claude/skills/<skill>/SKILL.md

This is a Claude Code skill that the project owns a copy of. If the SDK ships an updated version, instruct the user to overwrite their local copy from node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/SKILL.md — unless they've customized it locally, in which case manual merge.

For any other changed template file, the generated guide must include:

• The exact source path under node_modules/fa-mcp-sdk/cli-template/...
• The exact destination path in the project
• Whether to overwrite or merge carefully (because the project may have local customizations)

4.4 Analyze changes in scripts

The CLI copies scripts from node_modules/fa-mcp-sdk/scripts/ (NOT from cli-template/scripts/) into the project's scripts/ directory, and then removes copy-static.js and publish.sh (SDK-internal, not needed in downstream projects).

• Canonical source: node_modules/fa-mcp-sdk/scripts/<name>.js
• Project destination: scripts/<name>.js
• Exclude from upgrade suggestions: copy-static.js, publish.sh (SDK-only)

The generated guide must specify the exact source path under node_modules/fa-mcp-sdk/scripts/... for any script the user should copy into their project's scripts/ directory, and skip the excluded SDK-only scripts.

4.5 Analyze changes in core library exports

Prefer the TypeScript source over the compiled output. Fetch src/core/index.ts (and any re-exported _types_/ files it references) at both FROM and TO via GitHub raw:

https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<FROM-ref>/src/core/index.ts
https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<TO-ref>/src/core/index.ts

Compare them to identify:

• New exports that may be useful
• Removed/renamed exports that may break existing code
• Changed type signatures
• Type-level changes (generics, conditional types, union narrowing) that don't survive .d.ts emission cleanly

Why source over dist/:

• Original JSDoc comments and inline rationale are preserved in .ts but stripped/compressed in dist/*.js.
• Renames are visible as renames in the source diff; in dist/ they may appear as unrelated add+remove pairs because of import-order shuffling or minification.
• TS export * chains resolve naturally in source; in .d.ts they may be flattened, hiding which module a symbol came from originally.

Fallback — if GitHub raw is unavailable (rate-limited, network blocked), use node_modules/fa-mcp-sdk/dist/core/index.js and the matching .d.ts. State explicitly in the generated guide that the analysis was made from the compiled artifacts and recommend that the user double-check via the GitHub source viewer for any flagged change.

4.6 Check project code for breaking changes

Scan the project's src/ directory for:

• Imports from fa-mcp-sdk that reference removed/renamed exports
• Usage of deprecated APIs
• Config keys that have been renamed or restructured

Step 5: Generate Migration Guide

Write ALL headings, descriptions, and prose in the detected language (default: English). Technical content (file paths, YAML keys, code blocks, shell commands) is always in English.

Create a file upgrade-guide-<old>-to-<new>.md in the project root with the following structure:

# FA-MCP-SDK Migration Guide: v<old> -> v<new>

Generated: <timestamp>

## Summary

<Brief overview of what changed and the scope of required updates>

## Breaking Changes

<List any breaking changes that MUST be addressed. For each:>
- What changed
- What code/config is affected
- Exact fix with code snippets

## Config Changes

### New Configuration Keys

<For each new key, provide:>
- Key path (e.g., `webServer.auth.enabled`)
- Default value
- Description
- Whether it needs to be added to the project's config

### Changed Defaults

<Keys where default values changed>

### Removed Keys

<Keys that were removed>

### Recommended config/default.yaml additions

    ```yaml
    # Add these sections to your config/default.yaml:
    <actual YAML snippets to add>
    ```

### config/_local.yaml

<If `default.yaml` changed, check whether `_local.yaml` in the SDK also changed. If it did: describe what changed. If it did NOT but the `default.yaml` changes affect keys that also exist in `_local.yaml` (because `_local.yaml` overrides those keys), explicitly warn that the project's `config/_local.yaml` may need manual updates to stay consistent with the new `default.yaml` structure.>

### config/local.yaml (project-local overrides)

<Check whether the project's `config/local.yaml` overrides keys that changed in `default.yaml` or `_local.yaml`. This is especially important when: a new key is added to `default.yaml` that the project's `local.yaml` doesn't override (user just needs to know it exists); a key's meaning or structure changed and `local.yaml` has a stale override; `local.yaml` was derived from the old `_local.yaml` and needs re-derivation from the updated template.>

### Recommended config/custom-environment-variables.yaml additions

    ```yaml
    # Add these mappings:
    <actual YAML snippets>
    ```

## Template File Changes

> **Source of truth**: all updated template files live under `node_modules/fa-mcp-sdk/cli-template/` (after `yarn add fa-mcp-sdk@<TO>`). Copy from there into the project.

### package.json

> **Only ADD new dependencies. Do NOT touch anything else** (name, version, scripts, existing deps — all stay untouched). Source: `node_modules/fa-mcp-sdk/cli-template/package.json`.

<List only dependencies/devDependencies that were newly added in the SDK template. Provide a copy-pasteable JSON snippet 
with only the new keys. Mention removed deps as informational only — do not instruct deletion.>

### `.run/` (from `cli-template/r/`)

<For each changed `cli-template/r/<name>.xml`, show the mapping:>
- Source: `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`
- Destination: `.run/<name>.run.xml` (note the rename)
- Action: copy + rename (overwrite, warn about local customizations)

### Claude Code Skills (`.claude/skills/`)

<For each updated skill, e.g. `upgrade-guide`:>
- Source: `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill-name>/SKILL.md`
- Destination: `.claude/skills/<skill-name>/SKILL.md`
- Action: overwrite (unless locally customized — then manual merge)

### Other Template Files

<For each: source path under `node_modules/fa-mcp-sdk/cli-template/...`, destination, overwrite or merge.>

## New Features

<New SDK features that the project can now use>

## New/Updated Scripts

<Scripts that should be copied or updated>

## Code Changes Required

<Specific code changes needed in the project's src/ files, with before/after examples>

## Recommended Actions

<Ordered checklist of actions to complete the upgrade>

1. [ ] ...
2. [ ] ...

Step 6: Assess Impact on the Project

After generating the guide, scan the current project's source code (src/, config/, tests/) to evaluate how the changes specifically affect THIS project. Add a section to the guide:

## Impact Assessment for This Project

### Affected Files

<List of project files that need modification, with specific changes>

### Risk Level

<Low / Medium / High — based on the number and nature of breaking changes>

### Estimated Effort

<Brief assessment of the work required>

Step 7: Present Results

1. Display a summary of the key findings to the user.
2. Tell the user the full guide has been saved to upgrade-guide-<old>-to-<new>.md.
3. Ask if they want you to apply any of the recommended changes automatically.

Important Rules

• ALWAYS read the actual files to compare — do not guess or assume what changed.
• When comparing YAML configs, preserve comments and structure.
• Correlate config file changes: when config/default.yaml changes, ALWAYS also check config/_local.yaml in the SDK. Report whether _local.yaml has analogous changes or needs manual updates. Also advise checking the project's config/local.yaml for stale overrides that may conflict with the new defaults.
• Do not forget config/local.yaml in the project: the project's config/local.yaml overrides config/default.yaml. When new keys are added or sections restructured in default.yaml, explicitly instruct the user to verify that their config/local.yaml doesn't have stale overrides that conflict with the new structure, and to add any new keys there too if they want non-default values.
• Do not modify project files other than package.json (via yarn add) and FA-MCP-SDK-DOC/ (via update-sdk.js) unless the user explicitly asks.
• The migration guide must contain ACTIONABLE instructions with exact code/config snippets — not vague recommendations.
• If GitHub API is unavailable or rate-limited, fall back to comparing files directly from node_modules/fa-mcp-sdk/ against project files.
• Write the guide in the language detected from the user's arguments (default: English). Translate all headings, prose, and descriptions. Keep file paths, YAML keys, code blocks, and shell commands in English.