fa-mcp-sdk 0.4.70 → 0.4.71

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

@@ -110,10 +110,15 @@ Wait for completion. If it fails, report the error and stop.
 
 Run:
 ```bash
-node ./node_modules/fa-mcp-sdk/scripts/update-doc.js
+node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js
 ```
 
-This copies the latest `FA-MCP-SDK-DOC/` from the SDK into the project.
+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
 
@@ -187,7 +192,7 @@ Map of template file → project file (the CLI `bin/fa-mcp.js` applies these tra
 | `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-doc.js` |
+| `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
 
@@ -286,7 +291,7 @@ Generated: <timestamp>
 ### New Configuration Keys
 
 <For each new key, provide:>
-- Key path (e.g., `webServer.adminAuth.type`)
+- Key path (e.g., `webServer.auth.enabled`)
 - Default value
 - Description
 - Whether it needs to be added to the project's config
@@ -403,7 +408,7 @@ changes specifically affect THIS project. Add a section to the guide:
 - 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-doc.js) unless the user explicitly asks.
+- 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.

package/cli-template/package.json

@@ -22,7 +22,7 @@
     "generate-token": "node node_modules/fa-mcp-sdk/dist/core/auth/token-generator/server.js",
     "dead:exports": "ts-prune",
     "dead:files": "knip",
-    "update-sdk-docs": "node ../scripts/update-doc.js",
+    "update-sdk-docs": "node ../scripts/update-sdk.js",
     "postinstall": "node ../scripts/npm/patch_node_modules.js",
     "check-llm": "node node_modules/fa-mcp-sdk/dist/core/agent-tester/check-llm.js",
     "consul:unreg": "node node_modules/fa-mcp-sdk/dist/core/consul/deregister.js",
@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.4.70"
+    "fa-mcp-sdk": "^0.4.71"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/cli-template/r/{update-doc.js.xml → update-sdk.js.xml}

@@ -1,5 +1,5 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="update-doc.js" type="NodeJSConfigurationType" nameIsGenerated="true" path-to-js-file="scripts/update-doc.js" working-dir="$PROJECT_DIR$">
-    <method v="2" />
-  </configuration>
-</component>
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="update-sdk.js" type="NodeJSConfigurationType" nameIsGenerated="true" path-to-js-file="scripts/update-sdk.js" working-dir="$PROJECT_DIR$">
+    <method v="2" />
+  </configuration>
+</component>

package/config/_local.yaml

@@ -24,6 +24,26 @@
 #     #> Override the Consul service name to look up (defaults to the alias key)
 #     consulServiceName: <consulServiceName>
 
+#> ========================================================================
+#> ADMIN PANEL
+#> Token generation & validation UI served at /admin.
+#> Supports 4 authentication methods: permanentServerTokens, basic, jwtToken, ntlm.
+#> ========================================================================
+adminPanel:
+  #> Enable/disable admin panel. false — /admin is not mounted at all.
+  enabled: true
+  #> Authentication type: 'permanentServerTokens' | 'basic' | 'jwtToken' | 'ntlm' | 'none'
+  #> Accepts a single type (string) or multiple types (array):
+  #>   authType: 'basic'
+  #>   authType: ['jwtToken', 'basic']
+  #> 'none' / null / empty array / not set → panel opens WITHOUT authentication
+  #>   (convenience for local development and debugging; do NOT use in production).
+  #> For permanentServerTokens, basic, jwtToken — uses credentials from webServer.auth section.
+  #> For ntlm — uses AD configuration from ad.domains section.
+  #> When multiple types are set (e.g. ['jwtToken', 'basic']), the login page shows tabs
+  #> to choose between Token and Login (username/password) authentication.
+  authType: 'basic'
+
 #> Active Directory / LDAP settings.
 #> Used for authentication/authorization (e.g., NTLM in admin panel) and checking user membership in AD groups.
 ad:
@@ -325,21 +345,3 @@ webServer:
   #> Requires valid Authorization header (any method configured in webServer.auth).
   #> ========================================================================
   genJwtApiEnable: false
-
-  #> ========================================================================
-  #> ADMIN PANEL AUTHENTICATION
-  #> Token generation page available at /admin endpoint
-  #> Supports 4 authentication methods: permanentServerTokens, basic, jwtToken, ntlm
-  #> ========================================================================
-  adminAuth:
-    #> Enable/disable admin panel
-    enabled: true
-    #> Authentication type for admin panel: 'permanentServerTokens' | 'basic' | 'jwtToken' | 'ntlm'
-    #> Accepts a single type (string) or multiple types (array):
-    #>   type: 'basic'
-    #>   type: ['jwtToken', 'basic']
-    #> For permanentServerTokens, basic, jwtToken — uses credentials from webServer.auth section
-    #> For ntlm — uses AD configuration from ad.domains section (no additional credentials needed)
-    #> When multiple types are set (e.g. ['jwtToken', 'basic']), the login page shows tabs
-    #> to choose between Token and Login (username/password) authentication.
-    type: 'basic'

package/config/local.yaml

@@ -11,6 +11,9 @@ agentTester:
     baseURL: https://litellm.finam.ru/v1
     exposeToClient: true
 
+adminPanel:
+  enabled: true
+  authType: [ 'permanentServerTokens', 'basic', 'jwtToken' ]
 
 ad:
   domains:
@@ -104,7 +107,3 @@ webServer:
 
 
   genJwtApiEnable: false
-  adminAuth:
-    enabled: true
-    # 'permanentServerTokens' | 'basic' | 'jwtToken' | 'ntlm'
-    type: [ 'permanentServerTokens', 'basic', 'jwtToken' ]

package/package.json

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

package/scripts/update-sdk.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname, join, relative, sep } from 'path';
+
+const templateDir = join(process.cwd(), './node_modules/fa-mcp-sdk/cli-template');
+const cwd = process.cwd();
+
+const targets = [
+  { name: 'FA-MCP-SDK-DOC', src: join(templateDir, 'FA-MCP-SDK-DOC'), dest: join(cwd, 'FA-MCP-SDK-DOC') },
+  {
+    name: '.claude',
+    src: join(templateDir, '.claude'),
+    dest: join(cwd, '.claude'),
+    preserve: ['settings.json'],
+    respectPin: true,
+  },
+];
+
+// A folder containing a direct file named `pin` is preserved untouched —
+// it is neither deleted nor overwritten with new content from the template.
+function findPinnedFolders (rootDir) {
+  const pinned = new Set();
+  if (!existsSync(rootDir)) {return pinned;}
+  const walk = (currentDir) => {
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    if (entries.some((e) => e.isFile() && e.name === 'pin')) {
+      const rel = relative(rootDir, currentDir);
+      if (rel) {pinned.add(rel);}
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {walk(join(currentDir, entry.name));}
+    }
+  };
+  walk(rootDir);
+  return pinned;
+}
+
+function isInsidePinned (relPath, pinned) {
+  if (!relPath) {return false;}
+  if (pinned.has(relPath)) {return true;}
+  for (const p of pinned) {
+    if (relPath.startsWith(p + sep)) {return true;}
+  }
+  return false;
+}
+
+function cleanExceptPinned (rootDir, pinned) {
+  if (!existsSync(rootDir)) {return;}
+  const walk = (currentDir) => {
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(currentDir, entry.name);
+      const fullRel = relative(rootDir, full);
+      if (pinned.has(fullRel)) {continue;}
+      const hasPinnedDescendant = [...pinned].some((p) => p.startsWith(fullRel + sep));
+      if (entry.isDirectory() && hasPinnedDescendant) {
+        walk(full);
+      } else {
+        rmSync(full, { recursive: true, force: true });
+      }
+    }
+  };
+  walk(rootDir);
+}
+
+for (const { name, src, dest, preserve = [], respectPin = false } of targets) {
+  if (!existsSync(src)) {
+    console.error('Source not found:', src);
+    process.exit(1);
+  }
+  const saved = {};
+  for (const file of preserve) {
+    const p = join(dest, file);
+    if (existsSync(p)) {saved[file] = readFileSync(p);}
+  }
+
+  const pinned = respectPin ? findPinnedFolders(dest) : new Set();
+
+  if (existsSync(dest)) {
+    if (pinned.size > 0) {
+      cleanExceptPinned(dest, pinned);
+    } else {
+      rmSync(dest, { recursive: true });
+    }
+  }
+
+  cpSync(src, dest, {
+    recursive: true,
+    filter: (srcPath) => {
+      if (preserve.includes(basename(srcPath))) {return false;}
+      if (respectPin && pinned.size > 0) {
+        const rel = relative(src, srcPath);
+        if (isInsidePinned(rel, pinned)) {return false;}
+      }
+      return true;
+    },
+  });
+
+  for (const [file, content] of Object.entries(saved)) {
+    const p = join(dest, file);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, content);
+  }
+
+  if (pinned.size > 0) {
+    console.log(`${name} updated (pinned folders preserved: ${[...pinned].join(', ')})`);
+  } else {
+    console.log(`${name} updated`);
+  }
+}

package/scripts/update-doc.js

@@ -1,36 +0,0 @@
-#!/usr/bin/env node
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
-import { basename, dirname, join } from 'path';
-
-const templateDir = join(process.cwd(), './node_modules/fa-mcp-sdk/cli-template');
-const cwd = process.cwd();
-
-const targets = [
-  { name: 'FA-MCP-SDK-DOC', src: join(templateDir, 'FA-MCP-SDK-DOC'), dest: join(cwd, 'FA-MCP-SDK-DOC') },
-  { name: '.claude', src: join(templateDir, '.claude'), dest: join(cwd, '.claude'), preserve: ['settings.json'] },
-];
-
-for (const { name, src, dest, preserve = [] } of targets) {
-  if (!existsSync(src)) {
-    console.error('Source not found:', src);
-    process.exit(1);
-  }
-  const saved = {};
-  for (const file of preserve) {
-    const p = join(dest, file);
-    if (existsSync(p)) saved[file] = readFileSync(p);
-  }
-  if (existsSync(dest)) {
-    rmSync(dest, { recursive: true });
-  }
-  cpSync(src, dest, {
-    recursive: true,
-    filter: (srcPath) => !preserve.includes(basename(srcPath)),
-  });
-  for (const [file, content] of Object.entries(saved)) {
-    const p = join(dest, file);
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, content);
-  }
-  console.log(`${name} updated`);
-}