fa-mcp-sdk 0.2.38 → 0.2.78

package/cli-template/eslint.config.js

@@ -0,0 +1,139 @@
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import importPlugin from 'eslint-plugin-import';
+import unusedImports from 'eslint-plugin-unused-imports';
+
+export default [
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        project: './tsconfig.json',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'import': importPlugin,
+      'unused-imports': unusedImports,
+    },
+    rules: {
+      ...tsPlugin.configs.recommended.rules,
+      '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/no-unsafe-function-type': 'off',
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': ['warn', {
+        'argsIgnorePattern': '^_',
+        'varsIgnorePattern': '^_',
+        'caughtErrorsIgnorePattern': '^_',
+        'ignoreRestSiblings': true
+      }],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      'import/no-default-export': 'error',
+      'import/extensions': ['error', 'always', {
+        'ts': 'never',
+        'js': 'always',
+        'pattern': {
+          '**/*.ts': 'always'
+        },
+        'ignorePackages': true
+      }],
+      // Formatting rules
+      'semi': ['error', 'always'],
+      'quotes': ['error', 'single', { 'avoidEscape': true }],
+      'space-before-function-paren': ['error', {
+        'anonymous': 'always',
+        'named': 'always',
+        'asyncArrow': 'always'
+      }],
+      'object-curly-spacing': ['error', 'always'],
+      'curly': ['error', 'all'],
+      'eol-last': ['error', 'always'],
+    },
+  },
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+      },
+    },
+    plugins: {
+      'import': importPlugin,
+    },
+    rules: {
+      'import/no-default-export': 'off',
+      // Formatting rules
+      'semi': ['error', 'always'],
+      'quotes': ['error', 'single', { 'avoidEscape': true }],
+      'space-before-function-paren': ['error', {
+        'anonymous': 'always',
+        'named': 'always',
+        'asyncArrow': 'always'
+      }],
+      'object-curly-spacing': ['error', 'always'],
+      'curly': ['error', 'all'],
+      'eol-last': ['error', 'always'],
+    },
+  },
+  {
+    files: ['src/index.ts'],
+    rules: {
+      'import/no-default-export': 'off',
+    },
+  },
+  {
+    files: ['**/*.test.ts', '**/*.spec.ts'],
+    languageOptions: {
+      globals: {
+        jest: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+    },
+  },
+  {
+    ignores: [
+      '.claude/',
+      '.idea/',
+      '.run/',
+      '_misc/',
+      '_tmp/',
+      'config/',
+      'deploy/',
+      'dist/',
+      'doc/',
+      'node_modules/',
+      'coverage/',
+      '**/*.d.ts',
+    ],
+  },
+];

package/cli-template/jest.config.js

@@ -0,0 +1,30 @@
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts', '**/tests/**/*.spec.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/index.ts'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov'],
+  verbose: false,
+  silent: true,
+  reporters: ['<rootDir>/tests/jest-simple-reporter.js'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1'
+  },
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      useESM: true
+    }]
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(chalk|@modelcontextprotocol|af-.*)/)'
+  ],
+  extensionsToTreatAsEsm: ['.ts'],
+  forceExit: true,
+  detectOpenHandles: true,
+  testTimeout: 10000
+};

package/cli-template/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "{{project.name}}",
+  "productName": "{{project.productName}}",
+  "version": "0.0.1",
+  "description": "{{project.description}}",
+  "type": "module",
+  "main": "dist/core/index.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "start": "node dist/src/start.js",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "cb": "npm run clean && npm run build",
+    "ci": "node --no-deprecation ./scripts/npm/run.js",
+    "reinstall": "node --no-deprecation ./scripts/npm/run.js reinstall",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "generate-token": "node node_modules/fa-mcp-sdk/dist/core/token/gen-token-app/gen-token-server.js",
+    "dead:exports": "ts-prune",
+    "dead:files": "knip",
+    "postinstall": "node scripts/npm/patch_node_modules.js",
+    "consul:unreg": "node node_modules/fa-mcp-sdk/dist/core/consul/deregister.js",
+    "test": "jest",
+    "test:mcp": "node scripts/test-mcp-tools.js",
+    "test:mcp-http": "node tests/mcp/test-http.js",
+    "test:mcp-sse": "node tests/mcp/test-sse.js",
+    "test:mcp-stdio": "node tests/mcp/test-stdio.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "typescript",
+    "template",
+    "ai",
+    "prompts",
+    "tools",
+    "resources"
+  ],
+  "author": {
+    "name": "{{author.name}}",
+    "email": "{{author.email}}"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "dotenv": "^17.2.3",
+    "fa-mcp-sdk": "^0.2.64",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.10.1",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
+    "cross-env": "^10.1.0",
+    "eslint-config-at-25": "^25.9.6",
+    "jest": "^30.2.0",
+    "rimraf": "^6.1.0",
+    "ts-jest": "^29.4.5",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://{{git-base-url}}/{{project.name}}.git"
+  },
+  "private": true
+}

package/cli-template/scripts/kill-port.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Kill process on specified port (cross-platform)
+ * Usage: node scripts/kill-port.js [port_number]
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+const port = process.argv[2];
+
+if (!port) {
+  console.error('Usage: node scripts/kill-port.js [port_number]');
+  process.exit(1);
+}
+
+async function killProcessOnPort (portNumber) {
+  const isWindows = process.platform === 'win32';
+
+  console.log(`Searching for process on port ${portNumber}...`);
+
+  try {
+    if (isWindows) {
+      // Windows: netstat + taskkill
+      let stdout;
+      try {
+        const result = await execAsync(`netstat -ano | findstr :${portNumber}`);
+        stdout = result.stdout;
+      } catch (error) {
+        // findstr returns error when no matches found
+        console.log(`No process found on port ${portNumber}`);
+        return;
+      }
+
+      if (!stdout || !stdout.trim()) {
+        console.log(`No process found on port ${portNumber}`);
+        return;
+      }
+
+      // Parse PIDs from netstat output
+      const lines = stdout.trim().split('\n');
+      const pids = new Set();
+
+      for (const line of lines) {
+        const parts = line.trim().split(/\s+/);
+        const pid = parts[parts.length - 1];
+        if (pid && pid !== '0' && !isNaN(pid)) {
+          pids.add(pid);
+        }
+      }
+
+      if (pids.size === 0) {
+        console.log(`No process found on port ${portNumber}`);
+        return;
+      }
+
+      // Kill all PIDs
+      for (const pid of pids) {
+        try {
+          console.log(`Found process PID: ${pid}`);
+          await execAsync(`taskkill /F /PID ${pid}`);
+          console.log(`Process ${pid} on port ${portNumber} killed`);
+        } catch (error) {
+          console.error(`Failed to kill process ${pid}:`, error.message);
+        }
+      }
+    } else {
+      // Unix-like: lsof + kill
+      try {
+        const { stdout } = await execAsync(`lsof -ti:${portNumber}`);
+
+        if (!stdout.trim()) {
+          console.log(`No process found on port ${portNumber}`);
+          return;
+        }
+
+        const pids = stdout.trim().split('\n').filter(pid => pid);
+
+        for (const pid of pids) {
+          try {
+            console.log(`Found process PID: ${pid}`);
+            await execAsync(`kill -9 ${pid}`);
+            console.log(`Process ${pid} on port ${portNumber} killed`);
+          } catch (error) {
+            console.error(`Failed to kill process ${pid}:`, error.message);
+          }
+        }
+      } catch (error) {
+        if (error.message.includes('No such file or directory')) {
+          console.error('Error: lsof command not found. Please install lsof.');
+          process.exit(1);
+        }
+        console.log(`No process found on port ${portNumber}`);
+      }
+    }
+  } catch (error) {
+    if (error.stdout && error.stdout.includes('')) {
+      console.log(`No process found on port ${portNumber}`);
+    } else {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  }
+}
+
+killProcessOnPort(port);

package/cli-template/scripts/npm/patch_node_modules.js

@@ -0,0 +1,9 @@
+import fs from 'fs';
+import path from 'path';
+
+const virusFilePath = path.join(process.env.INIT_CWD || process.cwd(), 'node_modules/es5-ext/_postinstall.js');
+
+if (fs.existsSync(virusFilePath)) {
+  console.log('Deleting  file "es5-ext module _postinstall"');
+  fs.unlinkSync(virusFilePath);
+}

package/cli-template/scripts/npm/run.js

@@ -0,0 +1,31 @@
+
+import { spawn } from 'child_process';
+import os from 'os';
+
+function runScript (command, args) {
+  const process = spawn(command, args);
+
+  process.stdout.on('data', (data) => {
+    console.log(data.toString());
+  });
+
+  process.stderr.on('data', (data) => {
+    console.error(data.toString());
+  });
+
+  process.on('close', (code) => {
+    console.log(`${command} script is completed with code: ${code}`);
+  });
+}
+
+const platform = os.platform();
+
+const scriptType = process.argv[2] === 'reinstall' ? 'reinstall' : 'ci';
+
+const scriptsPath = `./scripts/npm/yarn-${scriptType}`;
+
+if (platform === 'win32') {
+  runScript('powershell.exe', ['-ExecutionPolicy', 'Bypass', '-File', `${scriptsPath}.ps1`]);
+} else {
+  runScript('bash', [`${scriptsPath}.sh`]);
+}

package/cli-template/scripts/npm/yarn-ci.ps1

@@ -0,0 +1,16 @@
+Write-Host "Removing node_modules. It may take a while..."
+
+# Ignore errors, equivalent to set +e
+$ErrorActionPreference = "Continue"
+
+# Remove node_modules directory
+Remove-Item -Recurse -Force -ErrorAction SilentlyContinue node_modules
+
+Write-Host "Do yarn ci..."
+
+yarn install --frozen-lockfile
+
+# If argument is passed, wait for key press
+if ($args.Count -gt 0) {
+  Read-Host "Press Enter to resume ..."
+}

package/cli-template/scripts/npm/yarn-ci.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+set +e
+rm -rf node_modules/
+yarn install --frozen-lockfile
+if [[ -n "$1" ]]; then
+  read -p "Press any key to resume ..."
+fi;

package/cli-template/scripts/npm/yarn-reinstall.ps1

@@ -0,0 +1,54 @@
+# Set English language for errors
+[System.Threading.Thread]::CurrentThread.CurrentUICulture = 'en-US'
+[System.Threading.Thread]::CurrentThread.CurrentCulture = 'en-US'
+$OutputEncoding = [Console]::OutputEncoding = [Text.Encoding]::UTF8
+chcp 65001 > $null
+
+# Get processes that use node_modules
+$processes = Get-Process | Where-Object {$_.Path -like "*node_modules*"}
+
+# Check if there are such processes
+if ($processes.Count -gt 0) {
+    Write-Host "Found the following processes holding files in node_modules folder:" -ForegroundColor Yellow
+
+    # Display information about each process
+    $processes | ForEach-Object {
+        Write-Host "- $($_.ProcessName) (ID: $($_.Id))" -ForegroundColor Cyan
+    }
+
+    Write-Host "`nTerminating processes..." -ForegroundColor Yellow
+
+    # Terminate processes
+    $processes | ForEach-Object {
+        Stop-Process -Id $_.Id -Force
+        Write-Host "Process $($_.ProcessName) (ID: $($_.Id)) terminated" -ForegroundColor Green
+    }
+}
+
+Write-Host "Removing node_modules. It may take a while..."
+
+# Ignore errors, equivalent to set +e
+#$ErrorActionPreference = "Continue"
+
+# Remove node_modules directory
+Remove-Item -Recurse -Force -ErrorAction SilentlyContinue node_modules
+
+
+# Check if directory still exists
+if (Test-Path -Path "node_modules") {
+    Write-Host "ERROR: Failed to completely remove node_modules folder!" -ForegroundColor Red
+}
+
+# Remove yarn.lock file if it exists
+if (Test-Path -Path "yarn.lock") {
+    Remove-Item -Path "yarn.lock" -Force
+}
+
+Write-Host "Do yarn install..."
+
+yarn install
+
+# If argument is passed, wait for key press
+if ($args.Count -gt 0) {
+    Read-Host "Press Enter to resume ..."
+}

package/cli-template/scripts/npm/yarn-reinstall.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+set +e
+rm -rf node_modules/
+if [ -f "yarn.lock" ]; then rm yarn.lock; fi;
+yarn install
+if [[ -n "$1" ]]; then
+  read -p "Press any key to resume ..."
+fi;
+

package/cli-template/scripts/pre-commit

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+#=============== Version update before commit: minor + 1 ==========================
+
+#File: .git/hooks/pre-commit
+# Version 2020-08-22
+
+c='\033[0;35m'
+y='\033[0;33m'
+c0='\033[0;0m'
+g='\033[0;32m'
+set -e
+echo -e "$c**** [pre-commit hook] ****$c0"
+
+
+update_version(){
+    old_version=`cat package.json | grep version | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g' | tr -d '[[:space:]]'`
+    echo -e "$c**** Old version is $g$old_version$c ****$c0"
+    version_split=( ${old_version//./ } )
+    major=${version_split[0]:-0}
+    minor=${version_split[1]:-0}
+    patch=${version_split[2]:-0}
+    let "patch=patch+1"
+    new_version="${major}.${minor}.${patch}"
+
+    repo=`cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g' | tr -d '[[:space:]]'`
+    echo -e "$c**** Bumping version of $g$repo$c: $y$old_version$c -> $g$new_version$c  ****$c0"
+    sed -i -e "0,/$old_version/s/$old_version/$new_version/" package.json
+    echo -e "$g"
+    npm version 2>&1 | head -2 | tail -1
+    echo -e "$c0"
+}
+
+branch_name=$(git symbolic-ref --short HEAD)
+retcode=$?
+
+if [[ $retcode -ne 0 ]] ; then
+    echo -e "$y**** Version will not be bumped since retcode is not equals 0 ****$c0"
+    exit 0
+fi
+
+if [[ $branch_name == *"_nap" ]] ; then
+    echo -e "$y**** Version will not be bumped since branch name ends with '_nap'. ****$c0"
+    exit 0
+fi
+
+if [[ $branch_name == *"_local" ]] ; then
+    echo -e "$y**** Version will not be bumped since branch name ends with '_local'. ****$c0"
+    exit 0
+fi
+
+if [[ "$DONT_BUMP_VERSION" -eq "1" ]] ; then
+    echo -e "$y**** Version will not be bumped since variable DONT_BUMP_VERSION is set. ****$c0"
+    exit 0
+fi
+
+update_version
+git add package.json

package/cli-template/scripts/remove-nul.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * Script to remove 'nul' file that accidentally gets created on Windows
+ * This file is created when using 2>nul redirection in Windows commands
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get project root (parent of scripts directory)
+const projectRoot = path.resolve(__dirname, '..');
+
+// File to remove
+const nulFile = path.join(projectRoot, 'nul');
+
+// Check if file exists and remove it
+if (fs.existsSync(nulFile)) {
+  try {
+    fs.unlinkSync(nulFile);
+    console.log('✅  Removed "nul" file from project root');
+  } catch (error) {
+    console.error('❌  Error removing "nul" file:', error.message);
+    process.exit(1);
+  }
+} else {
+  console.log('ℹ️  No "nul" file found in project root');
+}
+
+// Also check for other common accidental files on Windows
+const accidentalFiles = ['nul', 'NUL', 'con', 'CON', 'aux', 'AUX', 'prn', 'PRN'];
+
+accidentalFiles.forEach(fileName => {
+  const filePath = path.join(projectRoot, fileName);
+  if (fs.existsSync(filePath)) {
+    try {
+      const stats = fs.statSync(filePath);
+      if (stats.isFile()) {
+        fs.unlinkSync(filePath);
+        console.log(`✅  Removed "${fileName}" file from project root`);
+      }
+    } catch (error) {
+      console.error(`⚠️  Could not remove "${fileName}":`, error.message);
+    }
+  }
+});
+
+console.log('🎯 Cleanup completed');

package/cli-template/src/_types_/common.d.ts

@@ -0,0 +1,27 @@
+export interface ISearchParams {
+  query: string; // Search query string
+  limit?: number; // Maximum number of results (default: 20)
+  threshold?: number; // Minimum similarity threshold (0-1)
+}
+
+export interface ISearchResultRow {
+  similarity_score: number;
+  word_similarity_score: number;
+  final_score: number;
+  similarity: number; // mapped from final_score
+
+  [prop: string]: number | string;
+}
+
+export interface ISearchResultRow {
+  similarity_score: number;
+  word_similarity_score: number;
+  final_score: number;
+
+  [prop: string]: number | string;
+}
+
+export type ISearchResult = {
+  similarity: number; // mapped from final_score
+  [prop: string]: number | string | undefined;
+}[]

package/cli-template/src/api/router.ts

@@ -0,0 +1,35 @@
+import { Router, Request, Response } from 'express';
+import { logger, authTokenMW, IEndpointsOn404 } from 'fa-mcp-sdk';
+
+export const apiRouter: Router | null = Router();
+
+/**
+ * Template for API routes
+ * Modify this file to implement your specific API endpoints
+ */
+
+// Example protected endpoint using auth middleware
+apiRouter.get('/example', authTokenMW, async (req: Request, res: Response) => {
+  try {
+    logger.info('Example endpoint called');
+
+    res.json({
+      success: true,
+      message: 'This is a template endpoint',
+      data: {
+        timestamp: new Date().toISOString(),
+      },
+    });
+  } catch (error) {
+    logger.error('Error in example endpoint:', error);
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    });
+  }
+});
+
+export const endpointsOn404: IEndpointsOn404 = {
+  myEndpoints1: ['/my-endpoint-1', '/my-endpoint-2'],
+  myEndpoint3: '/my-endpoint-3',
+};