fa-mcp-sdk 0.4.17 → 0.4.19

package/cli-template/FA-MCP-SDK-DOC/08-agent-tester-and-headless-api.md

@@ -522,20 +522,31 @@ at-toast-<type>                e.g. at-toast-success, at-toast-error
 | `at-header-row-<name>` | Row for a specific header (e.g. `at-header-row-Authorization`) |
 | `at-header-input-<name>` | Input for a specific header value |
 
-**Sidebar — model settings**
+**Sidebar — LLM settings**
+
+The sidebar shows only the current model name (read-only) and a gear button. All LLM parameters (Base URL, API Key, Model Name, Temperature, Max Tokens, Max Turns, Limit (chars)) are edited in the LLM Settings modal opened via that button. Settings are persisted in `localStorage['mcpAgentLlmSettings']`. If `agentTester.openAi.exposeToClient` is `true` in config, the server sends `baseURL` and `apiKey` via `GET /agent-tester/api/config` → `llmDefaults` and the UI pre-fills them into localStorage on first open (security note: only enable `exposeToClient` when the tester is protected by `useAuth: true` or deployed in a trusted network). When the effective `apiKey` is empty, a red "API Key is not set" warning is shown below the model name.
 
 | testid | Element |
 |---|---|
 | `at-model-section` | Model section container |
-| `at-model-select` | Model `<select>` |
-| `at-custom-model-settings` | "Other..." custom model panel |
-| `at-custom-base-url` | Custom base URL input |
-| `at-custom-api-key` | Custom API key input |
-| `at-custom-model-name` | Custom model name input |
-| `at-model-temperature` | Temperature input |
-| `at-model-max-tokens` | Max tokens input |
-| `at-model-max-turns` | Max turns input |
-| `at-tool-result-limit` | Tool result char limit input |
+| `at-model-display` | Read-only current model name |
+| `at-llm-settings-btn` | Gear button that opens the LLM Settings modal |
+| `at-api-key-warning` | "API Key is not set" warning (visible only when `apiKey` is empty) |
+| `at-llm-modal` | LLM Settings modal overlay |
+| `at-llm-modal-close` | Modal close (×) button |
+| `at-llm-modal-cancel` | Modal Cancel button |
+| `at-llm-modal-save` | Modal Save button |
+| `at-llm-base-url` | Base URL input (optional — empty means OpenAI default) |
+| `at-llm-api-key` | API Key input (password field) |
+| `at-llm-api-key-toggle` | Show/hide API key visibility toggle |
+| `at-llm-model-name` | Model Name input (editable combobox) |
+| `at-llm-model-dropdown-toggle` | Model dropdown arrow button |
+| `at-llm-model-dropdown-list` | Model dropdown list (preset models) |
+| `at-llm-model-option-<name>` | Individual model option inside the list |
+| `at-llm-temperature` | Temperature input |
+| `at-llm-max-tokens` | Max tokens input |
+| `at-llm-max-turns` | Max turns input |
+| `at-llm-limit-chars` | Tool result char limit input |
 
 **Sidebar — prompts**
 

package/cli-template/package.json

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

package/config/_local.yaml

@@ -1,148 +1,312 @@
-# Copy this file to local.yaml and update with your database credentials
-# local.yaml is gitignored and won't be committed
----
-ad:
-  domains:
-    MYDOMAIN:
-      default: true
-      controllers:
-        - 'ldap://c1.corp.com'
-        - 'ldap://c2.corp.com'
-      username: '***'
-      password: '***'
-
-
-agentTester:
-  enabled: true
-  showFooterLink: true  # true (default) — show Agent Tester link in home page footer; false — hide link without disabling tester
-  useAuth: false  # true — apply full multi-auth middleware (permanentTokens/basic/JWT/custom) to /agent-tester routes, same as MCP endpoints
-  sessionTtlMs: 28800000  # Browser login session lifetime in milliseconds. Default: 28800000 (8 hours). Applies only when useAuth is true. Sessions are in-memory on the server — lost on restart.
-  logJson: false  # true — emit structured JSON events (tool_call, tool_result, llm_response, response) to stdout during agent execution
-  openAi:
-    apiKey: ''
-    # baseURL: ''
-  httpHeaders:
-  # Key-value pairs for HTTP requests that should be auto-populated in agentTester
-  # Example: X-User-Id: 12345
-
-
-# --------------------------------------------------
-# CACHING Reduces API calls by caching responses
-# --------------------------------------------------
-cache:
-  # Cache TTL in seconds
-  ttlSeconds: 300
-  # Maximum number of cached items
-  maxItems: 1000
-
-
-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: '{{consul.agent.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: '{{SERVICE_INSTANCE}}' # 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: '' # To exclude the use of the database, you need to set host = ''
-        port: 5432
-        user: your_user
-        password: your_password
-#        usedExtensions:
-#          - pgvector
-
-homePage:
-  helpLink:
-    url: ''          # If empty — help link is not shown in footer
-    label: 'Help'    # Link text (default: "Help")
-
-logger:
-  level: info
-  useFileLogger: {{logger.useFileLogger}} # To use or not to use logging to a file
-  # Absolute path to the folder where logs will be written. Default <proj_root>/../logs
-  dir: '{{logger.dir}}'
-
-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' ]
-  # Authentication is configured here only when accessing the MCP server
-  # Authentication in services that enable tools, resources, and prompts
-  # is implemented more deeply. To do this, you need to use the information passed in HTTP headers
-  # You can also use a custom authorization function
-  auth:
-    enabled: {{webServer.auth.enabled}} # Enables/disables token authorization
-    # ========================================================================
-    # PERMANENT SERVER TOKENS
-    # Static tokens for server-to-server communication
-    # CPU cost: O(1) - fastest authentication method
-    #
-    # To enable this authentication, you need to set auth.enabled = true
-    # and set one token of at least 20 characters in length
-    # ========================================================================
-    permanentServerTokens: [ ] # Add your server tokens here: ['token1', 'token2']
-
-    # ========================================================================
-    # JWT TOKEN WITH SYMMETRIC ENCRYPTION
-    # Custom JWT tokens with AES-256 encryption
-    # CPU cost: Medium - decryption + JSON parsing
-    #
-    # To enable this authentication, you need to set auth.enabled = true and set
-    # encryptKey to at least 20 characters
-    # ========================================================================
-    jwtToken:
-      # Symmetric encryption key to generate a token for this MCP (minimum 8 chars)
-      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}}
-
-    # ========================================================================
-    # Basic Authentication - Base64 encoded username:password
-    # CPU cost: Medium - Base64 decoding + string comparison
-    # To enable this authentication, you need to set auth.enabled = true
-    # and set username and password to valid values
-    # ========================================================================
-    basic:
-      username: ''
-      password: '***'
-
-  # ========================================================================
-  # ADMIN PANEL AUTHENTICATION
-  # Token generation page available at /admin endpoint
-  # Supports 4 authentication methods: permanentServerTokens, basic, jwtToken, ntlm
-  # ========================================================================
-  adminAuth:
-    enabled: true  # Enable/disable admin panel
-    # Authentication type for admin panel: 'permanentServerTokens' | 'basic' | 'jwtToken' | 'ntlm'
-    # For permanentServerTokens, basic, jwtToken - uses credentials from webServer.auth section
-    # For ntlm - uses AD configuration from ad.domains section (no additional credentials needed)
-    type: 'basic'
+# Copy this file to local.yaml and update with your database credentials
+# local.yaml is gitignored and won't be committed
+---
+
+#> ========================================================================
+#> Outbound access points — connection settings for remote services this MCP talks to.
+#> Each entry under accessPoints is keyed by a logical alias used in code to look up host/port/token.
+#> By default, hosts/ports are resolved via Consul; the fields below let you override that or
+#> describe a service that is not registered in Consul at all.
+#> ========================================================================
+# accessPoints:
+#   myService:
+#     #> Human-readable title shown in diagnostics and admin pages
+#     title: 'My remote service'
+#     #> Remote service host (used when noConsul=true or as a fallback)
+#     host: <host>
+#     #> Remote service TCP port
+#     port: 9999
+#     #> Auth token sent to the remote service
+#     token: '***'
+#     #> Use if the service developers do not provide registration in consul —
+#     #> disables Consul lookup and forces use of the host/port above
+#     noConsul: true
+#     #> Override the Consul service name to look up (defaults to the alias key)
+#     consulServiceName: <consulServiceName>
+
+#> Active Directory / LDAP settings.
+#> Used for authentication/authorization (e.g., NTLM in admin panel) and checking user membership in AD groups.
+ad:
+  #> Map of domains. Key is a domain name
+  domains:
+    MYDOMAIN:
+      #> Marks this domain as default one
+      default: true
+      #> List of LDAP controllers (can be multiple for failover).
+      #> Use ldap:// for plain LDAP or ldaps:// for LDAP over TLS.
+      controllers:
+        - 'ldap://c1.corp.com'
+        - 'ldap://c2.corp.com'
+      #> Service account (bind DN or username) used to connect to LDAP.
+      username: '***'
+      #> Service account password.
+      password: '***'
+      #> Base DN for LDAP searches. Auto-derived from controller URL if not set.
+      # baseDn: 'DC=corp,DC=com'
+  #> Cache TTL for group membership checks (default: 600000 = 10 min)
+  # groupCacheTtlMs: 600000
+  #> Cache TTL for user/group DN lookups (default: 86400000 = 24 hours)
+  # dnCacheTtlMs: 86400000
+
+#> Built-in chat UI for testing MCP tools with an LLM.
+agentTester:
+  #> Enables the Agent Tester UI at /agent-tester
+  enabled: true
+  #> true (default) — show Agent Tester link in home page footer; false — hide link without disabling tester
+  showFooterLink: true
+  #> true — protect Agent Tester with full multi-auth (permanentTokens/basic/JWT/custom);
+  #> browser users see a login dialog, headless clients pass Authorization header
+  useAuth: false
+  #> Browser login session lifetime in milliseconds. Default: 28800000 (8 hours).
+  #> Applies only when useAuth is true. Sessions are in-memory on the server — lost on restart.
+  sessionTtlMs: 28800000
+  #> true — emit structured JSON events (tool_call, tool_result, llm_response, response) to stdout during agent execution
+  logJson: false
+  #> OpenAI-compatible LLM credentials used by Agent Tester to drive tool calls
+  openAi:
+    #> API key for LLM provider (OpenAI and compatible)
+    apiKey: ''
+    #> Key name (for logging and debugging)
+    apiKeyName: '***'
+    #> Override base URL for OpenAI-compatible providers (Azure, local LLMs, proxies)
+    baseURL: ''
+    #> -------------------------------------------------------------------------
+    #> When true, baseURL and apiKey are sent to the Agent Tester UI as defaults
+    #> and auto-saved into the browser's localStorage on first open. The UI shows
+    #> them in the LLM Settings dialog. Enable only if the tester is protected by
+    #> useAuth=true OR deployed in a trusted network — otherwise anyone who opens
+    #> /agent-tester can read the key. Default: false (safe).
+    #> -------------------------------------------------------------------------
+    exposeToClient: false
+
+  #> Key-value pairs for HTTP requests that should be auto-populated in agentTester. Example: X-User-Id: 12345
+  httpHeaders:
+
+#> --------------------------------------------------
+#> CACHING Reduces API calls by caching responses
+#> --------------------------------------------------
+cache:
+  #> Time in seconds to check all data and delete expired keys
+  checkPeriod: 1200
+  #> Default maximum number of cached items
+  maxItems: 1000
+  #> Default Cache TTL in seconds
+  ttlSeconds: 300
+
+
+#> Consul service discovery and registration settings
+consul:
+  #> Health check parameters reported to Consul for this service
+  check:
+    #> How often Consul invokes the health check
+    interval: '10s'
+    #> Per-attempt timeout for the health check
+    timeout: '5s'
+    #> Auto-deregister the service after it has been critical for this duration
+    deregistercriticalserviceafter: '3m'
+  agent:
+    #> Credentials for getting information about services in the DEV DC
+    dev:
+      #> DEV datacenter name
+      dc: '{{consul.agent.dev.dc}}'
+      #> DEV consul agent host
+      host: '{{consul.agent.dev.host}}'
+      #> DEV consul agent port
+      port: 443
+      #> Use HTTPS for the DEV consul agent
+      secure: true
+      #> Token for getting information about DEV services
+      token: '{{consul.agent.dev.token}}'
+    #> Credentials for getting information about services in the PROD DC
+    prd:
+      #> PROD datacenter name
+      dc: '{{consul.agent.prd.dc}}'
+      #> PROD consul agent host
+      host: '{{consul.agent.prd.host}}'
+      #> PROD consul agent port
+      port: 443
+      #> Use HTTPS for the PROD consul agent
+      secure: true
+      #> Token for obtaining information about PROD services
+      token: '{{consul.agent.prd.token}}'
+    #> Credentials for registering the service with Consul
+    reg:
+      #> 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
+      host: '{{consul.agent.reg.host}}'
+      #> Consul agent port for registration
+      port: 8500
+      #> Use HTTPS when calling the registration agent
+      secure: false
+      #> Token for registering the service in the consul agent
+      token: '{{consul.agent.reg.token}}'
+  service:
+    #> true — Allows registration of the service with the consul
+    enable: {{consul.service.enable}}
+    #> Here you can specify an alternative name for the service.
+    #> String "<name>" will be replaced by env SERVICE_NAME | <package.json>.name at initialization
+    name: <name>
+    #> This value will be specified as a suffix in the id of the service
+    instance: '{{SERVICE_INSTANCE}}'
+    #> String "<version>" will be replaced by <package.json>.version at initialization
+    version: <version>
+    #> Here you can specify an alternative name description.
+    #> String "<description>" will be replaced by <package.json>.description at initialization
+    description: <description>
+    #> If null or empty array — Will be pulled up from package.keywords at initialization
+    tags: [ ]
+    #> Arbitrary metadata published with the service registration
+    meta:
+      #> "Home" page link template
+      who: 'http://{address}:{port}/'
+  #> Used to generate the service ID
+  envCode:
+    #> Production environment code
+    prod: '{{consul.envCode.prod}}'
+    #> Development environment code
+    dev: '{{consul.envCode.dev}}'
+
+#> Database connections used by the service
+db:
+  #> PostgreSQL connection pool definitions
+  postgres:
+    #> Map of named PostgreSQL databases (key is a logical alias used in code)
+    dbs:
+      main:
+        #> Human-readable label shown in diagnostics and admin pages
+        label: 'Your Database Label'
+        #> To exclude the use of the database, you need to set host = ''
+        host: ''
+        #> PostgreSQL server port
+        port: 5432
+        #> Database name
+        database: your_database
+        #> Database user
+        user: your_user
+        #> Database password
+        password: your_password
+        #> List of PostgreSQL extensions required by the service (e.g., 'pgvector', 'uuid-ossp')
+        usedExtensions: []
+        #  - pgvector
+
+
+#> Logging configuration (tslog-based)
+logger:
+  #> Minimum log level: silly | trace | debug | info | warn | error | fatal
+  level: info
+  #> To use or not to use logging to a file
+  useFileLogger: {{logger.useFileLogger}}
+  #> Absolute path to the folder where logs will be written. Default <proj_root>/../logs
+  dir: '{{logger.dir}}'
+
+#> MCP (Model Context Protocol) server settings
+mcp:
+  #> Transport for the MCP server: stdio | http
+  transportType: 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
+  #> Per-client request rate limiting for the MCP endpoint
+  rateLimit:
+    #> Maximum number of requests allowed within windowMs
+    maxRequests: 100
+    #> Rate limit window length in milliseconds (1 minute)
+    windowMs: 60000
+
+#> Swagger / OpenAPI documentation settings
+swagger:
+  #> An array of servers that will be added to swagger docs
+  servers:
+    # - url: http://localhost:{{port}}
+    #   description: "Development server (localhost)"
+    # - url: http://0.0.0.0:{{port}}
+    #   description: "Development server (all interfaces)"
+    # - url: http://<prod_server_host_or_ip>:{{port}}
+    #   description: "PROD server"
+    - url: http://localhost:{{port}}
+      description: "Local server"
+
+#> Service home page (`/`) customization
+homePage:
+  #> Optional help link rendered in the home page footer
+  helpLink:
+    #> If empty — help link is not shown in footer
+    url: ''
+    #> Link text (default: "Help")
+    label: 'Help'
+
+#> UI theme overrides for built-in pages (home, admin, agent-tester)
+uiColor:
+  #> Font color of the header and a number of interface elements on the HOME page
+  primary: '#0f65dc'
+
+#> HTTP server hosting MCP, admin panel, agent tester, swagger and health endpoints
+webServer:
+  #> Bind address for the HTTP server
+  host: '0.0.0.0'
+  #> TCP port for the HTTP server
+  port: {{port}}
+  #> Array of hosts that CORS skips
+  originHosts: [ 'localhost', '0.0.0.0' ]
+  #> ========================================================================
+  #> Authentication is configured here only when accessing the MCP server.
+  #> Authentication in services that enable tools, resources, and prompts
+  #> is implemented more deeply. To do this, you need to use the information passed in HTTP headers.
+  #> You can also use a custom authorization function.
+  #> ========================================================================
+  auth:
+    #> Enables/disables authorization
+    enabled: {{webServer.auth.enabled}}
+    #> ========================================================================
+    #> PERMANENT SERVER TOKENS
+    #> Static tokens for server-to-server communication
+    #> CPU cost: O(1) — fastest authentication method
+    #>
+    #> To enable this authentication, you need to set auth.enabled = true
+    #> and set one token of at least 20 characters in length
+    #> ========================================================================
+    #> Add your server tokens here: ['token1', 'token2']
+    permanentServerTokens: [ ]
+
+    #> ========================================================================
+    #> JWT TOKEN WITH SYMMETRIC ENCRYPTION
+    #> Custom JWT tokens with AES-256 encryption
+    #> CPU cost: Medium — decryption + JSON parsing
+    #>
+    #> To enable this authentication, you need to set auth.enabled = true and set
+    #> encryptKey to at least 20 characters
+    #> ========================================================================
+    jwtToken:
+      #> Symmetric encryption key to generate a token for this MCP (minimum 8 chars)
+      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}}
+      #> If true and JWT token contains non-empty 'ip' field,
+      #> the client IP will be checked against the allowed list in the token
+      isCheckIP: false
+
+    #> ========================================================================
+    #> Basic Authentication — Base64 encoded username:password
+    #> CPU cost: Medium — Base64 decoding + string comparison
+    #> To enable this authentication, you need to set auth.enabled = true
+    #> and set username and password to valid values
+    #> ========================================================================
+    basic:
+      #> Username for HTTP Basic auth
+      username: ''
+      #> Password for HTTP Basic auth
+      password: '***'
+
+  #> ========================================================================
+  #> 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'
+    #> For permanentServerTokens, basic, jwtToken — uses credentials from webServer.auth section
+    #> For ntlm — uses AD configuration from ad.domains section (no additional credentials needed)
+    type: 'basic'