fa-mcp-sdk 0.4.36 → 0.4.39

package/README.md

@@ -211,6 +211,7 @@ Note: The `dist/` directory (compiled JavaScript) is created after running `npm
 | `npm run generate-token` | Generate JWT tokens (Web UI) |
 | `node scripts/generate-jwt.js` | Generate JWT token (CLI) |
 | `/gen-jwt` | Generate JWT token (Claude Code skill) |
+| `/upgrade-guide` | Generate upgrade guide for downstream projects (Claude Code skill) |
 | `npm run consul:unreg` | Deregister from Consul |
 
 
@@ -244,6 +245,23 @@ agentTester:
 The tester UI is available at `http://localhost:<port>/agent-tester` and auto-connects to the local MCP server.
 Supports custom LLM endpoints, configurable system prompts, and dynamic HTTP headers. Recommended model for testing: **gpt-5.2**.
 
+## Upgrade Guide Skill
+
+Claude Code skill that generates a step-by-step upgrade guide for projects built on fa-mcp-sdk.
+Analyzes git diff between two versions/commits and produces an MD file covering config changes, template file updates, script changes, API changes, and dependency updates.
+
+**Usage in Claude Code:**
+```
+/upgrade-guide 0.4.30 0.4.37
+/upgrade-guide 0.4.30
+/upgrade-guide abc1234
+/upgrade-guide 0.4.30 0.4.37 на русском
+```
+
+Output language is English by default. Add a natural-language hint (e.g., "на русском", "in German") to change it.
+
+Skill location: `.claude/skills/upgrade-guide/SKILL.md`
+
 ## Directory Requirements
 
 - Use absolute paths for target directory

package/cli-template/.claude/skills/upgrade-guide/SKILL.md

@@ -0,0 +1,276 @@
+---
+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).
+
+**Two arguments** — explicit FROM and TO:
+- `/upgrade-guide 0.4.30 0.4.37` — from version 0.4.30 to 0.4.37
+- `/upgrade-guide abc1234 def5678` — from commit to commit
+
+**One argument** — FROM is the current installed version, TO is the argument:
+- `/upgrade-guide 0.5.0` — upgrade from current to 0.5.0
+- `/upgrade-guide abc1234` — upgrade from current to that commit
+
+**No arguments** — FROM is the current installed version, TO is the latest published version.
+
+## Step 1: Determine Versions
+
+1. Read the current project's `package.json` and extract the installed `fa-mcp-sdk` version — this is the **default FROM**.
+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**.
+3. Apply argument parsing rules above to determine the actual FROM and TO.
+4. If FROM equals TO — inform the user and stop.
+
+Display to the user:
+```
+From: X.Y.Z (or commit hash)
+To:   A.B.C (or commit hash)
+```
+
+## Step 2: Upgrade the Dependency
+
+If TO is a published version (not a commit hash), run:
+```bash
+yarn add fa-mcp-sdk@<TO-version>
+```
+
+If TO is a commit hash, run:
+```bash
+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:
+```bash
+node ./node_modules/fa-mcp-sdk/scripts/update-doc.js
+```
+
+This copies the latest `FA-MCP-SDK-DOC/` from the SDK into the project.
+
+## 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.
+
+### 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/custom-environment-variables.yaml` — env var mappings
+- `config/development.yaml` — dev overrides
+- `config/production.yaml` — production overrides
+- `config/local.yaml` — local secrets template
+
+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
+
+### 4.3 Analyze changes in cli-template files
+
+These directories in the SDK template may have changed:
+
+- `node_modules/fa-mcp-sdk/cli-template/` — the project template
+
+Compare template files with their project counterparts. Key files to check:
+
+- `package.json` — new scripts, dependency changes
+- `tsconfig.json` — compiler option changes
+- `eslint.config.js` — linting rule changes
+- `CLAUDE.md` — project instructions updates
+- `deploy/` — deployment configuration changes
+- `jest.config.js` — test configuration changes
+- `.claude/skills/` — new or updated skills
+
+### 4.4 Analyze changes in scripts
+
+Check `node_modules/fa-mcp-sdk/scripts/` for new or modified scripts that may need to be copied or adapted in the project.
+
+### 4.5 Analyze changes in core library exports
+
+Read `node_modules/fa-mcp-sdk/dist/core/index.js` (or `.d.ts`) to identify:
+- New exports that may be useful
+- Removed/renamed exports that may break existing code
+- Changed type signatures
+
+### 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:
+
+```markdown
+# 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.adminAuth.type`)
+- 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>
+    ```
+
+### Recommended config/custom-environment-variables.yaml additions
+
+    ```yaml
+    # Add these mappings:
+    <actual YAML snippets>
+    ```
+
+## Template File Changes
+
+### package.json
+
+<New scripts, changed dependencies, etc.>
+
+### Other Template Files
+
+<Changes in tsconfig.json, eslint.config.js, deploy/, etc.>
+
+## 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:
+
+```markdown
+## 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.
+- Do not modify project files other than `package.json` (via yarn add) and `FA-MCP-SDK-DOC/` (via update-doc.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.

package/cli-template/README.md

@@ -102,4 +102,18 @@ Add to `claude_desktop_config.json`:
 - **/sse** - Server-Sent Events
 - **/mcp** - JSON-RPC 2.0
 
+## Claude Code Skills
+
+### `/upgrade-guide`
+
+Generates a migration guide for upgrading `fa-mcp-sdk` to the latest (or specified) version. Analyzes config changes, template diffs, new exports, and breaking changes, then saves a step-by-step guide to `upgrade-guide-<old>-to-<new>.md`.
+
+```
+/upgrade-guide                        # current → latest
+/upgrade-guide 0.5.0                  # current → 0.5.0
+/upgrade-guide 0.4.30 0.5.0           # 0.4.30 → 0.5.0
+/upgrade-guide abc1234 def5678        # commit → commit
+/upgrade-guide 0.4.30 0.5.0 на русском
+```
+
 ## Security

package/cli-template/package.json

@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.4.36"
+    "fa-mcp-sdk": "^0.4.39"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/dist/core/web/static/agent-tester/index.html

@@ -119,8 +119,11 @@
                 <section class="config-section">
                     <div class="form-group">
                         <div class="prompt-label-row">
-                            <label for="systemPrompt">Agent Prompt</label>
+                            <label for="systemPrompt">Agent Prompt<span class="prompt-modified-badge" id="promptModifiedBadge" style="display:none">(modified)</span></label>
                             <div class="prompt-actions">
+                                <button type="button" class="btn-view-original" id="btnViewOriginalPrompt" title="View original agent prompt" data-testid="at-system-prompt-view-original" style="display:none">
+                                    <span class="material-icons-round">visibility</span>
+                                </button>
                                 <button type="button" class="btn-reset-prompt" id="btnResetAgentPrompt" title="Reset to original agent prompt" data-testid="at-system-prompt-reset" style="display:none">
                                     <span class="material-icons-round">restart_alt</span>
                                 </button>

package/dist/core/web/static/agent-tester/script.js

@@ -398,6 +398,8 @@ class McpAgentTester {
     this.systemPromptTextarea = document.getElementById('systemPrompt');
     this.customPromptTextarea = document.getElementById('customPrompt');
     this.btnResetAgentPrompt = document.getElementById('btnResetAgentPrompt');
+    this.btnViewOriginalPrompt = document.getElementById('btnViewOriginalPrompt');
+    this.promptModifiedBadge = document.getElementById('promptModifiedBadge');
     this.originalAgentPrompt = null;
 
     this.connectedServersContainer = document.getElementById('connectedServers');
@@ -442,9 +444,13 @@ class McpAgentTester {
     this.serverUrlDropdown.addEventListener('click', (e) => this.toggleUrlDropdown(e));
     document.addEventListener('click', (e) => this.handleClickOutside(e));
 
-    this.systemPromptTextarea.addEventListener('input', () => this.saveFormValuesToStorage());
+    this.systemPromptTextarea.addEventListener('input', () => {
+      this.saveFormValuesToStorage();
+      this.updatePromptModifiedState();
+    });
     this.customPromptTextarea.addEventListener('input', () => this.saveFormValuesToStorage());
     this.btnResetAgentPrompt.addEventListener('click', () => this.resetAgentPrompt());
+    this.btnViewOriginalPrompt.addEventListener('click', () => this.viewOriginalPrompt());
 
     // LLM settings modal
     this.llmSettingsBtn.addEventListener('click', () => this.openLlmModal());
@@ -532,7 +538,15 @@ class McpAgentTester {
   }
 
   closePromptModal () {
-    document.getElementById('promptModal').style.display = 'none';
+    const modal = document.getElementById('promptModal');
+    const textarea = document.getElementById('promptModalTextarea');
+    const saveBtn = document.getElementById('promptModalSave');
+    modal.style.display = 'none';
+    if (this._viewOriginalMode) {
+      textarea.readOnly = false;
+      saveBtn.style.display = '';
+      this._viewOriginalMode = false;
+    }
     this._promptModalTarget = null;
   }
 
@@ -1693,11 +1707,41 @@ class McpAgentTester {
       this.systemPromptTextarea.value = this.originalAgentPrompt;
       this.currentSystemPrompt = this.originalAgentPrompt;
       this.saveFormValuesToStorage();
+      this.updatePromptModifiedState();
     }
   }
 
+  viewOriginalPrompt () {
+    if (!this.originalAgentPrompt) { return; }
+    const modal = document.getElementById('promptModal');
+    const textarea = document.getElementById('promptModalTextarea');
+    const title = document.getElementById('promptModalTitle');
+    const saveBtn = document.getElementById('promptModalSave');
+    title.textContent = 'Original Agent Prompt';
+    textarea.value = this.originalAgentPrompt;
+    textarea.readOnly = true;
+    saveBtn.style.display = 'none';
+    this._promptModalTarget = null;
+    this._viewOriginalMode = true;
+    modal.style.display = 'flex';
+    textarea.focus();
+  }
+
   updateResetPromptButton () {
     this.btnResetAgentPrompt.style.display = this.originalAgentPrompt ? '' : 'none';
+    this.updatePromptModifiedState();
+  }
+
+  updatePromptModifiedState () {
+    const hasOriginal = !!this.originalAgentPrompt;
+    const isModified = hasOriginal && this.systemPromptTextarea.value.trim() !== this.originalAgentPrompt.trim();
+    this.promptModifiedBadge.style.display = isModified ? '' : 'none';
+    this.btnViewOriginalPrompt.style.display = isModified ? '' : 'none';
+    if (isModified) {
+      this.systemPromptTextarea.classList.add('prompt-modified');
+    } else {
+      this.systemPromptTextarea.classList.remove('prompt-modified');
+    }
   }
 
   saveFormValuesToStorage () {

package/dist/core/web/static/agent-tester/styles.css

@@ -1391,6 +1391,40 @@ body {
   gap: 2px;
 }
 
+/* --- Prompt Modified Indicator --- */
+.prompt-modified-badge {
+  font-size: 0.75em;
+  color: var(--warning, #f0ad4e);
+  margin-left: 6px;
+  font-style: italic;
+  font-weight: 400;
+}
+
+textarea.prompt-modified {
+  border-left: 3px solid var(--warning, #f0ad4e) !important;
+}
+
+.btn-view-original {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 2px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-sm);
+  transition: color 0.15s;
+}
+
+.btn-view-original:hover {
+  color: var(--primary);
+}
+
+.btn-view-original .material-icons-round {
+  font-size: 16px;
+}
+
 .btn-reset-prompt {
   background: none;
   border: none;
@@ -1449,8 +1483,8 @@ body {
   border: 1px solid var(--border);
   border-radius: var(--radius-lg);
   width: 100%;
-  max-width: 900px;
-  max-height: 85vh;
+  max-width: 90vw;
+  height: 90vh;
   display: flex;
   flex-direction: column;
   box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fa-mcp-sdk",
   "productName": "FA MCP SDK",
-  "version": "0.4.36",
+  "version": "0.4.39",
   "description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",