fa-mcp-sdk 0.4.95 → 0.4.96
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,554 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: upgrade-sdk
|
|
3
|
+
description: "Upgrade fa-mcp-sdk in the current project end-to-end: analyze the version diff, present an actionable execution plan, get user confirmation, then apply the upgrade automatically (deps, configs, code) — asking the user inline for any choices or values it needs. Falls back to a manual checklist only for items the LLM genuinely cannot perform. Use when user asks to upgrade/update fa-mcp-sdk, mentions 'обновить sdk', 'upgrade sdk', 'обновление fa-mcp-sdk', 'обнови sdk', or supplies versions to upgrade between."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
allowed-tools: Bash(yarn *) Bash(npm *) Bash(node *) Bash(git *) Bash(cat *) Bash(diff *) Bash(ls *) Bash(find *) Bash(mkdir *) Bash(cp *) Bash(mv *) Bash(rm *) Read Write Edit MultiEdit Glob Grep WebFetch Agent
|
|
6
|
+
argument-hint: "[from-version] [to-version] [language hint]"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# FA-MCP-SDK Upgrader
|
|
10
|
+
|
|
11
|
+
Execute an end-to-end upgrade of the `fa-mcp-sdk` dependency in the current project: analyze the diff between two
|
|
12
|
+
versions, present an actionable execution plan, get user confirmation, apply the changes automatically (asking for any
|
|
13
|
+
inputs needed along the way), verify, and report.
|
|
14
|
+
|
|
15
|
+
## Operating principle
|
|
16
|
+
|
|
17
|
+
**Maximize automation.** Do as much as possible inside this skill. The only items that should end up on a "manual"
|
|
18
|
+
checklist are those the LLM genuinely cannot perform from within this session (e.g. they depend on production secrets it
|
|
19
|
+
has no way to obtain, or on coordination with humans in external systems). When the LLM **can** perform a step but needs
|
|
20
|
+
information from the user — a credential, a config value with no sensible default, a choice between alternatives,
|
|
21
|
+
confirmation about overwriting a locally-customized file — it must **ask the user inline** rather than punt the task
|
|
22
|
+
to the manual list.
|
|
23
|
+
|
|
24
|
+
The user expects: confirm the plan → upgrade is fully done by the time the skill finishes. Failures must be reported
|
|
25
|
+
with concrete next-step options (retry, fix, roll back, leave-as-is) — never silently swallowed.
|
|
26
|
+
|
|
27
|
+
## Workflow at a glance
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
1. Parse arguments → resolve FROM/TO refs
|
|
31
|
+
2. Validate refs → fail fast on bogus versions
|
|
32
|
+
3. Preflight safety → branch + uncommitted-changes check
|
|
33
|
+
4. Install TO into project → `yarn add fa-mcp-sdk@<TO>` (first mutation)
|
|
34
|
+
5. Analyze diff → categorize every change as Auto / Needs-Input / Manual
|
|
35
|
+
6. Build execution plan
|
|
36
|
+
7. PRESENT PLAN + CONFIRM ← blocking gate; nothing else mutates until user says go
|
|
37
|
+
8. Execute Auto items, ask user inline for Needs-Input items as we reach them
|
|
38
|
+
9. Verify (build, lint, typecheck, tests, clean startup)
|
|
39
|
+
10. Report (chat + claudedocs/upgrade-sdk-<FROM>-to-<TO>.md)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Step 1: Argument parsing
|
|
43
|
+
|
|
44
|
+
Parse `$ARGUMENTS` to extract a target version and an optional language hint.
|
|
45
|
+
|
|
46
|
+
### Language detection
|
|
47
|
+
|
|
48
|
+
Look anywhere in the arguments for a natural-language phrase indicating the desired output language:
|
|
49
|
+
- "на русском", "по-русски", "in Russian", "ru" → Russian
|
|
50
|
+
- "in English", "en" → English
|
|
51
|
+
- Any similar phrase or ISO 639-1 code.
|
|
52
|
+
|
|
53
|
+
Strip the language hint from the arguments before parsing versions. **Default: English** if no hint is found.
|
|
54
|
+
|
|
55
|
+
The detected language controls ALL human-readable text in the plan and the report (headings, prose, recommendations).
|
|
56
|
+
Technical content (file paths, YAML keys, code snippets, shell commands) stays as-is regardless of language.
|
|
57
|
+
|
|
58
|
+
### Version/commit references
|
|
59
|
+
|
|
60
|
+
After stripping the language hint, the remaining arguments are version or commit references.
|
|
61
|
+
|
|
62
|
+
An argument is a **commit hash** if it contains 7+ hex characters and does not match a semver pattern. Otherwise it is
|
|
63
|
+
a **version** (with or without `v` prefix — `0.4.30` and `v0.4.30` are equivalent).
|
|
64
|
+
|
|
65
|
+
#### Scope of references: PROJECT (default) vs SDK
|
|
66
|
+
|
|
67
|
+
**By default, versions and commit hashes refer to THIS project** (the repository where the skill is invoked), NOT to
|
|
68
|
+
fa-mcp-sdk. A reference is SDK-scoped ONLY if the user's phrasing explicitly says so. Trigger phrases (case-insensitive,
|
|
69
|
+
English or Russian):
|
|
70
|
+
- "sdk", "fa-mcp-sdk", "of sdk", "sdk commit", "sdk version"
|
|
71
|
+
- "sdk", "fa-mcp-sdk", "версия sdk", "комит sdk", "коммит sdk", "хеш sdk"
|
|
72
|
+
|
|
73
|
+
Examples:
|
|
74
|
+
- `/upgrade-sdk 1.2.3 1.2.7` → project versions (look up the SDK version pinned in each)
|
|
75
|
+
- `/upgrade-sdk от версии 0.2.3 SDK до 0.4.5 SDK` → SDK versions directly
|
|
76
|
+
- `/upgrade-sdk от комита sdk abc1234 до комита sdk def5678` → SDK commits directly
|
|
77
|
+
- `/upgrade-sdk abc1234 def5678` → project commits (look up the SDK version pinned in each)
|
|
78
|
+
|
|
79
|
+
#### Resolving PROJECT references to SDK versions
|
|
80
|
+
|
|
81
|
+
When a reference is PROJECT-scoped (the default), resolve it to an SDK version/commit before computing the diff:
|
|
82
|
+
|
|
83
|
+
1. **Project commit hash** — run `git show <hash>:package.json` and extract `fa-mcp-sdk` from `dependencies`.
|
|
84
|
+
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`.
|
|
85
|
+
3. If the dependency value is semver (`^0.4.30`, `~0.4.30`, `0.4.30`), strip range operators → exact SDK version.
|
|
86
|
+
4. If the dependency value is a git URL with a commit hash (e.g. `github:Bazilio-san/fa-mcp-sdk#abc1234`), extract the
|
|
87
|
+
commit hash as the SDK ref.
|
|
88
|
+
5. If the project tag/commit cannot be found, report and stop.
|
|
89
|
+
|
|
90
|
+
Show the resolution result before proceeding:
|
|
91
|
+
```
|
|
92
|
+
Resolved project references to SDK:
|
|
93
|
+
FROM: project <ref> → SDK <version-or-commit>
|
|
94
|
+
TO: project <ref> → SDK <version-or-commit>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
#### Argument count
|
|
98
|
+
|
|
99
|
+
**Two arguments** — explicit FROM and TO (resolved per scope rules above).
|
|
100
|
+
|
|
101
|
+
**One argument** — it is treated as **FROM**; TO defaults to the **latest published fa-mcp-sdk** (fetched via
|
|
102
|
+
`yarn info fa-mcp-sdk version` or `npm view fa-mcp-sdk version`). Goal: upgrade to the newest existing release.
|
|
103
|
+
|
|
104
|
+
**Alternative TO=HEAD mode.** If the user explicitly says "to HEAD", "до HEAD", "до последнего коммита SDK",
|
|
105
|
+
"to latest commit", "до master", or supplies the literal `HEAD`/`master` as the second argument, TO becomes the
|
|
106
|
+
**tip of `master` on `Bazilio-san/fa-mcp-sdk`** (resolved via
|
|
107
|
+
`https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/master`) instead of the latest **published** version.
|
|
108
|
+
In this mode `yarn add` must use the git-URL form with the resolved commit hash (see Step 4).
|
|
109
|
+
|
|
110
|
+
**No arguments** — FROM is the currently installed SDK version (from the project's current `package.json`); TO is the
|
|
111
|
+
latest published SDK version.
|
|
112
|
+
|
|
113
|
+
## Step 2: Validate refs (fail fast)
|
|
114
|
+
|
|
115
|
+
Read the project's `package.json` for the default FROM, fetch the latest published version for the default TO, then
|
|
116
|
+
apply argument-parsing rules to determine FROM and TO. Before any analysis or mutation, **validate both SDK refs
|
|
117
|
+
actually exist** — fail fast with a clear message rather than letting a later GitHub API call return 404. For each ref:
|
|
118
|
+
|
|
119
|
+
- If it's a **version** (`0.4.30` / `v0.4.30`) — probe
|
|
120
|
+
`https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/git/refs/tags/v<version>` (also try without `v`).
|
|
121
|
+
Fall back to `yarn info fa-mcp-sdk@<version> version` — if that also fails, report
|
|
122
|
+
`Cannot resolve SDK version <X>: not found on GitHub or npm` and stop.
|
|
123
|
+
- If it's a **commit hash** — probe `https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/<hash>`.
|
|
124
|
+
On 404, report `Cannot resolve SDK commit <hash>: not found in repo` and stop.
|
|
125
|
+
- If GitHub API is rate-limited, fall back to `git ls-remote https://github.com/Bazilio-san/fa-mcp-sdk.git` for
|
|
126
|
+
tag/branch existence, and skip commit-hash validation with a warning.
|
|
127
|
+
|
|
128
|
+
If FROM == TO, inform the user (e.g. "Both project commits pin the same SDK version X.Y.Z — nothing to do") and stop.
|
|
129
|
+
|
|
130
|
+
Display:
|
|
131
|
+
```
|
|
132
|
+
From: <project or SDK ref> → SDK <version-or-commit> ✓ validated
|
|
133
|
+
To: <project or SDK ref> → SDK <version-or-commit> ✓ validated
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Step 3: Preflight safety
|
|
137
|
+
|
|
138
|
+
This is the last point before mutating the project. Run these checks and **ask the user inline** when relevant:
|
|
139
|
+
|
|
140
|
+
1. **Branch check.** Run `git rev-parse --abbrev-ref HEAD`. If the user is on `main`/`master`/`prod`/`production`, ask:
|
|
141
|
+
"You're on `<branch>`. I recommend creating `upgrade/sdk-<TO>` before mutating anything. Create it? (yes/no)"
|
|
142
|
+
On yes, run `git checkout -b upgrade/sdk-<TO>`. On no, proceed but note it in the report so rollback expectations
|
|
143
|
+
are clear.
|
|
144
|
+
2. **Uncommitted changes.** Run `git status --short`. If non-empty, ask:
|
|
145
|
+
"I see N uncommitted changes. To stay safe I can: (1) stash them, (2) require you to commit first, (3) proceed
|
|
146
|
+
anyway (rollback will affect your in-flight work). Pick one." Apply the user's choice.
|
|
147
|
+
3. **Capture rollback info.** Record:
|
|
148
|
+
- current commit hash: `git rev-parse HEAD`
|
|
149
|
+
- prior installed SDK version: from the current `package.json`
|
|
150
|
+
|
|
151
|
+
These go into the final report's rollback section regardless of outcome.
|
|
152
|
+
|
|
153
|
+
## Step 4: Install the target SDK version
|
|
154
|
+
|
|
155
|
+
This is the first mutating action. From here on, we're committed to either finishing the upgrade or rolling back.
|
|
156
|
+
|
|
157
|
+
If TO is a published version:
|
|
158
|
+
```bash
|
|
159
|
+
yarn add fa-mcp-sdk@<TO-version>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
If TO is a commit hash:
|
|
163
|
+
```bash
|
|
164
|
+
yarn add fa-mcp-sdk@https://github.com/Bazilio-san/fa-mcp-sdk#<TO-commit>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Wait for completion. If `yarn add` fails, show the error verbatim and ask the user how to proceed (retry, switch to a
|
|
168
|
+
different TO ref, or abort).
|
|
169
|
+
|
|
170
|
+
Then run:
|
|
171
|
+
```bash
|
|
172
|
+
node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js
|
|
173
|
+
```
|
|
174
|
+
This copies the latest `FA-MCP-SDK-DOC/` and `.claude/` content from the SDK into the project. Pinned folders (any
|
|
175
|
+
folder under the project's `.claude/` containing a direct file named `pin`) are preserved by the script as-is.
|
|
176
|
+
|
|
177
|
+
## Step 5: Analyze the diff
|
|
178
|
+
|
|
179
|
+
Use `https://github.com/Bazilio-san/fa-mcp-sdk` (public repo) to inspect what changed between FROM and TO. **Read
|
|
180
|
+
actual content — do not guess.**
|
|
181
|
+
|
|
182
|
+
### 5.1 Commit log
|
|
183
|
+
|
|
184
|
+
Fetch:
|
|
185
|
+
```
|
|
186
|
+
https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/compare/<FROM-ref>...<TO-ref>
|
|
187
|
+
```
|
|
188
|
+
The `commits[]` array carries the **why** of each change (motivation, fixed issue) that file diffs alone don't show.
|
|
189
|
+
Extract `commit.message` (subject + body) for every commit. Use these to:
|
|
190
|
+
- Spot intent — flag any conventional-commit `BREAKING CHANGE:` markers prominently.
|
|
191
|
+
- Group related file changes under a single narrative.
|
|
192
|
+
- Note "rationale unclear — check commit `<hash>` directly" for non-obvious diffs with terse messages.
|
|
193
|
+
|
|
194
|
+
If the compare endpoint is rate-limited, fall back to paged commits:
|
|
195
|
+
`https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits?sha=<TO>&since=<FROM-date>&until=<TO-date>`.
|
|
196
|
+
|
|
197
|
+
Include a "Changelog" list (short hash + first line) in the report.
|
|
198
|
+
|
|
199
|
+
### 5.2 Config files
|
|
200
|
+
|
|
201
|
+
These SDK config files may have changed and require corresponding updates in the project:
|
|
202
|
+
|
|
203
|
+
- `config/default.yaml` — main configuration defaults
|
|
204
|
+
- `config/_local.yaml` — template for the project's `config/_local.yaml` (CLI derives `config/local.yaml` from this
|
|
205
|
+
with `{{param}}` substitutions)
|
|
206
|
+
- `config/custom-environment-variables.yaml` — env var mappings
|
|
207
|
+
- `config/development.yaml`, `config/production.yaml` — env overrides
|
|
208
|
+
- `config/local.yaml` (SDK's own) — reference only, not shipped
|
|
209
|
+
|
|
210
|
+
For each, compare the SDK's version (`node_modules/fa-mcp-sdk/config/<file>`) with the project's version
|
|
211
|
+
(`config/<file>`). Identify: new keys, removed keys, changed defaults, new sections.
|
|
212
|
+
|
|
213
|
+
**Correlate `default.yaml` ⇄ `_local.yaml`.** When `default.yaml` has structural changes (new keys, restructured
|
|
214
|
+
sections, changed defaults), also check `_local.yaml` for analogous changes — `_local.yaml` mirrors `default.yaml`'s
|
|
215
|
+
structure with override values. If `default.yaml` changed but `_local.yaml` did NOT, flag this: the project's
|
|
216
|
+
`config/_local.yaml` may need manual updates to stay consistent.
|
|
217
|
+
|
|
218
|
+
**Config file mapping (SDK source → project destination):**
|
|
219
|
+
|
|
220
|
+
| SDK source (in `config/`) | Project destination | Action |
|
|
221
|
+
|--------------------------------------------|----------------------------------------------|--------|
|
|
222
|
+
| `config/default.yaml` | `config/default.yaml` | Add new keys; do NOT remove existing keys the project may have customized |
|
|
223
|
+
| `config/_local.yaml` | `config/_local.yaml` | Update to match SDK — this is the template `local.yaml` is derived from |
|
|
224
|
+
| `config/_local.yaml` (via CLI) | `config/local.yaml` | Derived by CLI from `_local.yaml` with `{{param}}` substitutions |
|
|
225
|
+
| `config/custom-environment-variables.yaml` | `config/custom-environment-variables.yaml` | Add new env var mappings |
|
|
226
|
+
| `config/local.yaml` (SDK's own) | *(not shipped — reference only)* | Use as reference for what the SDK itself overrides locally |
|
|
227
|
+
|
|
228
|
+
### 5.3 cli-template files
|
|
229
|
+
|
|
230
|
+
After `yarn add fa-mcp-sdk@<TO>`, the SDK ships its template at `node_modules/fa-mcp-sdk/cli-template/`. This is the
|
|
231
|
+
canonical source for any template files in the project.
|
|
232
|
+
|
|
233
|
+
| Template (source of truth) | Project (destination) | Notes |
|
|
234
|
+
|------------------------------------------------------------------|-------------------------------|-------|
|
|
235
|
+
| `node_modules/fa-mcp-sdk/cli-template/package.json` | `package.json` | **Merge carefully** — see rule below |
|
|
236
|
+
| `node_modules/fa-mcp-sdk/cli-template/tsconfig.json` | `tsconfig.json` | Overwrite unless customized |
|
|
237
|
+
| `node_modules/fa-mcp-sdk/cli-template/.oxlintrc.json` | `.oxlintrc.json` | Overwrite unless customized |
|
|
238
|
+
| `node_modules/fa-mcp-sdk/cli-template/.oxfmtrc.json` | `.oxfmtrc.json` | Overwrite unless customized |
|
|
239
|
+
| `node_modules/fa-mcp-sdk/cli-template/CLAUDE.md` | `CLAUDE.md` | Merge — project may add custom sections |
|
|
240
|
+
| `node_modules/fa-mcp-sdk/cli-template/jest.config.js` | `jest.config.js` | Overwrite unless customized |
|
|
241
|
+
| `node_modules/fa-mcp-sdk/cli-template/deploy/` | `deploy/` | Merge per file |
|
|
242
|
+
| `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/` | `.claude/skills/<skill>/` | Overwrite unless locally customized |
|
|
243
|
+
| `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml` | `.run/<name>.run.xml` | **Renamed** — see rule below |
|
|
244
|
+
| `node_modules/fa-mcp-sdk/cli-template/gitignore` | `.gitignore` | Source has no leading dot |
|
|
245
|
+
| `node_modules/fa-mcp-sdk/cli-template/FA-MCP-SDK-DOC/` | `FA-MCP-SDK-DOC/` | Auto-updated by `update-sdk.js` in Step 4 |
|
|
246
|
+
|
|
247
|
+
#### Rule: `package.json` — ADD ONLY new dependencies
|
|
248
|
+
|
|
249
|
+
The project's `package.json` has evolved since generation (project-specific name, version, scripts, team-added deps).
|
|
250
|
+
When the SDK's template `package.json` changes:
|
|
251
|
+
|
|
252
|
+
1. Diff `node_modules/fa-mcp-sdk/cli-template/package.json` (TO) against the same file at the FROM version.
|
|
253
|
+
2. Identify ONLY dependencies/devDependencies that were **added** (not version-changed, not removed).
|
|
254
|
+
3. Apply additions to the project's `package.json` under the matching section.
|
|
255
|
+
4. Do NOT touch `name`, `version`, `scripts`, `engines`, `type`, or any other field.
|
|
256
|
+
5. If a dep was **removed** from the template, mention it in the report as informational only — do not delete it from
|
|
257
|
+
the project (it may still be in use).
|
|
258
|
+
|
|
259
|
+
#### Rule: `r/` → `.run/` with filename transformation
|
|
260
|
+
|
|
261
|
+
The project has no `r/` directory — it was renamed to `.run/` at generation, and each `<name>.xml` was renamed to
|
|
262
|
+
`<name>.run.xml`. For new or changed files in `cli-template/r/`:
|
|
263
|
+
- Source: `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`
|
|
264
|
+
- Destination: `.run/<name>.run.xml`
|
|
265
|
+
- NEW file → copy with rename.
|
|
266
|
+
- CHANGED file → if the project's existing `.run.xml` is untouched (matches the FROM template), overwrite. If it has
|
|
267
|
+
local customizations, treat as Needs-Input (ask the user: overwrite / merge / skip).
|
|
268
|
+
- REMOVED file → informational only; do not delete the project's `.run/<name>.run.xml`.
|
|
269
|
+
|
|
270
|
+
#### Rule: `.claude/` files — use fcp.js
|
|
271
|
+
|
|
272
|
+
`.claude/**` is denied for direct `Write`/`Edit` in the project's `settings.json`. To update any file under
|
|
273
|
+
`.claude/` (skills, scripts, hooks, agents, settings.json) use the project's `scripts/fcp.js` workflow described in
|
|
274
|
+
the `edit-claude-files` skill — write the new content to a temp file, then
|
|
275
|
+
`node scripts/fcp.js .claude/<path> <temp-file>` to install it atomically. This applies to every cli-template
|
|
276
|
+
`.claude/` entry being copied into the project.
|
|
277
|
+
|
|
278
|
+
For any other changed template file: source path under `node_modules/fa-mcp-sdk/cli-template/...`, destination in the
|
|
279
|
+
project, action = overwrite or merge (depending on local customization).
|
|
280
|
+
|
|
281
|
+
### 5.4 Scripts
|
|
282
|
+
|
|
283
|
+
The CLI copies scripts from `node_modules/fa-mcp-sdk/scripts/` (NOT from `cli-template/scripts/`) into the project's
|
|
284
|
+
`scripts/`, then removes `copy-static.js`, `publish.js`, and `scripts/publish-README.md` (SDK-internal, not shipped).
|
|
285
|
+
|
|
286
|
+
- Canonical source: `node_modules/fa-mcp-sdk/scripts/<name>.js`
|
|
287
|
+
- Project destination: `scripts/<name>.js`
|
|
288
|
+
- Exclude: `copy-static.js`, `publish.js`, `publish-README.md`
|
|
289
|
+
|
|
290
|
+
### 5.5 Core library exports
|
|
291
|
+
|
|
292
|
+
**Prefer the TypeScript source over compiled output.** Fetch `src/core/index.ts` (and any re-exported `_types_/`
|
|
293
|
+
files it references) at both FROM and TO via GitHub raw:
|
|
294
|
+
```
|
|
295
|
+
https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<FROM-ref>/src/core/index.ts
|
|
296
|
+
https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<TO-ref>/src/core/index.ts
|
|
297
|
+
```
|
|
298
|
+
Compare to identify: new exports, removed/renamed exports, changed type signatures, type-level changes (generics,
|
|
299
|
+
conditional types, union narrowing) that don't survive `.d.ts` emission cleanly.
|
|
300
|
+
|
|
301
|
+
Why source over `dist/`:
|
|
302
|
+
- Original JSDoc comments and inline rationale preserved in `.ts`, stripped/compressed in `dist/*.js`.
|
|
303
|
+
- Renames visible as renames in source diff; in `dist/` they may appear as unrelated add+remove pairs.
|
|
304
|
+
- `export *` chains resolve naturally in source; in `.d.ts` they may be flattened.
|
|
305
|
+
|
|
306
|
+
**Fallback** — if GitHub raw is unavailable, use `node_modules/fa-mcp-sdk/dist/core/index.js` and the matching `.d.ts`.
|
|
307
|
+
State explicitly in the report that analysis was made from compiled artifacts and double-check via the GitHub source
|
|
308
|
+
viewer for any flagged change.
|
|
309
|
+
|
|
310
|
+
### 5.6 Project code scan
|
|
311
|
+
|
|
312
|
+
Scan the project's `src/`, `config/`, and `tests/` for:
|
|
313
|
+
- Imports from `fa-mcp-sdk` referencing removed/renamed exports
|
|
314
|
+
- Usage of deprecated APIs
|
|
315
|
+
- Config keys that were renamed or restructured
|
|
316
|
+
|
|
317
|
+
For each hit, capture file:line and the exact replacement plan — needed for Step 6 categorization.
|
|
318
|
+
|
|
319
|
+
## Step 6: Categorize and build the execution plan
|
|
320
|
+
|
|
321
|
+
For every change found in Step 5, assign one of three categories:
|
|
322
|
+
|
|
323
|
+
### Auto — LLM applies without asking
|
|
324
|
+
- `yarn add fa-mcp-sdk@<TO>` (already done in Step 4)
|
|
325
|
+
- `node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js` (already done in Step 4)
|
|
326
|
+
- Adding a brand-new config key to `config/default.yaml` when the project doesn't override it
|
|
327
|
+
- Adding new env var mappings to `config/custom-environment-variables.yaml`
|
|
328
|
+
- Adding a missing dependency to `package.json` under `dependencies`/`devDependencies`
|
|
329
|
+
- Copying a new template file the project doesn't have yet (scripts, `.run/` entries, new skill folders)
|
|
330
|
+
- Applying a mechanical rename of a renamed SDK export across the project's `src/` when there's exactly one
|
|
331
|
+
unambiguous replacement
|
|
332
|
+
- Updating SDK-shipped skill files via the `.claude/` fcp.js protocol when the project hasn't customized them
|
|
333
|
+
|
|
334
|
+
### Needs-Input — LLM applies, but needs user input
|
|
335
|
+
- A locally-customized file conflicts with the new template — ask: overwrite / merge / skip
|
|
336
|
+
- A new config key has no sensible default — ask for the value
|
|
337
|
+
- A breaking change has multiple plausible API replacements — ask which one fits the project's intent
|
|
338
|
+
- A `BREAKING CHANGE:` marker that the LLM can apply mechanically but wants explicit confirmation
|
|
339
|
+
- The project's `config/local.yaml` has stale overrides for keys that changed structure — ask whether to drop them,
|
|
340
|
+
port to the new structure, or leave them and warn
|
|
341
|
+
|
|
342
|
+
### Manual — LLM cannot perform
|
|
343
|
+
Reserve this only for things the LLM truly cannot do in this session. Examples:
|
|
344
|
+
- Rotating production secrets in a secrets manager outside this repo
|
|
345
|
+
- Deploying to staging/production environments
|
|
346
|
+
- Communicating with third-party services or teammates
|
|
347
|
+
|
|
348
|
+
**If a step could be automated in principle but requires human judgment, prefer Needs-Input over Manual.**
|
|
349
|
+
|
|
350
|
+
Build the plan as three lists with item counts and concrete actions.
|
|
351
|
+
|
|
352
|
+
## Step 7: Present the plan and ASK FOR CONFIRMATION
|
|
353
|
+
|
|
354
|
+
Render the plan in the conversation in the detected language:
|
|
355
|
+
|
|
356
|
+
```markdown
|
|
357
|
+
## Upgrade plan: fa-mcp-sdk v<FROM> → v<TO>
|
|
358
|
+
|
|
359
|
+
### 🤖 I will do automatically (N items)
|
|
360
|
+
1. ✅ yarn add fa-mcp-sdk@<TO> [already done]
|
|
361
|
+
2. ✅ node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js [already done]
|
|
362
|
+
3. Add new key `webServer.foo` (default `bar`) to `config/default.yaml`
|
|
363
|
+
4. Copy new template file `.run/new-task.run.xml` (renamed from `r/new-task.xml`)
|
|
364
|
+
5. Add dep `some-pkg@^1.2.3` to package.json `dependencies`
|
|
365
|
+
6. Apply rename `oldFn` → `newFn` in src/foo.ts:42, src/bar.ts:17, src/baz.ts:55
|
|
366
|
+
7. Run verification: `oxlint --fix . && oxfmt . && rimraf dist && tsc` + project tests + clean startup
|
|
367
|
+
|
|
368
|
+
### ❓ I need your input on (M items)
|
|
369
|
+
1. `config/local.yaml` overrides `webServer.auth` which restructured in v<TO>. Options:
|
|
370
|
+
(a) port overrides to new structure (b) drop overrides (c) leave + warn
|
|
371
|
+
2. New config key `someService.apiKey` has no default. What value should I set?
|
|
372
|
+
3. Project's `.claude/skills/upgrade-sdk/SKILL.md` is locally customized. Overwrite with new template,
|
|
373
|
+
merge non-conflicting parts only, or skip?
|
|
374
|
+
|
|
375
|
+
### 👋 You'll need to do manually (K items)
|
|
376
|
+
- [empty if everything is in Auto or Needs-Input]
|
|
377
|
+
|
|
378
|
+
### Rollback info
|
|
379
|
+
- Pre-upgrade commit: <hash>
|
|
380
|
+
- Prior SDK version: v<FROM>
|
|
381
|
+
- Branch: <branch>
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
Then ask **explicitly**:
|
|
385
|
+
|
|
386
|
+
> "Confirm — apply the Auto items now and prompt you inline for the Needs-Input items as I reach them? (yes/no)"
|
|
387
|
+
|
|
388
|
+
Wait for explicit confirmation. If the user declines, stop and leave the project as it is after Step 4 (note this in
|
|
389
|
+
the final report). If the user confirms, proceed to Step 8.
|
|
390
|
+
|
|
391
|
+
## Step 8: Execute
|
|
392
|
+
|
|
393
|
+
Apply each Auto item in order. For each Needs-Input item, ask the user **at the moment you reach it** (one question
|
|
394
|
+
at a time so the user can reason — don't batch). Apply with the answer, then move on.
|
|
395
|
+
|
|
396
|
+
Be transparent about state — after each item is applied, output a one-line acknowledgment so the user can follow
|
|
397
|
+
along, e.g. `✓ Added webServer.foo to config/default.yaml`.
|
|
398
|
+
|
|
399
|
+
When touching files under `.claude/`, always use the project's `scripts/fcp.js` workflow (see Step 5.3 → "Rule:
|
|
400
|
+
`.claude/` files — use fcp.js" and the project's `edit-claude-files` skill).
|
|
401
|
+
|
|
402
|
+
Maintain an in-memory execution log so the final report can list exactly what was done and what required input.
|
|
403
|
+
|
|
404
|
+
## Step 9: Verify
|
|
405
|
+
|
|
406
|
+
After all items are applied, run the verification chain in this exact order. Record pass/fail for each step.
|
|
407
|
+
|
|
408
|
+
### 9.1 Lint + format + clean build (fixed chain)
|
|
409
|
+
|
|
410
|
+
Run this single command chain — same shape regardless of project:
|
|
411
|
+
|
|
412
|
+
```bash
|
|
413
|
+
npx oxlint --fix . && npx oxfmt . && npx rimraf dist && npx tsc
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
(Use `npx` to invoke the tools directly so the chain doesn't depend on yarn script wrappers, which may differ between
|
|
417
|
+
projects. If the project clearly pins these tools as direct `node_modules/.bin/` binaries, those work too.)
|
|
418
|
+
|
|
419
|
+
- `oxlint --fix .` — auto-fix lint issues across the whole project
|
|
420
|
+
- `oxfmt .` — format the whole project
|
|
421
|
+
- `rimraf dist` — wipe stale build output
|
|
422
|
+
- `tsc` — typecheck + compile
|
|
423
|
+
|
|
424
|
+
If any step fails, stop the chain and trigger the failure-handling flow below.
|
|
425
|
+
|
|
426
|
+
### 9.2 Project tests (whatever is wired in `package.json`)
|
|
427
|
+
|
|
428
|
+
**Do not hard-code a test command.** Read the project's `package.json` `scripts` section and run whatever test scripts
|
|
429
|
+
the project actually defines. Common patterns to look for, in order of preference:
|
|
430
|
+
|
|
431
|
+
1. `test:mcp`, `test:mcp-http`, `test:mcp-sse`, `test:mcp-streamable` — MCP transport tests (run all that exist)
|
|
432
|
+
2. `test` — top-level test runner (usually `jest`)
|
|
433
|
+
3. Any other script whose name starts with `test:` or contains `test`
|
|
434
|
+
|
|
435
|
+
Run all relevant test scripts; the project may need just one of them or several. Record pass/fail per script.
|
|
436
|
+
|
|
437
|
+
If no test scripts are defined, note it in the report ("project has no test scripts — verification skipped tests").
|
|
438
|
+
|
|
439
|
+
### 9.3 Clean startup
|
|
440
|
+
|
|
441
|
+
Briefly start the server, confirm it boots without errors, then stop it:
|
|
442
|
+
|
|
443
|
+
```bash
|
|
444
|
+
yarn start & # or `npm start` — match the project
|
|
445
|
+
# wait ~3-5s for startup logs
|
|
446
|
+
node scripts/kill-port.js <port> # port from config/default.yaml → webServer.port
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
A "clean startup" means: no exceptions in logs, server reports it's listening on the configured port. If startup
|
|
450
|
+
fails, treat it as a verification failure.
|
|
451
|
+
|
|
452
|
+
### On verification failure
|
|
453
|
+
|
|
454
|
+
Do NOT silently proceed and do NOT silently roll back. Present the failing step, the error output, and the diff of
|
|
455
|
+
the likely-causing file(s), then ask the user to choose:
|
|
456
|
+
|
|
457
|
+
> "Verification failed at <step>. Options:
|
|
458
|
+
> - **fix**: I diagnose the root cause and fix it (may need more input from you)
|
|
459
|
+
> - **retry**: just rerun the verification step (useful for flaky tests)
|
|
460
|
+
> - **rollback**: revert to the pre-upgrade state (commit `<hash>`, SDK v`<FROM>`) and stop
|
|
461
|
+
> - **leave-as-is**: keep current state, surface the failure in the final report, and stop
|
|
462
|
+
> Pick one."
|
|
463
|
+
|
|
464
|
+
Apply the user's choice:
|
|
465
|
+
- **fix** → diagnose, apply a fix (asking inline for any info needed), re-run verification. Loop if it fails again.
|
|
466
|
+
- **retry** → rerun the failing step once. If it fails again, present the same four options.
|
|
467
|
+
- **rollback** → run `yarn add fa-mcp-sdk@<FROM>` (or git-URL form), `git checkout <pre-upgrade-hash> -- .`,
|
|
468
|
+
`node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js` if needed. If the user stashed changes in Step 3, restore
|
|
469
|
+
them with `git stash pop`. Report what was rolled back.
|
|
470
|
+
- **leave-as-is** → no further changes. Final report will clearly mark the failure and what remains unverified.
|
|
471
|
+
|
|
472
|
+
## Step 10: Report
|
|
473
|
+
|
|
474
|
+
Produce a final report in **two places**:
|
|
475
|
+
1. **In the chat**, immediately at the end of the skill run.
|
|
476
|
+
2. **In a file** at `claudedocs/upgrade-sdk-<FROM>-to-<TO>.md` (overwrite if it exists from a previous run).
|
|
477
|
+
|
|
478
|
+
Both copies use this structure (in the detected language):
|
|
479
|
+
|
|
480
|
+
```markdown
|
|
481
|
+
# Upgrade report: fa-mcp-sdk v<FROM> → v<TO>
|
|
482
|
+
|
|
483
|
+
Generated: <ISO timestamp>
|
|
484
|
+
Branch: <branch>
|
|
485
|
+
Pre-upgrade commit: <hash>
|
|
486
|
+
|
|
487
|
+
## Outcome
|
|
488
|
+
|
|
489
|
+
<one of: ✅ completed | ⚠️ completed with issues | ❌ rolled back | ⏸ stopped at user request>
|
|
490
|
+
|
|
491
|
+
## Changelog (commits between FROM and TO)
|
|
492
|
+
|
|
493
|
+
- `<short-hash>` <first line>
|
|
494
|
+
- ...
|
|
495
|
+
|
|
496
|
+
## ✓ Done automatically
|
|
497
|
+
|
|
498
|
+
- Item 1
|
|
499
|
+
- Item 2
|
|
500
|
+
- ...
|
|
501
|
+
|
|
502
|
+
## ✓ Done with your input
|
|
503
|
+
|
|
504
|
+
- `config/local.yaml`: chose (a) port to new structure — applied N keys
|
|
505
|
+
- `someService.apiKey`: set to `<value-you-provided>`
|
|
506
|
+
- `oldFn` → `newFn` rename: applied to src/foo.ts:42, src/bar.ts:17, src/baz.ts:55
|
|
507
|
+
- ...
|
|
508
|
+
|
|
509
|
+
## 👋 Still on your plate
|
|
510
|
+
|
|
511
|
+
- [empty if nothing manual remains]
|
|
512
|
+
|
|
513
|
+
## Verification
|
|
514
|
+
|
|
515
|
+
- `oxlint --fix .`: ✅ / ❌ (<error excerpt>)
|
|
516
|
+
- `oxfmt .`: ✅ / ❌
|
|
517
|
+
- `rimraf dist`: ✅ / ❌
|
|
518
|
+
- `tsc`: ✅ / ❌ (<error excerpt>)
|
|
519
|
+
- tests (<list scripts run>): ✅ / ❌ (<n>/<m> passed)
|
|
520
|
+
- clean startup: ✅ / ❌
|
|
521
|
+
|
|
522
|
+
## Rollback info
|
|
523
|
+
|
|
524
|
+
- Pre-upgrade commit: `<hash>`
|
|
525
|
+
- Prior SDK version: `v<FROM>`
|
|
526
|
+
- To roll back manually:
|
|
527
|
+
```bash
|
|
528
|
+
yarn add fa-mcp-sdk@<FROM>
|
|
529
|
+
git checkout <hash> -- .
|
|
530
|
+
node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
## Notes
|
|
534
|
+
|
|
535
|
+
<anything noteworthy: rate limits hit, fallbacks used, files with rationale-unclear diffs flagged for review, etc.>
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
Make sure `claudedocs/` exists (`mkdir -p claudedocs`) before writing.
|
|
539
|
+
|
|
540
|
+
## Important rules
|
|
541
|
+
|
|
542
|
+
- Always read actual files; never guess what changed.
|
|
543
|
+
- Treat user customizations as inviolable unless the user explicitly says "overwrite" in response to a Needs-Input
|
|
544
|
+
prompt.
|
|
545
|
+
- Never modify `package.json` other than to ADD new deps; do not change `name`, `version`, `scripts`, `engines`,
|
|
546
|
+
`type`, or any other field.
|
|
547
|
+
- Don't skip verification. If it fails, surface it via the 4-option prompt — don't smuggle failures past the user.
|
|
548
|
+
- All `.claude/` writes go through `scripts/fcp.js` (per the `edit-claude-files` protocol).
|
|
549
|
+
- Write all human-readable text in the detected language (default: English). Keep paths, YAML keys, and shell
|
|
550
|
+
commands in English regardless.
|
|
551
|
+
- Correlate config files: when `default.yaml` changes, always check `_local.yaml` for analogous changes and flag
|
|
552
|
+
stale `local.yaml` overrides explicitly.
|
|
553
|
+
- If GitHub API is unavailable or rate-limited, fall back to comparing files directly from `node_modules/fa-mcp-sdk/`
|
|
554
|
+
against project files, and note the fallback in the report.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fa-mcp-sdk",
|
|
3
3
|
"productName": "FA MCP SDK",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.96",
|
|
5
5
|
"description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "dist/core/index.js",
|
package/scripts/update-sdk.js
CHANGED
|
@@ -131,3 +131,19 @@ for (const { name, src, dest, preserve = [], respectPin = false } of targets) {
|
|
|
131
131
|
console.log(`${name} updated`);
|
|
132
132
|
}
|
|
133
133
|
}
|
|
134
|
+
|
|
135
|
+
const scriptsSrcDir = join(cwd, './node_modules/fa-mcp-sdk/scripts');
|
|
136
|
+
const scriptsDestDir = join(cwd, 'scripts');
|
|
137
|
+
const individualScripts = ['generate-jwt.js'];
|
|
138
|
+
|
|
139
|
+
for (const file of individualScripts) {
|
|
140
|
+
const src = join(scriptsSrcDir, file);
|
|
141
|
+
const dest = join(scriptsDestDir, file);
|
|
142
|
+
if (!existsSync(src)) {
|
|
143
|
+
console.error('Source not found:', src);
|
|
144
|
+
process.exit(1);
|
|
145
|
+
}
|
|
146
|
+
mkdirSync(dirname(dest), { recursive: true });
|
|
147
|
+
cpSync(src, dest);
|
|
148
|
+
console.log(`scripts/${file} updated`);
|
|
149
|
+
}
|
|
@@ -1,456 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: upgrade-guide
|
|
3
|
-
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."
|
|
4
|
-
disable-model-invocation: true
|
|
5
|
-
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
|
|
6
|
-
argument-hint: "[from-version] [to-version] [language hint]"
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# FA-MCP-SDK Upgrade Guide Generator
|
|
10
|
-
|
|
11
|
-
Generate a comprehensive migration guide for upgrading the fa-mcp-sdk dependency in the current project.
|
|
12
|
-
|
|
13
|
-
## Overview
|
|
14
|
-
|
|
15
|
-
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.
|
|
16
|
-
|
|
17
|
-
## Argument Parsing
|
|
18
|
-
|
|
19
|
-
Parse `$ARGUMENTS` to extract a target version and an optional language hint.
|
|
20
|
-
|
|
21
|
-
### Language detection
|
|
22
|
-
|
|
23
|
-
Look for a natural-language phrase anywhere in the arguments that indicates the desired output language. Examples:
|
|
24
|
-
- "на русском", "по-русски", "in Russian", "ru" → Russian
|
|
25
|
-
- "in English", "en" → English
|
|
26
|
-
- Any similar phrase or ISO 639-1 code
|
|
27
|
-
|
|
28
|
-
Remove the language hint from the arguments before parsing the target version.
|
|
29
|
-
|
|
30
|
-
**Default: English** if no language hint is found.
|
|
31
|
-
|
|
32
|
-
The detected language determines ALL human-readable text in the generated guide (headings, descriptions, recommendations).
|
|
33
|
-
Technical content (file paths, YAML keys, code snippets, commands) stays as-is regardless of language.
|
|
34
|
-
|
|
35
|
-
### Version/commit references
|
|
36
|
-
|
|
37
|
-
After stripping the language hint, the remaining arguments are version or commit references.
|
|
38
|
-
|
|
39
|
-
An argument is a **commit hash** if it contains 7+ hex characters and does not match semver pattern.
|
|
40
|
-
Otherwise it is treated as a **version** (with or without `v` prefix — `0.4.30` and `v0.4.30` are equivalent).
|
|
41
|
-
|
|
42
|
-
#### Scope of references: PROJECT (default) vs SDK
|
|
43
|
-
|
|
44
|
-
**By default, all versions and commit hashes refer to THIS project** (the repository where the skill is invoked), NOT to fa-mcp-sdk.
|
|
45
|
-
|
|
46
|
-
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):
|
|
47
|
-
- "sdk", "fa-mcp-sdk", "of sdk", "sdk commit", "sdk version"
|
|
48
|
-
- "sdk", "fa-mcp-sdk", "версия sdk", "комит sdk", "коммит sdk", "хеш sdk"
|
|
49
|
-
|
|
50
|
-
Examples:
|
|
51
|
-
- `/upgrade-guide 1.2.3 1.2.7` → project versions (look up which SDK version was used in each)
|
|
52
|
-
- `/upgrade-guide от версии 0.2.3 SDK до 0.4.5 SDK` → SDK versions directly
|
|
53
|
-
- `/upgrade-guide от комита sdk abc1234 до комита sdk def5678` → SDK commits directly
|
|
54
|
-
- `/upgrade-guide abc1234 def5678` → project commits (look up which SDK version was pinned in each)
|
|
55
|
-
|
|
56
|
-
#### Resolving PROJECT references to SDK versions
|
|
57
|
-
|
|
58
|
-
When a reference is PROJECT-scoped (the default), resolve it to an SDK version/commit before computing the diff:
|
|
59
|
-
|
|
60
|
-
1. **Project commit hash** — run `git show <hash>:package.json` and extract the `fa-mcp-sdk` dependency value.
|
|
61
|
-
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.
|
|
62
|
-
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.
|
|
63
|
-
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.
|
|
64
|
-
5. If the project tag/commit cannot be found, report an error and stop.
|
|
65
|
-
|
|
66
|
-
Show the user the resolution result before proceeding:
|
|
67
|
-
```
|
|
68
|
-
Resolved project references to SDK:
|
|
69
|
-
FROM: project <ref> → SDK <version-or-commit>
|
|
70
|
-
TO: project <ref> → SDK <version-or-commit>
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
#### Argument count
|
|
74
|
-
|
|
75
|
-
**Two arguments** — explicit FROM and TO (resolved per scope rules above).
|
|
76
|
-
|
|
77
|
-
**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.
|
|
78
|
-
|
|
79
|
-
**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).
|
|
80
|
-
|
|
81
|
-
**No arguments** — FROM is the current installed SDK version (from the project's current `package.json`); TO is the latest published SDK version.
|
|
82
|
-
|
|
83
|
-
## Step 1: Determine SDK Versions
|
|
84
|
-
|
|
85
|
-
1. Read the current project's `package.json` and extract the installed `fa-mcp-sdk` version — this is the **default FROM (SDK)**.
|
|
86
|
-
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)**.
|
|
87
|
-
3. Apply argument parsing rules above (scope, count) to determine FROM and TO.
|
|
88
|
-
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").
|
|
89
|
-
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:
|
|
90
|
-
- If it's a **version** (e.g. `0.4.30` / `v0.4.30`) — probe the GitHub tag endpoint:
|
|
91
|
-
`https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/git/refs/tags/v<version>` (also try without
|
|
92
|
-
the `v` prefix). Fall back to `yarn info fa-mcp-sdk@<version> version` — if that also fails,
|
|
93
|
-
report `Cannot resolve SDK version <X>: not found on GitHub or npm` and stop.
|
|
94
|
-
- If it's a **commit hash** — probe `https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/<hash>`.
|
|
95
|
-
If it returns 404, report `Cannot resolve SDK commit <hash>: not found in repo` and stop.
|
|
96
|
-
- If GitHub API is rate-limited, fall back to `git ls-remote https://github.com/Bazilio-san/fa-mcp-sdk.git`
|
|
97
|
-
for tag/branch existence, and skip commit-hash validation with a warning.
|
|
98
|
-
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.
|
|
99
|
-
|
|
100
|
-
Display to the user:
|
|
101
|
-
```
|
|
102
|
-
From: <project or SDK ref> → SDK <version-or-commit> ✓ validated
|
|
103
|
-
To: <project or SDK ref> → SDK <version-or-commit> ✓ validated
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
## Step 2: Upgrade the Dependency
|
|
107
|
-
|
|
108
|
-
If TO is a published version (not a commit hash), run:
|
|
109
|
-
```bash
|
|
110
|
-
yarn add fa-mcp-sdk@<TO-version>
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
If TO is a commit hash, run:
|
|
114
|
-
```bash
|
|
115
|
-
yarn add fa-mcp-sdk@https://github.com/Bazilio-san/fa-mcp-sdk#<TO-commit>
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
Wait for completion. If it fails, report the error and stop.
|
|
119
|
-
|
|
120
|
-
## Step 3: Update SDK Documentation
|
|
121
|
-
|
|
122
|
-
Run:
|
|
123
|
-
```bash
|
|
124
|
-
node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
This copies the latest `FA-MCP-SDK-DOC/` and `.claude/` from the SDK into the project.
|
|
128
|
-
|
|
129
|
-
**Pinned folders.** Any folder under the project's `.claude/` that contains a direct file named
|
|
130
|
-
`pin` is preserved as-is — the script neither deletes it nor overwrites it with template content.
|
|
131
|
-
Drop a `pin` file into `.claude/skills/<your-skill>/` (or any other `.claude/` subdirectory) to
|
|
132
|
-
protect local customizations from being reset on upgrade.
|
|
133
|
-
|
|
134
|
-
## Step 4: Analyze Changes in SDK Between Versions
|
|
135
|
-
|
|
136
|
-
Use the public GitHub repository `https://github.com/Bazilio-san/fa-mcp-sdk` to analyze what changed.
|
|
137
|
-
|
|
138
|
-
### 4.1 Get the commit log between versions
|
|
139
|
-
|
|
140
|
-
Fetch the GitHub compare URL to understand what changed:
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/compare/<FROM-ref>...<TO-ref>
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
Where `<FROM-ref>` and `<TO-ref>` are version tags (try both `v0.4.30` and `0.4.30` formats) or commit hashes.
|
|
147
|
-
|
|
148
|
-
If version tags don't exist, use the commits API to find commits between versions, or search `git log` for version bump commit messages.
|
|
149
|
-
|
|
150
|
-
Alternative approach — use the npm registry to get git metadata, or simply read the changelog if available.
|
|
151
|
-
|
|
152
|
-
**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:
|
|
153
|
-
- Spot intent (e.g. "fix: ...", "BREAKING CHANGE: ...", "refactor: ...") — flag any conventional-commit BREAKING markers prominently in the Breaking Changes section.
|
|
154
|
-
- Group related file changes under a single narrative ("These three files changed because of <reason from commit>").
|
|
155
|
-
- 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".
|
|
156
|
-
|
|
157
|
-
If the compare API is rate-limited, fall back to fetching commits one page at a time via
|
|
158
|
-
`https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits?sha=<TO>&until=<TO-date>&since=<FROM-date>`.
|
|
159
|
-
|
|
160
|
-
### 4.2 Analyze changes in config files
|
|
161
|
-
|
|
162
|
-
These config files in the SDK may have changed and require corresponding updates in the project:
|
|
163
|
-
|
|
164
|
-
- `config/default.yaml` — main configuration defaults
|
|
165
|
-
- `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)
|
|
166
|
-
- `config/custom-environment-variables.yaml` — env var mappings
|
|
167
|
-
- `config/development.yaml` — dev overrides
|
|
168
|
-
- `config/production.yaml` — production overrides
|
|
169
|
-
- `config/local.yaml` (SDK's own) — reference only, not shipped to projects
|
|
170
|
-
|
|
171
|
-
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>`).
|
|
172
|
-
|
|
173
|
-
Identify:
|
|
174
|
-
- **New keys** added in the SDK that are missing in the project
|
|
175
|
-
- **Removed keys** that existed in the old SDK but are gone now
|
|
176
|
-
- **Changed defaults** where the SDK's default value has changed
|
|
177
|
-
- **New sections** that represent new features
|
|
178
|
-
|
|
179
|
-
**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`.
|
|
180
|
-
|
|
181
|
-
Compare both files in the SDK's `node_modules/fa-mcp-sdk/config/`:
|
|
182
|
-
- `node_modules/fa-mcp-sdk/config/default.yaml` — the canonical defaults
|
|
183
|
-
- `node_modules/fa-mcp-sdk/config/_local.yaml` — the template that was used to generate the project's `config/local.yaml`
|
|
184
|
-
|
|
185
|
-
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.
|
|
186
|
-
|
|
187
|
-
**Config file mapping (SDK source → project destination):**
|
|
188
|
-
|
|
189
|
-
| SDK source (in `config/`) | Project destination | Action |
|
|
190
|
-
|--------------------------------------|---------------------------------|--------|
|
|
191
|
-
| `config/default.yaml` | `config/default.yaml` | Add new keys; do NOT remove existing keys the project may have customized |
|
|
192
|
-
| `config/_local.yaml` | `config/_local.yaml` | Update to match SDK — this is the template users derive their `local.yaml` from |
|
|
193
|
-
| `config/_local.yaml` (via CLI) | `config/local.yaml` | Derived by CLI from `_local.yaml` with `{{param}}` substitutions — check for needed adjustments |
|
|
194
|
-
| `config/custom-environment-variables.yaml` | `config/custom-environment-variables.yaml` | Add new env var mappings |
|
|
195
|
-
| `config/local.yaml` (SDK's own) | *(not shipped — reference only)* | Use as reference for what the SDK itself overrides locally |
|
|
196
|
-
|
|
197
|
-
### 4.3 Analyze changes in cli-template files
|
|
198
|
-
|
|
199
|
-
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.
|
|
200
|
-
|
|
201
|
-
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):
|
|
202
|
-
|
|
203
|
-
| Template (source of truth) | Project (destination) | Notes |
|
|
204
|
-
|-------------------------------------------------------------------|---------------------------------------------|-------|
|
|
205
|
-
| `node_modules/fa-mcp-sdk/cli-template/package.json` | `package.json` | **Merge carefully** — see rule below |
|
|
206
|
-
| `node_modules/fa-mcp-sdk/cli-template/tsconfig.json` | `tsconfig.json` | overwrite (unless customized) |
|
|
207
|
-
| `node_modules/fa-mcp-sdk/cli-template/.oxlintrc.json` | `.oxlintrc.json` | overwrite (unless customized) |
|
|
208
|
-
| `node_modules/fa-mcp-sdk/cli-template/.oxfmtrc.json` | `.oxfmtrc.json` | overwrite (unless customized) |
|
|
209
|
-
| `node_modules/fa-mcp-sdk/cli-template/CLAUDE.md` | `CLAUDE.md` | merge — project may add custom sections |
|
|
210
|
-
| `node_modules/fa-mcp-sdk/cli-template/jest.config.js` | `jest.config.js` | overwrite (unless customized) |
|
|
211
|
-
| `node_modules/fa-mcp-sdk/cli-template/deploy/` | `deploy/` | merge per file |
|
|
212
|
-
| `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/` | `.claude/skills/<skill>/` | overwrite unless locally customized |
|
|
213
|
-
| `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml` | `.run/<name>.run.xml` | **Renamed** — see rule below |
|
|
214
|
-
| `node_modules/fa-mcp-sdk/cli-template/gitignore` | `.gitignore` | source has no leading dot |
|
|
215
|
-
| `node_modules/fa-mcp-sdk/cli-template/FA-MCP-SDK-DOC/` | `FA-MCP-SDK-DOC/` | auto-updated by `update-sdk.js` |
|
|
216
|
-
|
|
217
|
-
#### Rule: package.json — ADD ONLY new dependencies, do NOT touch anything else
|
|
218
|
-
|
|
219
|
-
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:
|
|
220
|
-
|
|
221
|
-
1. Diff `node_modules/fa-mcp-sdk/cli-template/package.json` (TO) against the same file at the FROM version.
|
|
222
|
-
2. Identify ONLY dependencies/devDependencies that were **added** (not changed versions of existing ones, not removed).
|
|
223
|
-
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."
|
|
224
|
-
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).
|
|
225
|
-
5. Do NOT suggest overwriting `scripts`, `engines`, `type`, or any other field.
|
|
226
|
-
|
|
227
|
-
Provide a copy-pasteable JSON snippet with only the new keys:
|
|
228
|
-
```json
|
|
229
|
-
{
|
|
230
|
-
"dependencies": {
|
|
231
|
-
"<new-dep>": "<version>"
|
|
232
|
-
}
|
|
233
|
-
}
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
#### Rule: `r/` → `.run/` with filename transformation
|
|
237
|
-
|
|
238
|
-
The project has no `r/` directory — it was renamed to `.run/` at project generation, and each `<name>.xml` inside was
|
|
239
|
-
renamed to `<name>.run.xml`. When the SDK template ships new or changed files in `cli-template/r/`:
|
|
240
|
-
|
|
241
|
-
- Source: `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`
|
|
242
|
-
- Destination: `.run/<name>.run.xml`
|
|
243
|
-
- Action for NEW files: copy `<name>.xml` → `.run/<name>.run.xml`
|
|
244
|
-
- Action for CHANGED files: copy with the same rename, overwriting the existing `.run.xml` file (warn the user to back up any customizations)
|
|
245
|
-
- Action for REMOVED files: informational only — do not delete the project's `.run/<name>.run.xml` automatically
|
|
246
|
-
|
|
247
|
-
The generated guide must show the exact source → destination mapping for each changed file, with the filename transformation applied.
|
|
248
|
-
|
|
249
|
-
#### Rule: `.claude/skills/<skill>/SKILL.md`
|
|
250
|
-
|
|
251
|
-
This is a Claude Code skill that the project owns a copy of. If the SDK ships an updated version, instruct the user to
|
|
252
|
-
overwrite their local copy from `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/SKILL.md` — unless they've
|
|
253
|
-
customized it locally, in which case manual merge.
|
|
254
|
-
|
|
255
|
-
For any other changed template file, the generated guide must include:
|
|
256
|
-
- The exact source path under `node_modules/fa-mcp-sdk/cli-template/...`
|
|
257
|
-
- The exact destination path in the project
|
|
258
|
-
- Whether to **overwrite** or **merge carefully** (because the project may have local customizations)
|
|
259
|
-
|
|
260
|
-
### 4.4 Analyze changes in scripts
|
|
261
|
-
|
|
262
|
-
The CLI copies scripts from `node_modules/fa-mcp-sdk/scripts/` (NOT from `cli-template/scripts/`) into the project's
|
|
263
|
-
`scripts/` directory, and then removes `copy-static.js`, `publish.js`, `scripts/publish-README.md` (SDK-internal, not needed in downstream projects).
|
|
264
|
-
|
|
265
|
-
- Canonical source: `node_modules/fa-mcp-sdk/scripts/<name>.js`
|
|
266
|
-
- Project destination: `scripts/<name>.js`
|
|
267
|
-
- Exclude from upgrade suggestions: `copy-static.js`, `publish.js`, `scripts/publish-README.md` (SDK-only)
|
|
268
|
-
|
|
269
|
-
The generated guide must specify the exact source path under `node_modules/fa-mcp-sdk/scripts/...` for any script the
|
|
270
|
-
user should copy into their project's `scripts/` directory, and skip the excluded SDK-only scripts.
|
|
271
|
-
|
|
272
|
-
### 4.5 Analyze changes in core library exports
|
|
273
|
-
|
|
274
|
-
**Prefer the TypeScript source over the compiled output.** Fetch `src/core/index.ts` (and any
|
|
275
|
-
re-exported `_types_/` files it references) at both FROM and TO via GitHub raw:
|
|
276
|
-
|
|
277
|
-
```
|
|
278
|
-
https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<FROM-ref>/src/core/index.ts
|
|
279
|
-
https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<TO-ref>/src/core/index.ts
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
Compare them to identify:
|
|
283
|
-
- New exports that may be useful
|
|
284
|
-
- Removed/renamed exports that may break existing code
|
|
285
|
-
- Changed type signatures
|
|
286
|
-
- Type-level changes (generics, conditional types, union narrowing) that don't survive `.d.ts`
|
|
287
|
-
emission cleanly
|
|
288
|
-
|
|
289
|
-
Why source over `dist/`:
|
|
290
|
-
- Original JSDoc comments and inline rationale are preserved in `.ts` but stripped/compressed in `dist/*.js`.
|
|
291
|
-
- Renames are visible as renames in the source diff; in `dist/` they may appear as unrelated
|
|
292
|
-
add+remove pairs because of import-order shuffling or minification.
|
|
293
|
-
- TS `export *` chains resolve naturally in source; in `.d.ts` they may be flattened, hiding which
|
|
294
|
-
module a symbol came from originally.
|
|
295
|
-
|
|
296
|
-
**Fallback** — if GitHub raw is unavailable (rate-limited, network blocked), use
|
|
297
|
-
`node_modules/fa-mcp-sdk/dist/core/index.js` and the matching `.d.ts`. State explicitly in the
|
|
298
|
-
generated guide that the analysis was made from the compiled artifacts and recommend that the user
|
|
299
|
-
double-check via the GitHub source viewer for any flagged change.
|
|
300
|
-
|
|
301
|
-
### 4.6 Check project code for breaking changes
|
|
302
|
-
|
|
303
|
-
Scan the project's `src/` directory for:
|
|
304
|
-
- Imports from `fa-mcp-sdk` that reference removed/renamed exports
|
|
305
|
-
- Usage of deprecated APIs
|
|
306
|
-
- Config keys that have been renamed or restructured
|
|
307
|
-
|
|
308
|
-
## Step 5: Generate Migration Guide
|
|
309
|
-
|
|
310
|
-
Write ALL headings, descriptions, and prose in the detected language (default: English).
|
|
311
|
-
Technical content (file paths, YAML keys, code blocks, shell commands) is always in English.
|
|
312
|
-
|
|
313
|
-
Create a file `upgrade-guide-<old>-to-<new>.md` in the project root with the following structure:
|
|
314
|
-
|
|
315
|
-
```markdown
|
|
316
|
-
# FA-MCP-SDK Migration Guide: v<old> -> v<new>
|
|
317
|
-
|
|
318
|
-
Generated: <timestamp>
|
|
319
|
-
|
|
320
|
-
## Summary
|
|
321
|
-
|
|
322
|
-
<Brief overview of what changed and the scope of required updates>
|
|
323
|
-
|
|
324
|
-
## Breaking Changes
|
|
325
|
-
|
|
326
|
-
<List any breaking changes that MUST be addressed. For each:>
|
|
327
|
-
- What changed
|
|
328
|
-
- What code/config is affected
|
|
329
|
-
- Exact fix with code snippets
|
|
330
|
-
|
|
331
|
-
## Config Changes
|
|
332
|
-
|
|
333
|
-
### New Configuration Keys
|
|
334
|
-
|
|
335
|
-
<For each new key, provide:>
|
|
336
|
-
- Key path (e.g., `webServer.auth.enabled`)
|
|
337
|
-
- Default value
|
|
338
|
-
- Description
|
|
339
|
-
- Whether it needs to be added to the project's config
|
|
340
|
-
|
|
341
|
-
### Changed Defaults
|
|
342
|
-
|
|
343
|
-
<Keys where default values changed>
|
|
344
|
-
|
|
345
|
-
### Removed Keys
|
|
346
|
-
|
|
347
|
-
<Keys that were removed>
|
|
348
|
-
|
|
349
|
-
### Recommended config/default.yaml additions
|
|
350
|
-
|
|
351
|
-
```yaml
|
|
352
|
-
# Add these sections to your config/default.yaml:
|
|
353
|
-
<actual YAML snippets to add>
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
### config/_local.yaml
|
|
357
|
-
|
|
358
|
-
<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.>
|
|
359
|
-
|
|
360
|
-
### config/local.yaml (project-local overrides)
|
|
361
|
-
|
|
362
|
-
<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.>
|
|
363
|
-
|
|
364
|
-
### Recommended config/custom-environment-variables.yaml additions
|
|
365
|
-
|
|
366
|
-
```yaml
|
|
367
|
-
# Add these mappings:
|
|
368
|
-
<actual YAML snippets>
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
## Template File Changes
|
|
372
|
-
|
|
373
|
-
> **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.
|
|
374
|
-
|
|
375
|
-
### package.json
|
|
376
|
-
|
|
377
|
-
> **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`.
|
|
378
|
-
|
|
379
|
-
<List only dependencies/devDependencies that were newly added in the SDK template. Provide a copy-pasteable JSON snippet
|
|
380
|
-
with only the new keys. Mention removed deps as informational only — do not instruct deletion.>
|
|
381
|
-
|
|
382
|
-
### `.run/` (from `cli-template/r/`)
|
|
383
|
-
|
|
384
|
-
<For each changed `cli-template/r/<name>.xml`, show the mapping:>
|
|
385
|
-
- Source: `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`
|
|
386
|
-
- Destination: `.run/<name>.run.xml` (note the rename)
|
|
387
|
-
- Action: copy + rename (overwrite, warn about local customizations)
|
|
388
|
-
|
|
389
|
-
### Claude Code Skills (`.claude/skills/`)
|
|
390
|
-
|
|
391
|
-
<For each updated skill, e.g. `upgrade-guide`:>
|
|
392
|
-
- Source: `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill-name>/SKILL.md`
|
|
393
|
-
- Destination: `.claude/skills/<skill-name>/SKILL.md`
|
|
394
|
-
- Action: overwrite (unless locally customized — then manual merge)
|
|
395
|
-
|
|
396
|
-
### Other Template Files
|
|
397
|
-
|
|
398
|
-
<For each: source path under `node_modules/fa-mcp-sdk/cli-template/...`, destination, overwrite or merge.>
|
|
399
|
-
|
|
400
|
-
## New Features
|
|
401
|
-
|
|
402
|
-
<New SDK features that the project can now use>
|
|
403
|
-
|
|
404
|
-
## New/Updated Scripts
|
|
405
|
-
|
|
406
|
-
<Scripts that should be copied or updated>
|
|
407
|
-
|
|
408
|
-
## Code Changes Required
|
|
409
|
-
|
|
410
|
-
<Specific code changes needed in the project's src/ files, with before/after examples>
|
|
411
|
-
|
|
412
|
-
## Recommended Actions
|
|
413
|
-
|
|
414
|
-
<Ordered checklist of actions to complete the upgrade>
|
|
415
|
-
|
|
416
|
-
1. [ ] ...
|
|
417
|
-
2. [ ] ...
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
## Step 6: Assess Impact on the Project
|
|
421
|
-
|
|
422
|
-
After generating the guide, scan the current project's source code (`src/`, `config/`, `tests/`) to evaluate how the
|
|
423
|
-
changes specifically affect THIS project. Add a section to the guide:
|
|
424
|
-
|
|
425
|
-
```markdown
|
|
426
|
-
## Impact Assessment for This Project
|
|
427
|
-
|
|
428
|
-
### Affected Files
|
|
429
|
-
|
|
430
|
-
<List of project files that need modification, with specific changes>
|
|
431
|
-
|
|
432
|
-
### Risk Level
|
|
433
|
-
|
|
434
|
-
<Low / Medium / High — based on the number and nature of breaking changes>
|
|
435
|
-
|
|
436
|
-
### Estimated Effort
|
|
437
|
-
|
|
438
|
-
<Brief assessment of the work required>
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
## Step 7: Present Results
|
|
442
|
-
|
|
443
|
-
1. Display a summary of the key findings to the user.
|
|
444
|
-
2. Tell the user the full guide has been saved to `upgrade-guide-<old>-to-<new>.md`.
|
|
445
|
-
3. Ask if they want you to apply any of the recommended changes automatically.
|
|
446
|
-
|
|
447
|
-
## Important Rules
|
|
448
|
-
|
|
449
|
-
- ALWAYS read the actual files to compare — do not guess or assume what changed.
|
|
450
|
-
- When comparing YAML configs, preserve comments and structure.
|
|
451
|
-
- **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.
|
|
452
|
-
- **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.
|
|
453
|
-
- 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.
|
|
454
|
-
- The migration guide must contain ACTIONABLE instructions with exact code/config snippets — not vague recommendations.
|
|
455
|
-
- If GitHub API is unavailable or rate-limited, fall back to comparing files directly from `node_modules/fa-mcp-sdk/` against project files.
|
|
456
|
-
- 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.
|