fa-mcp-sdk 0.4.76 → 0.4.77

package/cli-template/FA-MCP-SDK-DOC/03-configuration.md

@@ -1,384 +1,384 @@
-# Configuration, Cache, and Access Points
-
-## Custom Startup Diagnostics
-
-You can add custom key-value pairs to the startup diagnostic output by passing `customStartupInfo` to `McpServerData`:
-
-```typescript
-const serverData: McpServerData = {
-  // ... other options
-
-  // Custom startup diagnostic info displayed in the console at server start
-  customStartupInfo: [
-    ['Custom param', 'any value'],
-    ['Environment', process.env.MY_ENV || 'default'],
-    ['Feature Flag', isFeatureEnabled ? 'enabled' : 'disabled'],
-  ],
-};
-```
-
-These values will appear in the startup info block alongside built-in diagnostics like `MCP Auth`, `Admin Auth`, etc.
-
-## Configuration
-
-### appConfig Access
-
-```typescript
-import { appConfig } from 'fa-mcp-sdk';
-
-const port = appConfig.webServer.port;
-const dbEnabled = appConfig.isMainDBUsed;
-const transport = appConfig.mcp.transportType; // 'stdio' | 'http'
-```
-
-### Service Identification
-
-| Variable | Source | Usage |
-|----------|--------|-------|
-| `appConfig.name` | `SERVICE_NAME` env or `package.json.name` | Consul, JWT, logs, MCP server ID |
-| `appConfig.shortName` | name without "mcp" | Cache key prefix |
-| `appConfig.productName` | `PRODUCT_NAME` env or `package.json.productName` | Swagger title, UI header |
-
-### config/default.yaml
-
-```yaml
-accessPoints:
-  myService:
-    title: 'Remote service'
-    host: <host>
-    port: 9999
-    token: '***'
-    noConsul: true
-    consulServiceName: <name>
-
-cache:
-  ttlSeconds: 300
-  maxItems: 1000
-
-consul:
-  check:
-    interval: '10s'
-    timeout: '5s'
-    deregistercriticalserviceafter: '3m'
-  agent:
-    dev:                                # DEV DC credentials
-      dc: '{{consul.agent.dev.dc}}'
-      host: '{{consul.agent.dev.host}}'
-      port: 443
-      secure: true
-      token: '***'
-    prd:                                # PROD DC credentials
-      dc: '{{consul.agent.prd.dc}}'
-      host: '{{consul.agent.prd.host}}'
-      port: 443
-      secure: true
-      token: '***'
-    reg:                                # Service registration
-      host: null                        # null = use current server
-      port: 8500
-      secure: false
-      token: '***'
-  service:
-    enable: {{consul.service.enable}}
-    name: <name>                        # from package.json
-    instance: '{{SERVICE_INSTANCE}}'
-    version: <version>                  # from package.json
-    description: <description>          # from package.json
-    tags: []                            # null/empty = from package.keywords
-    meta:
-      who: 'http://{address}:{port}/'
-  envCode:
-    prod: {{consul.envCode.prod}}
-    dev: {{consul.envCode.dev}}
-
-db:
-  postgres:
-    dbs:
-      main:
-        label: 'My Database'
-        host: ''  # Empty = DB disabled
-        port: 5432
-        database: <database>
-        user: <user>
-        password: <password>
-
-logger:
-  level: info
-  useFileLogger: {{logger.useFileLogger}}
-  dir: '{{logger.dir}}'
-
-mcp:
-  transportType: http  # stdio | http
-  rateLimit:
-    maxRequests: 100
-    windowMs: 60000
-  tools:
-    answerAs: text   # text | structuredContent
-    hideAnnotations: false  # true — strip `annotations` from tool listings
-
-swagger:
-  servers:
-    - url: https://{{mcp.domain}}
-      description: "PROD server"
-
-homePage:
-  helpLink:
-    href: ''        # If empty — help link is not shown in footer
-    text: 'Help'    # Link text (default: "Help")
-  maintainer:
-    href: ''        # If empty — Support link is not shown in footer
-    text: 'Support' # Link text (default: "Help")
-
-uiColor:
-  # Font color of the header and a number of interface elements on the HOME page
-  primary: '#0f65dc'
-
-webServer:
-  host: '0.0.0.0'
-  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: false # Enables/disables 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: '***'
-      # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
-      checkMCPName: true
-      # 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: ''
-      password: '***'
-
-```
-
-## Access Points
-
-If your MCP server talks to third-party / external services (REST APIs, legacy systems, partner endpoints, etc.),
-declare their connection attributes (`host`, `port`, `protocol`, `token`, credentials, custom fields) under the
-top-level `accessPoints` block in the config — **not** scattered through code or ad-hoc config sections. Benefits:
-
-- Single registry of outbound dependencies visible in diagnostics and admin pages.
-- Automatic `host`/`port` resolution via Consul for services registered there.
-- Uniform access pattern (`appConfig.accessPoints.<alias>`) across all tools and modules.
-- Runtime updates — the SDK periodically refreshes dynamic access points from Consul without restarting the server.
-
-The SDK automatically wraps `appConfig.accessPoints` in an `AccessPoints` instance on startup and starts the Consul
-updater — **do not call `new AccessPoints(...)` or `accessPointUpdater.start()` manually**.
-
-### Declaring Access Points
-
-```yaml
-accessPoints:
-  # Dynamic AP — host/port resolved from Consul
-  wso2siAPI:
-    title: 'WSO2 SI API'
-    consulServiceName: 'dev01-wso2si-d2'
-    host: null               # filled in from Consul
-    port: 9443               # fallback; also used when Consul meta specifies a different port
-    protocol: 'https'
-    user: 'admin'
-    pass: '***'
-    myProp: 'anyValue'       # any custom field is preserved and available at runtime
-
-  # Static AP — Consul is NOT used
-  externalAPI:
-    noConsul: true
-    host: 'api.partner.com'
-    port: 443
-    protocol: 'https'
-    token: '***'
-    timeoutMs: 5000
-```
-
-### Using Access Points in Code
-
-```typescript
-import { appConfig } from 'fa-mcp-sdk';
-
-// Direct access — always works, for dynamic and static APs alike
-const ap = appConfig.accessPoints.wso2siAPI;
-const url = `${ap.protocol}://${ap.host}:${ap.port}`;
-const token = ap.token;              // custom fields available
-const custom = ap.myProp;
-
-// "Clean" copy without service fields
-const ap2 = appConfig.accessPoints.getAP('wso2siAPI');
-
-// All access points at once
-const all = appConfig.accessPoints.get();
-
-// For dynamic APs — wait until host/port are resolved from Consul (first run)
-await ap.waitForHostPortUpdated(5000);
-```
-
-**Strict typing for custom fields:**
-
-```typescript
-import type { IAccessPoint } from 'fa-consul';
-
-interface IWso2AP extends IAccessPoint {
-  user: string;
-  pass: string;
-  myProp: string;
-}
-
-const ap = appConfig.accessPoints.wso2siAPI as IWso2AP;
-```
-
-### Access Point Properties
-
-**User-defined (configured in YAML):**
-
-| Property                         | Required        | Purpose                                                                               |
-|----------------------------------|-----------------|---------------------------------------------------------------------------------------|
-| `consulServiceName`              | yes for dynamic | Consul service name used to resolve `host`/`port`                                     |
-| `host`                           | —               | IP/hostname. Dynamic: usually `null`, filled from Consul. Static (`noConsul`): manual |
-| `port`                           | —               | TCP port. Coerced to `Number` or `null`. Dynamic: from Consul (or `meta.port`)        |
-| `protocol`                       | —               | `http` or `https`. Anything other than `https?` is coerced to `http`, lowercased      |
-| `title`                          | —               | Human-readable name (defaults to the AP key)                                          |
-| `noConsul`                       | —               | `true` → static AP: Consul is not polled, `consulServiceName` is not required         |
-| `retrieveProps`                  | —               | `(host, meta) => ({host, port})`. Custom extractor for Consul response                |
-| `updateIntervalIfSuccessMillis`  | —               | Interval between successful Consul polls for this AP (default 2 min)                  |
-| `user`, `pass`, `token`, any key | —               | Application fields — stored as-is and available at runtime                            |
-
-**Service fields (added automatically by the SDK for dynamic APs):**
-
-| Property                     | Purpose                                                                 |
-|------------------------------|-------------------------------------------------------------------------|
-| `id`                         | The AP key from the config                                              |
-| `isAP`                       | Marker for a dynamic AP; absent on `noConsul` APs                       |
-| `meta`                       | Filled from `Service.Meta` of the Consul service on successful poll     |
-| `isReachable`                | `true` if the last Consul poll returned data                            |
-| `lastSuccessUpdate`          | Timestamp of the last successful update                                 |
-| `idHostPortUpdated`          | `true` once `host` + `port` have been populated at least once           |
-| `setProps(data)`             | Method for externally updating AP fields                                |
-| `waitForHostPortUpdated(ms)` | Promise that resolves when `host`/`port` have been populated            |
-| `getChanges()`               | Returns `[propName, oldValue, newValue][]` for the last `setProps` call |
-
-### `noConsul` Access Points
-
-Setting `noConsul: true` makes the access point **static** — its address is not resolved through Consul. Typical use
-cases: partner APIs, legacy systems, or services with fixed addresses that cannot (or should not) be registered in
-Consul.
-
-Differences from a dynamic AP:
-
-- `consulServiceName` is not required.
-- The AP object is stored **as-is** — no normalization of `port`/`protocol`, no service fields (`isAP`, `setProps`,
-  `waitForHostPortUpdated`, etc.) are added.
-- The AP is excluded from Consul polling; `host`/`port` are never overwritten.
-- `getAP('key')` and `get()` do **not** return static APs by default (they filter on `isAP`). Pass `andNotIsAP = true`
-  to include them, or use direct access — `appConfig.accessPoints.externalAPI` — which always works.
-
-```typescript
-appConfig.accessPoints.getAP('externalAPI', true);  // include static AP in lookup
-appConfig.accessPoints.externalAPI;                 // direct access always works
-```
-
-### Custom Fields
-
-Any additional property on an AP (`apiKey`, `timeoutMs`, `headers: {...}`, etc.) is preserved verbatim and accessible at
-runtime:
-
-- On creation, all fields from the config are copied onto the AP object.
-- Periodic Consul updates only refresh `host`/`port` (and optionally `meta`) — other properties are **never
-  overwritten**.
-- `get()` / `getAP()` copy all enumerable properties except `undefined` and functions.
-- Nested objects are copied shallowly — if a custom field is an object, its inner references are shared with the
-  original config.
-- Only `port` (coerced to `Number`) and `protocol` (coerced to `http`/`https`) are normalized; all other fields are
-  left untouched.
-
-### Subscribing to Updates
-
-When a dynamic AP is refreshed from Consul, events are emitted on the SDK's `eventEmitter`
-(see "Event System" in `06-utilities.md`):
-
-```typescript
-import { eventEmitter } from 'fa-mcp-sdk';
-
-eventEmitter.on('access-point-updated', ({ accessPoint, changes }) => {
-  // changes: [propName, oldValue, newValue][]
-});
-eventEmitter.on('access-points-updated', () => { /* any AP was updated this cycle */ });
-```
-
-## Cache
-
-```typescript
-import { getCache } from 'fa-mcp-sdk';
-
-const cache = getCache();  // Default options
-const cache = getCache({ ttlSeconds: 600, maxItems: 5000 });
-
-// Methods
-cache.set('key', value, ttlSeconds?);
-cache.get<T>('key');
-cache.has('key');
-cache.del('key');
-cache.take<T>('key');              // Get and delete
-cache.mget<T>(['k1', 'k2']);
-cache.mset([{ key: 'a', val: 1 }, { key: 'b', val: 2, ttl: 600 }]);
-cache.keys();
-cache.flush();
-cache.ttl('key', seconds);         // Update TTL
-cache.getTtl('key');
-cache.getStats();                  // { hitRate, keys, vsize }
-cache.close();
-
-// Get-or-set pattern
-const data = await cache.getOrSet('key', async () => await fetchData(), 3600);
-```
-
-## Database
-
-PostgreSQL integration (including the `MAIN` sugar layer — `queryMAIN`, `execMAIN`, `getMergeSqlMAIN`,
-`mergeByBatch`, `pgvector` support, etc.) is documented in [09-database.md](09-database.md).
-
-Minimal config snippet (see [09-database.md](09-database.md) for the full reference):
-
-```yaml
-db:
-  postgres:
-    dbs:
-      main:
-        label: 'My Database'
-        host: ''                    # empty string disables DB (isMainDBUsed = false)
-        port: 5432
-        database: <database>
-        user: <user>
-        password: <password>
-        usedExtensions: []          # e.g. [pgvector]
-```
+# Configuration, Cache, and Access Points
+
+## Custom Startup Diagnostics
+
+You can add custom key-value pairs to the startup diagnostic output by passing `customStartupInfo` to `McpServerData`:
+
+```typescript
+const serverData: McpServerData = {
+  // ... other options
+
+  // Custom startup diagnostic info displayed in the console at server start
+  customStartupInfo: [
+    ['Custom param', 'any value'],
+    ['Environment', process.env.MY_ENV || 'default'],
+    ['Feature Flag', isFeatureEnabled ? 'enabled' : 'disabled'],
+  ],
+};
+```
+
+These values will appear in the startup info block alongside built-in diagnostics like `MCP Auth`, `Admin Auth`, etc.
+
+## Configuration
+
+### appConfig Access
+
+```typescript
+import { appConfig } from 'fa-mcp-sdk';
+
+const port = appConfig.webServer.port;
+const dbEnabled = appConfig.isMainDBUsed;
+const transport = appConfig.mcp.transportType; // 'stdio' | 'http'
+```
+
+### Service Identification
+
+| Variable | Source | Usage |
+|----------|--------|-------|
+| `appConfig.name` | `SERVICE_NAME` env or `package.json.name` | Consul, JWT, logs, MCP server ID |
+| `appConfig.shortName` | name without "mcp" | Cache key prefix |
+| `appConfig.productName` | `PRODUCT_NAME` env or `package.json.productName` | Swagger title, UI header |
+
+### config/default.yaml
+
+```yaml
+accessPoints:
+  myService:
+    title: 'Remote service'
+    host: <host>
+    port: 9999
+    token: '***'
+    noConsul: true
+    consulServiceName: <name>
+
+cache:
+  ttlSeconds: 300
+  maxItems: 1000
+
+consul:
+  check:
+    interval: '10s'
+    timeout: '5s'
+    deregistercriticalserviceafter: '3m'
+  agent:
+    dev:                                # DEV DC credentials
+      dc: '{{consul.agent.dev.dc}}'
+      host: '{{consul.agent.dev.host}}'
+      port: 443
+      secure: true
+      token: '***'
+    prd:                                # PROD DC credentials
+      dc: '{{consul.agent.prd.dc}}'
+      host: '{{consul.agent.prd.host}}'
+      port: 443
+      secure: true
+      token: '***'
+    reg:                                # Service registration
+      host: null                        # null = use current server
+      port: 8500
+      secure: false
+      token: '***'
+  service:
+    enable: {{consul.service.enable}}
+    name: <name>                        # from package.json
+    instance: '{{SERVICE_INSTANCE}}'
+    version: <version>                  # from package.json
+    description: <description>          # from package.json
+    tags: []                            # null/empty = from package.keywords
+    meta:
+      who: 'http://{address}:{port}/'
+  envCode:
+    prod: {{consul.envCode.prod}}
+    dev: {{consul.envCode.dev}}
+
+db:
+  postgres:
+    dbs:
+      main:
+        label: 'My Database'
+        host: ''  # Empty = DB disabled
+        port: 5432
+        database: <database>
+        user: <user>
+        password: <password>
+
+logger:
+  level: info
+  useFileLogger: {{logger.useFileLogger}}
+  dir: '{{logger.dir}}'
+
+mcp:
+  transportType: http  # stdio | http
+  rateLimit:
+    maxRequests: 100
+    windowMs: 60000
+  tools:
+    answerAs: text   # text | structuredContent
+    hideAnnotations: false  # true — strip `annotations` from tool listings
+
+swagger:
+  servers:
+    - url: https://{{mcp.domain}}
+      description: "PROD server"
+
+homePage:
+  helpLink:
+    href: ''        # If empty — help link is not shown in footer
+    text: 'Help'    # Link text (default: "Help")
+  maintainer:
+    href: ''        # If empty — Support link is not shown in footer
+    text: 'Support' # Link text (default: "Help")
+
+uiColor:
+  # Font color of the header and a number of interface elements on the HOME page
+  primary: '#0f65dc'
+
+webServer:
+  host: '0.0.0.0'
+  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: false # Enables/disables 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: '***'
+      # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
+      checkMCPName: true
+      # 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: ''
+      password: '***'
+
+```
+
+## Access Points
+
+If your MCP server talks to third-party / external services (REST APIs, legacy systems, partner endpoints, etc.),
+declare their connection attributes (`host`, `port`, `protocol`, `token`, credentials, custom fields) under the
+top-level `accessPoints` block in the config — **not** scattered through code or ad-hoc config sections. Benefits:
+
+- Single registry of outbound dependencies visible in diagnostics and admin pages.
+- Automatic `host`/`port` resolution via Consul for services registered there.
+- Uniform access pattern (`appConfig.accessPoints.<alias>`) across all tools and modules.
+- Runtime updates — the SDK periodically refreshes dynamic access points from Consul without restarting the server.
+
+The SDK automatically wraps `appConfig.accessPoints` in an `AccessPoints` instance on startup and starts the Consul
+updater — **do not call `new AccessPoints(...)` or `accessPointUpdater.start()` manually**.
+
+### Declaring Access Points
+
+```yaml
+accessPoints:
+  # Dynamic AP — host/port resolved from Consul
+  wso2siAPI:
+    title: 'WSO2 SI API'
+    consulServiceName: 'dev01-wso2si-d2'
+    host: null               # filled in from Consul
+    port: 9443               # fallback; also used when Consul meta specifies a different port
+    protocol: 'https'
+    user: 'admin'
+    pass: '***'
+    myProp: 'anyValue'       # any custom field is preserved and available at runtime
+
+  # Static AP — Consul is NOT used
+  externalAPI:
+    noConsul: true
+    host: 'api.partner.com'
+    port: 443
+    protocol: 'https'
+    token: '***'
+    timeoutMs: 5000
+```
+
+### Using Access Points in Code
+
+```typescript
+import { appConfig } from 'fa-mcp-sdk';
+
+// Direct access — always works, for dynamic and static APs alike
+const ap = appConfig.accessPoints.wso2siAPI;
+const url = `${ap.protocol}://${ap.host}:${ap.port}`;
+const token = ap.token;              // custom fields available
+const custom = ap.myProp;
+
+// "Clean" copy without service fields
+const ap2 = appConfig.accessPoints.getAP('wso2siAPI');
+
+// All access points at once
+const all = appConfig.accessPoints.get();
+
+// For dynamic APs — wait until host/port are resolved from Consul (first run)
+await ap.waitForHostPortUpdated(5000);
+```
+
+**Strict typing for custom fields:**
+
+```typescript
+import type { IAccessPoint } from 'fa-consul';
+
+interface IWso2AP extends IAccessPoint {
+  user: string;
+  pass: string;
+  myProp: string;
+}
+
+const ap = appConfig.accessPoints.wso2siAPI as IWso2AP;
+```
+
+### Access Point Properties
+
+**User-defined (configured in YAML):**
+
+| Property                         | Required        | Purpose                                                                               |
+|----------------------------------|-----------------|---------------------------------------------------------------------------------------|
+| `consulServiceName`              | yes for dynamic | Consul service name used to resolve `host`/`port`                                     |
+| `host`                           | —               | IP/hostname. Dynamic: usually `null`, filled from Consul. Static (`noConsul`): manual |
+| `port`                           | —               | TCP port. Coerced to `Number` or `null`. Dynamic: from Consul (or `meta.port`)        |
+| `protocol`                       | —               | `http` or `https`. Anything other than `https?` is coerced to `http`, lowercased      |
+| `title`                          | —               | Human-readable name (defaults to the AP key)                                          |
+| `noConsul`                       | —               | `true` → static AP: Consul is not polled, `consulServiceName` is not required         |
+| `retrieveProps`                  | —               | `(host, meta) => ({host, port})`. Custom extractor for Consul response                |
+| `updateIntervalIfSuccessMillis`  | —               | Interval between successful Consul polls for this AP (default 2 min)                  |
+| `user`, `pass`, `token`, any key | —               | Application fields — stored as-is and available at runtime                            |
+
+**Service fields (added automatically by the SDK for dynamic APs):**
+
+| Property                     | Purpose                                                                 |
+|------------------------------|-------------------------------------------------------------------------|
+| `id`                         | The AP key from the config                                              |
+| `isAP`                       | Marker for a dynamic AP; absent on `noConsul` APs                       |
+| `meta`                       | Filled from `Service.Meta` of the Consul service on successful poll     |
+| `isReachable`                | `true` if the last Consul poll returned data                            |
+| `lastSuccessUpdate`          | Timestamp of the last successful update                                 |
+| `idHostPortUpdated`          | `true` once `host` + `port` have been populated at least once           |
+| `setProps(data)`             | Method for externally updating AP fields                                |
+| `waitForHostPortUpdated(ms)` | Promise that resolves when `host`/`port` have been populated            |
+| `getChanges()`               | Returns `[propName, oldValue, newValue][]` for the last `setProps` call |
+
+### `noConsul` Access Points
+
+Setting `noConsul: true` makes the access point **static** — its address is not resolved through Consul. Typical use
+cases: partner APIs, legacy systems, or services with fixed addresses that cannot (or should not) be registered in
+Consul.
+
+Differences from a dynamic AP:
+
+- `consulServiceName` is not required.
+- The AP object is stored **as-is** — no normalization of `port`/`protocol`, no service fields (`isAP`, `setProps`,
+  `waitForHostPortUpdated`, etc.) are added.
+- The AP is excluded from Consul polling; `host`/`port` are never overwritten.
+- `getAP('key')` and `get()` do **not** return static APs by default (they filter on `isAP`). Pass `andNotIsAP = true`
+  to include them, or use direct access — `appConfig.accessPoints.externalAPI` — which always works.
+
+```typescript
+appConfig.accessPoints.getAP('externalAPI', true);  // include static AP in lookup
+appConfig.accessPoints.externalAPI;                 // direct access always works
+```
+
+### Custom Fields
+
+Any additional property on an AP (`apiKey`, `timeoutMs`, `headers: {...}`, etc.) is preserved verbatim and accessible at
+runtime:
+
+- On creation, all fields from the config are copied onto the AP object.
+- Periodic Consul updates only refresh `host`/`port` (and optionally `meta`) — other properties are **never
+  overwritten**.
+- `get()` / `getAP()` copy all enumerable properties except `undefined` and functions.
+- Nested objects are copied shallowly — if a custom field is an object, its inner references are shared with the
+  original config.
+- Only `port` (coerced to `Number`) and `protocol` (coerced to `http`/`https`) are normalized; all other fields are
+  left untouched.
+
+### Subscribing to Updates
+
+When a dynamic AP is refreshed from Consul, events are emitted on the SDK's `eventEmitter`
+(see "Event System" in `06-utilities.md`):
+
+```typescript
+import { eventEmitter } from 'fa-mcp-sdk';
+
+eventEmitter.on('access-point-updated', ({ accessPoint, changes }) => {
+  // changes: [propName, oldValue, newValue][]
+});
+eventEmitter.on('access-points-updated', () => { /* any AP was updated this cycle */ });
+```
+
+## Cache
+
+```typescript
+import { getCache } from 'fa-mcp-sdk';
+
+const cache = getCache();  // Default options
+const cache = getCache({ ttlSeconds: 600, maxItems: 5000 });
+
+// Methods
+cache.set('key', value, ttlSeconds?);
+cache.get<T>('key');
+cache.has('key');
+cache.del('key');
+cache.take<T>('key');              // Get and delete
+cache.mget<T>(['k1', 'k2']);
+cache.mset([{ key: 'a', val: 1 }, { key: 'b', val: 2, ttl: 600 }]);
+cache.keys();
+cache.flush();
+cache.ttl('key', seconds);         // Update TTL
+cache.getTtl('key');
+cache.getStats();                  // { hitRate, keys, vsize }
+cache.close();
+
+// Get-or-set pattern
+const data = await cache.getOrSet('key', async () => await fetchData(), 3600);
+```
+
+## Database
+
+PostgreSQL integration (including the `MAIN` sugar layer — `queryMAIN`, `execMAIN`, `getMergeSqlMAIN`,
+`mergeByBatch`, `pgvector` support, etc.) is documented in [09-database.md](09-database.md).
+
+Minimal config snippet (see [09-database.md](09-database.md) for the full reference):
+
+```yaml
+db:
+  postgres:
+    dbs:
+      main:
+        label: 'My Database'
+        host: ''                    # empty string disables DB (isMainDBUsed = false)
+        port: 5432
+        database: <database>
+        user: <user>
+        password: <password>
+        usedExtensions: []          # e.g. [pgvector]
+```