fa-mcp-sdk 0.2.38 → 0.2.76

package/cli-template/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+end_of_line = lf
+indent_size = 2
+indent_style = space
+charset = utf-8
+
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 2
+
+

package/cli-template/.env.example

@@ -0,0 +1,29 @@
+SERVICE_NAME={{project.name}}
+# Used as an alternate service name when using systemd
+SERVICE_NAME_ALT={{project.name}}
+NODE_ENV={{NODE_ENV}}
+# Used for PM2
+SERVICE_INSTANCE={{SERVICE_INSTANCE}}
+PM2_NAMESPACE={{PM2_NAMESPACE}}
+
+# Affects how the Consul service ID is formed - as a product or development ID
+NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
+
+DEBUG=config-info
+# Used for PM2 service configuration
+#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
+#│ id │ name                                                      │ namespace       │
+#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
+#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
+
+## DEBUG patterns ##
+# AP-UPDATER - consul/access-points-updater
+# af-consul:reg | af-consul:* - consul/cyclic-register
+# af-consul:curl - consul/prepare-consul-api
+# token:auth
+
+# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
+# TEST_MCP_SERVER_URL=
+
+# The directory to store test result logs
+TEST_RESULT_LOGS_DIR='_logs/mcp'

package/cli-template/.envrc

@@ -0,0 +1,3 @@
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
+nvm use 22.17.1

package/cli-template/.run/== START ==.run.xml

@@ -0,0 +1,14 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="== START ==" type="js.build_tools.npm">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="start" />
+    </scripts>
+    <node-interpreter value="project" />
+    <node-options value="--dns-result-order=ipv4first --no-node-snapshot" />
+    <package-manager value="npm" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/TEST HTTP.run.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TEST HTTP" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-http.js" working-dir="$PROJECT_DIR$/">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/TEST SSE.run.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TEST SSE" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-sse.js" working-dir="$PROJECT_DIR$/">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/TEST STDIO.run.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TEST STDIO" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-stdio.js" working-dir="$PROJECT_DIR$">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/TEST search.run.xml

@@ -0,0 +1,11 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TEST search" type="JavaScriptTestRunnerJest">
+    <node-interpreter value="project" />
+    <jest-package value="$PROJECT_DIR$/node_modules/jest" />
+    <working-dir value="$PROJECT_DIR$" />
+    <envs />
+    <scope-kind value="TEST_FILE" />
+    <test-file value="$PROJECT_DIR$/tests/tools/search.test.ts" />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/cb.run.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="cb" type="js.build_tools.npm">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="cb" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/ci.run.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="ci" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="ci" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/kill-port 3030.run.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="kill-port 3030" type="NodeJSConfigurationType" application-parameters="3030" path-to-js-file="scripts/kill-port.js" working-dir="$PROJECT_DIR$">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/lint.run.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="lint" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="lint" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/lint_fix.run.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="lint:fix" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="lint:fix" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/reinstall.run.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="reinstall" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="reinstall" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/.run/remove-nul.js.run.xml

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

package/cli-template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael Makarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cli-template/config/_local.yaml

@@ -0,0 +1,64 @@
+# Copy this file to local.yaml and update with your database credentials
+# local.yaml is gitignored and won't be committed
+---
+consul:
+  agent:
+    dev:
+      # Token for getting information about DEV services
+      token: '{{consul.agent.dev.token}}'
+    prd:
+      # Token for obtaining information about PROD services
+      token: '{{consul.agent.prd.token}}'
+    reg:
+      # host: '***' # The host of the consul agent where the service will be registered. If not specified, the server on which the service is running is used
+      # Token for registering the service in the consul agent
+      token: '{{consul.agent.reg.token}}'
+  service:
+    enable: {{consul.service.enable}} # true - Allows registration of the service with the consul
+    instance: 'instance-0' # This value will be specified as a suffix in the id of the service
+  envCode: # Used to generate the service ID
+    prod: '{{consul.envCode.prod}}' # Production environment code
+    dev: '{{consul.envCode.dev}}' # Development environment code
+
+db:
+  postgres:
+    dbs:
+      main:
+        label: 'Your Database Label'
+        database: your_database
+        host: 'your_host' # To exclude the use of the database, you need to set host = ''
+        port: 5432
+        user: your_user
+        password: your_password
+#        usedExtensions:
+#          - pgvector
+
+logger:
+  level: info
+  useFileLogger: true # To use or not to use logging to a file
+
+mcp:
+  transportType: http # 'stdio' or 'http'
+  toolAnswerAs: text # text | structuredContent
+  rateLimit:
+    maxRequests: 100
+    windowMs: 60000  # 1 minute
+
+swagger:
+  servers:  # An array of servers that will be added to swagger docs
+    - url: http://localhost:{{port}}
+      description: "Local server"
+
+webServer:
+  port: {{port}}
+  # array of hosts that CORS skips
+  originHosts: ['localhost', '0.0.0.0']
+  auth:
+    enabled: {{webServer.auth.enabled}} # Enables/disables token authorization
+    # An array of fixed tokens that pass to the MCP (use only for MCPs with green data or for development)
+    permanentServerTokens: []
+    token:
+      # Symmetric encryption key to generate a token for this MCP
+      encryptKey: '{{webServer.auth.token.encryptKey}}'
+      # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
+      checkMCPName: {{webServer.auth.token.checkMCPName}}

package/cli-template/config/custom-environment-variables.yaml

@@ -0,0 +1,33 @@
+db:
+  postgres:
+    dbs:
+      main:
+        database: DB_NAME
+        host: DB_HOST
+        port: DB_PORT
+        user: DB_USER
+        password: DB_PASSWORD
+
+logger:
+  level: LOGGER_LEVEL
+  useFileLogger: LOGGER_USE_FILE_LOGGER
+
+mcp:
+  transportType: MCP_TRANSPORT_TYPE
+  toolAnswerAs: MCP_TOOL_ANSWER_AS
+  rateLimit:
+    maxRequests: MCP_RATE_LIMIT_MAX_REQUESTS
+    windowMs: MCP_RATE_LIMIT_WINDOW_MS
+
+uiColor:
+  primary: UI_COLOR_PRIMARY
+
+webServer:
+  host: WS_HOST
+  port: WS_PORT
+  auth:
+    enabled: WS_AUTH_ENABLED
+    permanentServerTokens: WS_SERVER_TOKENS # comma separated list
+    token:
+      encryptKey: WS_TOKEN_ENCRYPT_KEY
+      checkMCPName: WS_CHECK_MC_NAME

package/cli-template/config/default.yaml

@@ -0,0 +1,101 @@
+---
+
+#accessPoints:
+#  myService:
+#    title: 'My remote service'
+#    host: <host>
+#    port: 9999
+#    token: '***'
+#    noConsul: true # Use if the service developers do not provide registration in consul
+#    consulServiceName: <consulServiceName>
+
+consul:
+  check:
+    interval: '10s'
+    timeout: '5s'
+    deregistercriticalserviceafter: '3m'
+  agent:
+    dev:
+      dc: '{{consul.agent.dev.dc}}'
+      host: '{{consul.agent.dev.host}}'
+      port: 443
+      secure: true
+      # Token for getting information about DEV services
+      token: '***'
+    prd:
+      dc: '{{consul.agent.prd.dc}}'
+      host: '{{consul.agent.prd.host}}'
+      port: 443
+      secure: true
+      # Token for obtaining information about PROD services
+      token: '***'
+    reg:
+      host: null # The host of the consul agent where the service will be registered. If not specified, the server on which the service is running is used
+      port: 8500
+      secure: false
+      # Token for registering the service in the consul agent
+      token: '***'
+  service:
+    enable: {{consul.service.enable}} # true - Allows registration of the service with the consul
+    name: <name> # <name> will be replaced by <package.json>.name at initialization
+    instance: 'instance-0' # This value will be specified as a suffix in the id of the service
+    version: <version> # <version> will be replaced by <package.json>.version at initialization
+    description: <description> # <description> will be replaced by <package.json>.description at initialization
+    tags: [] # If null or empty array - Will be pulled up from package.keywords at initialization
+    meta:
+      # "About" page link template
+      who: 'http://{address}:{port}/'
+  envCode: # Used to generate the service ID
+    prod: {{consul.envCode.prod}} # Production environment code
+    dev: {{consul.envCode.dev}} # Development environment code
+
+db:
+  postgres:
+    dbs:
+      main:
+        label: 'My Database'
+        host: ''  # To exclude the use of the database, you need to set host = ''
+        port: 5432
+        database: <database>
+        user: <user>
+        password: <password>
+        usedExtensions: []
+
+logger:
+  level: info
+  useFileLogger: true # To use or not to use logging to a file
+
+mcp:
+  transportType: http # stdio | http
+  # Response format configuration.
+  # - structuredContent - default - the response in result.structuredContent returns JSON
+  # - text - in the response, serialized JSON is returned in result.content[0].text
+  toolAnswerAs: text # text | structuredContent
+  rateLimit:
+    maxRequests: 100
+    windowMs: 60000  # 1 minute
+
+swagger:
+  servers:  # An array of servers that will be added to swagger docs
+    - url: http://localhost:{{port}}
+      description: "Development server (localhost)"
+    - url: http://0.0.0.0:{{port}}
+      description: "Development server (all interfaces)"
+
+uiColor:  # Font color of the header and a number of interface elements on the ABOUT page
+  primary: '#0f65dc'
+
+webServer:
+  host: '0.0.0.0'
+  port: {{port}}
+  # array of hosts that CORS skips
+  originHosts: ['localhost', '0.0.0.0']
+  auth:
+    enabled: false # Enables/disables token authorization
+    # An array of fixed tokens that pass to the MCP (use only for MCPs with green data or for development)
+    permanentServerTokens: []
+    token:
+      # Symmetric encryption key to generate a token for this MCP
+      encryptKey: '***'
+      # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
+      checkMCPName: true

package/cli-template/config/development.yaml

@@ -0,0 +1,4 @@
+---
+
+
+

package/cli-template/config/production.yaml

@@ -0,0 +1,4 @@
+---
+
+
+

package/cli-template/config/test.yaml

@@ -0,0 +1,26 @@
+---
+# Test configuration - mocked database and minimal setup
+db:
+  postgres:
+    dbs:
+      main:
+        label: 'Test Database (Mocked)'
+        database: test_db
+        host: localhost
+        port: 5432
+        password: test_password
+        user: test_user
+
+logger:
+  level: error  # Minimize log output during tests
+
+mcp:
+  transportType: stdio
+  rateLimit:
+    maxRequests: 1000
+    windowMs: 60000
+
+webServer:
+  host: '127.0.0.1'
+  port: 0  # Random port for testing
+  originHosts: ['localhost']

package/cli-template/deploy/config.example.yml

@@ -0,0 +1,3 @@
+branch: master
+email: vvpipkin@corp.com
+

package/cli-template/deploy/mcp-template.com.conf

@@ -0,0 +1,58 @@
+# sudo vim /etc/nginx/sites-enabled/{{mcp.domain}}.conf
+
+#Setup upstream for backend Node.js server
+upstream {{upstream}}  {
+    server 127.0.0.1:9020;
+    keepalive 8;
+}
+
+#The Nginx server instance
+server {
+    server_name {{mcp.domain}};
+    access_log /var/log/nginx/{{mcp.domain}}.log;
+    error_log /var/log/nginx/{{mcp.domain}}.ERROR.log;
+
+    # SSE endpoint for MCP protocol - requires special streaming settings
+    location /sse {
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Host $http_host;
+        proxy_set_header X-NginX-Proxy true;
+        proxy_set_header Cache-Control no-cache;
+        proxy_set_header Connection '';
+
+        proxy_http_version 1.1;
+        proxy_pass http://{{upstream}}/sse;
+        proxy_redirect off;
+        proxy_buffering off;
+        proxy_cache off;
+    }
+
+    # All other endpoints (/, /health, /api/, /docs, /mcp)
+    location / {
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Host $http_host;
+        proxy_set_header X-NginX-Proxy true;
+
+        proxy_pass http://{{upstream}}/;
+        proxy_redirect off;
+    }
+
+    listen 443 ssl http2;
+    include snippets/ssl-wildcard-finam-ru.conf;
+    include snippets/ssl-params.conf;
+    ssl_protocols  TLSv1.3;
+}
+
+server {
+    if ($host = {{mcp.domain}}) {
+        return 301 https://$host$request_uri;
+    }
+
+    listen 0.0.0.0:80;
+    server_name {{mcp.domain}};
+    return 404;
+}
+
+#sudo systemctl restart nginx

package/cli-template/deploy/pm2.config.js

@@ -0,0 +1,30 @@
+require('dotenv').config({ path: './.env', debug: true });
+const { name, main } = require('../package.json');
+
+const { SERVICE_NAME, SERVICE_INSTANCE, PM2_NAMESPACE } = process.env;
+const suffix = SERVICE_INSTANCE ? `--${SERVICE_INSTANCE}` : '';
+
+module.exports = {
+  apps: [{
+    name: `${SERVICE_NAME || name}${suffix}`,
+    script: main,
+    node_args: '--no-node-snapshot',
+    // Options reference: https://pm2.keymetrics.io/docs/usage/application-declaration/
+    namespace: PM2_NAMESPACE || undefined,
+    instances: 1,
+    // exec_interpreter: '/root/.nvm/versions/node/v22.17.1/bin/node',
+    exec_mode: 'fork', // Fixing ESM Connection
+    autorestart: true,
+    // restart_delay: 5000,
+    exp_backoff_restart_delay: 100,
+    watch: false,
+    watch_delay: 5000, // Delay between restart
+    // watch: ["server", "client"],
+    ignore_watch: ['.git', '_misc', '_sql', 'deploy', 'node_modules', 'sql', 'tmp'],
+    max_memory_restart: '10G',
+    error_file: `/var/log/pm2/${name}.app.log`,
+    out_file: `/var/log/pm2/${name}.log`,
+    // env_prd: { NODE_ENV: 'production' },
+    // env_dev: { NODE_ENV: 'development' },
+  }],
+};

package/cli-template/deploy/pm2reg.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+c='\033[0;35m'
+y='\033[0;33m'
+c0='\033[0;0m'
+g='\033[0;32m'
+set -e
+
+# Parse arguments
+NODE_ENV="development"
+if [[ "$1" == "-p" || "$1" == "--prod" ]]; then
+  NODE_ENV="production"
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"  # Parent directory (project root)
+
+# Load environment variables from .env if exists
+if [ -f "$PROJECT_ROOT/.env" ]; then
+  source "$PROJECT_ROOT/.env"
+fi
+
+# Get SERVICE_NAME from environment variable or package.json
+if [ -n "$SERVICE_NAME" ]; then
+  # Use environment variable
+  SERVICE_NAME="$SERVICE_NAME"
+else
+  # Read from package.json
+  SERVICE_NAME=`cat "$PROJECT_ROOT/package.json" | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g' | tr -d '[[:space:]]'`
+fi
+if [ -z "$SERVICE_INSTANCE" ]
+then
+  SERVICE="${SERVICE_NAME}"
+else
+  SERVICE="${SERVICE_NAME}--${SERVICE_INSTANCE}"
+fi
+
+echo -e "$g========================================$c0"
+echo -e "$g**** REGISTER SERVICE $y${SERVICE}$g ****$c0"
+echo -e "$g========================================$c0"
+
+# Checking if the service exists in PM2
+if pm2 list | grep -q "$SERVICE"; then
+  echo -e "${g}An existing process was found $y${SERVICE}$g. Deleting..."
+  pm2 delete $SERVICE
+fi
+
+NODE_ENV=$NODE_ENV pm2 startOrRestart "$PROJECT_ROOT/deploy/pm2.config.js"
+pm2 save