fa-mcp-sdk 0.4.67 → 0.4.69

package/cli-template/FA-MCP-SDK-DOC/00-FA-MCP-SDK-index.md

@@ -15,12 +15,13 @@ npm install fa-mcp-sdk
 | [01-getting-started](01-getting-started.md) | `initMcpServer()`, `McpServerData`, `IPromptData`, `IResourceData`, `AppConfig` | Starting new project |
 | [02-1-tools-and-api](02-1-tools-and-api.md) | Tool definitions, `toolHandler`, outbound webhooks, REST API with tsoa, OpenAPI/Swagger | Creating tools, REST endpoints, webhook callbacks |
 | [02-2-prompts-and-resources](02-2-prompts-and-resources.md) | Standard/custom prompts, resources, `requireAuth` | Configuring prompts/resources |
-| [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points for external services, cache, PostgreSQL | Server configuration, external services, DB |
+| [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points for external services, cache | Server configuration, external services |
 | [04-authentication](04-authentication.md) | JWT, Basic auth, server tokens, `createAuthMW()`, Token Generator, CLI Token Generator, JWT Generation API | Authentication setup |
 | [05-ad-authorization](05-ad-authorization.md) | AD group authorization at HTTP/tool levels | AD group restrictions |
 | [06-utilities](06-utilities.md) | `ServerError`, `normalizeHeaders`, logging, Consul, graceful shutdown | Error handling, utilities |
 | [07-testing-and-operations](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE, Streamable HTTP) | Testing, deployment |
 | [08-agent-tester-and-headless-api](08-agent-tester-and-headless-api.md) | Agent Tester, Headless API, structured logging, automated testing, UI `data-testid` reference | Agent-driven tool development, CLI automation, UI E2E tests |
+| [09-database](09-database.md) | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, `getInsertSqlMAIN`, `getMergeSqlMAIN`, `mergeByBatch`), `pgvector`, secondary DBs | Database access, upserts, batching |
 
 ## Key Exports
 
@@ -35,7 +36,13 @@ import { createAuthMW, generateToken, getAuthHeadersForTests, TTokenType, genera
 import { formatToolResult, ToolExecutionError, ServerError, BaseMcpError, ValidationError, getTools } from 'fa-mcp-sdk';
 
 // Database & Cache
-import { queryMAIN, execMAIN, oneRowMAIN, checkMainDB, getCache } from 'fa-mcp-sdk';
+import {
+  queryMAIN, queryRsMAIN, oneRowMAIN, execMAIN,
+  getInsertSqlMAIN, getMergeSqlMAIN, mergeByBatch,
+  checkMainDB, getMainDBConnectionStatus,
+  IQueryPgArgsCOptional,
+  getCache,
+} from 'fa-mcp-sdk';
 
 // Utilities
 import { logger, fileLogger, Logger, trim, ppj, toError, toStr, normalizeHeaders } from 'fa-mcp-sdk';

package/cli-template/FA-MCP-SDK-DOC/02-1-tools-and-api.md

@@ -62,65 +62,208 @@ const clientIP = headers?.['x-real-ip'] || headers?.['x-forwarded-for'];
 `IToolHandlerParams` includes `ITransportContext` fields (`transport`, `headers`, `payload`).
 See [ITransportContext](./02-2-prompts-and-resources.md#itransportcontext).
 
-### Outbound Webhooks
+### Outbound Webhooks (`x-web-hook`)
 
-The SDK does not ship a built-in webhook — it is a **handler-level pattern** enabled by
-the fact that `params.headers` already carries every client header through to the tool.
-Use it when the caller should be notified of each tool result (audit, dashboards, CI
-chains). Reference implementation: `mcp-jira` (`src/tools/tools-manager.ts`,
-`callWebHook` + dispatch block).
+Handler-level pattern. The SDK does **not** ship a built-in webhook dispatcher — it exposes
+everything you need (`params.headers`, `appConfig`, `logger`) and leaves the policy to the project.
+This section is the **canonical recipe**: implement it as written so every fa-mcp-sdk-based MCP
+server behaves the same way for clients and downstream collectors.
 
-**Recipe:**
+**What it is:** after every tool invocation the server can `POST` the tool result to an external
+URL. Useful for audit trails, real-time dashboards, chaining MCP calls into CI/automation pipelines.
+Opt-in per request (via header) and optionally per tool (via the response object). A failing webhook
+**must never** fail the tool call.
 
-1. **Declare the header** so Agent Tester and `use://http-headers` advertise it:
+#### Contract (stable across all MCPs)
 
-   ```typescript
-   usedHttpHeaders: [
-     { name: 'x-web-hook', description: 'URL to POST the tool result to.', isOptional: true },
-   ],
-   ```
+**Inbound — precedence:**
 
-2. **Dispatch inside the handler** — fire-and-forget, never throw, never block the reply:
+| Source              | Form                                                    | Precedence |
+|---------------------|---------------------------------------------------------|------------|
+| Per-tool override   | `IToolResponse.hook: string` returned by the handler    | wins       |
+| Per-request header  | `x-web-hook: <http(s) URL>`                             | fallback   |
 
-   ```typescript
-   import axios from 'axios';
-   import { appConfig, logger, toStr, IToolHandlerParams } from 'fa-mcp-sdk';
+If neither is present, no webhook fires.
 
-   const URL_REGEX = /^https?:\/\/[^\s]+$/i;
+**Outbound request:**
 
-   const callWebHook = (url: string, tool: string, response: unknown, user?: string): void => {
-     if (!URL_REGEX.test(url)) { return; }
-     axios.post(url, { mcpName: appConfig.name, tool, user, response }, { timeout: 10_000 })
-       .catch((err) => logger.warn(`Web-hook POST ${url} failed: ${toStr(err?.message || err)}`));
-   };
+- Method: `POST`, `Content-Type: application/json`, timeout ≤ 10 000 ms
+- Body:
 
-   export const handleToolCall = async (params: IToolHandlerParams) => {
-     const { name, headers = {} } = params;
-     const result = await runTool(params);                // produce { text, json, hook? }
-     const hookUrl = (result.hook || headers['x-web-hook'] || '').trim();
-     if (hookUrl) { callWebHook(hookUrl, name, result.json, resolveUser(headers, params.payload)); }
-     return formatToolResult(result.json);
-   };
-   ```
+```json
+{
+  "mcpName": "<appConfig.name>",
+  "tool": "<tool_name>",
+  "user": "<caller-id-or-omitted>",
+  "response": { "...": "tool's full JSON result" }
+}
+```
+
+| Field      | Description                                                                  |
+|------------|------------------------------------------------------------------------------|
+| `mcpName`  | `appConfig.name` — identifies which MCP sent the callback                    |
+| `tool`     | Name of the invoked tool                                                     |
+| `user`     | Best-effort caller identity (see *User resolution*); **omit** if unresolved  |
+| `response` | Full JSON returned by the tool handler (same payload sent to the client)     |
+
+Do **not** add ad-hoc fields on a per-project basis without versioning the body — downstream
+collectors rely on this exact shape.
+
+#### Implementation recipe
+
+**1. Declare the header** so `use://http-headers`, Agent Tester, and tool-call introspection
+advertise it:
+
+```typescript
+// src/start.ts
+usedHttpHeaders.push({
+  name: 'x-web-hook',
+  description:
+    'Optional URL called via POST after each tool invocation. '
+    + 'Body: { mcpName, tool, user, response }. Fire-and-forget; failures are logged only.',
+  isOptional: true,
+});
+```
+
+**2. Add `hook?` to the internal tool-response type** (lets a handler override the URL per tool):
+
+```typescript
+// src/_types_/tool.ts
+export interface IToolResponse {
+  text: string;
+  json: Record<string, any>;
+  hook?: string; // per-tool URL override; takes precedence over x-web-hook header
+}
+```
+
+**3. Dispatcher — fire-and-forget, never throws:**
+
+```typescript
+// src/tools/tools-manager.ts
+import axios from 'axios';
+import { appConfig, logger as lgr, toStr } from 'fa-mcp-sdk';
+
+const logger = lgr.getSubLogger({ name: 'tools' });
+const URL_REGEX = /^https?:\/\/[^\s]+$/i;
+
+const callWebHook = (
+  url: string,
+  toolName: string,
+  json: Record<string, any>,
+  user?: string,
+): void => {
+  if (!URL_REGEX.test(url)) { return; }                 // silently drop garbage URLs
+  const body = { mcpName: appConfig.name, tool: toolName, response: json, user };
+  axios.post(url, body, { timeout: 10_000 })
+    .catch((err) => logger.warn(`Web-hook POST ${url} failed: ${toStr(err?.message || err)}`));
+};
+```
+
+Rules:
 
-3. **Per-tool override (optional)** — let a tool return its own `hook` URL that wins over
-   the client header. Extend your internal tool-response type:
+- **No `await`.** The webhook must not delay the MCP response.
+- **No re-throws.** A 5xx, timeout, or DNS failure is a `warn` log, nothing more.
+- **URL allow-list.** At minimum, require `http(s)://`. Add an internal-net allow-list via config
+  (e.g. `webhook.allowedHosts`) if the threat model requires it (see *Security*).
 
-   ```typescript
-   export interface IToolResponse { text: string; json: Record<string, any>; hook?: string; }
-   ```
+**4. Wire it into the tool-call entry point** — dispatch after the handler resolves and before
+the result is returned:
 
-**Body contract** (recommended; keep stable across tools):
+```typescript
+export const handleToolCall = async (params: IToolHandlerParams): Promise<any> => {
+  const { name: toolName, arguments: args, headers: mcpRequestHeaders = {} } = params;
+
+  const tool = (await getTools(mcpRequestHeaders)).get(toolName);
+  if (!tool?.handler) { throw new ToolExecutionError(toolName, `Unknown tool: ${toolName}`); }
+
+  const ctx: ToolContext = {
+    httpClient: createHttpClient(mcpRequestHeaders),
+    logger: logger.getSubLogger({ name: toolName }),
+    mcpRequestHeaders,
+  };
+
+  const toolResponse: IToolResponse = await tool.handler(args, ctx);
+
+  // ─── webhook dispatch (fire-and-forget) ─────────────────────────────────────
+  const hookUrl = (toolResponse?.hook || mcpRequestHeaders['x-web-hook'] || '').trim();
+  if (hookUrl) {
+    const syncUser = resolveActualUser(mcpRequestHeaders);     // see step 5
+    if (syncUser) {
+      callWebHook(hookUrl, toolName, toolResponse.json, syncUser);
+    } else {
+      // Async user resolution — still fire-and-forget; do not block the tool response.
+      getCachedSelfUser(ctx.httpClient, mcpRequestHeaders)
+        .then((u) => callWebHook(hookUrl, toolName, toolResponse.json, u));
+    }
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
+  return formatToolResult(toolResponse);
+};
+```
 
-| Field | Description |
-|-------|-------------|
-| `mcpName` | `appConfig.name` — which MCP sent the callback |
-| `tool` | Tool name that was invoked |
-| `user` | Caller identity (JWT `payload.user`, auth header, or a lookup — project-specific) |
-| `response` | Full JSON the tool produced |
+**5. User resolution — best-effort, two-step.** The `user` field is what makes the webhook useful
+for audit. Resolve carefully, but never let resolution fail the call.
+
+- **Step A — Sync (preferred):** derive from headers / JWT payload / config without I/O
+  (e.g. JWT `payload.user`, a custom `x-actual-user` header your auth layer stamps, etc.).
+- **Step B — Async fallback (only when sync returns nothing):** call the upstream "who am I"
+  endpoint with the same auth, **cache the result** (recommended TTL: 1 h, key by hashed
+  `Authorization`), and dedupe in-flight requests (thundering-herd protection).
+- If both steps fail → **omit** the `user` field. Never invent a placeholder like `"unknown"`.
+
+```typescript
+export function resolveActualUser (headers: Record<string, string>): string | undefined { /* … */ }
+
+export const getCachedSelfUser = async (
+  httpClient: AxiosInstance,
+  headers: Record<string, string>,
+): Promise<string | undefined> => { /* GET /me, cache by hashed Authorization, dedupe */ };
+```
+
+#### Per-tool override — when to use
+
+A handler may force a specific webhook URL:
+
+```typescript
+return { text, json, hook: 'https://collector.internal/special' };
+```
 
-**Rules of thumb:** validate the URL (`http(s)://…`), short timeout (≤10 s), catch+log
-only, **never** `await` the POST, and never let a webhook failure surface as a tool error.
+Use sparingly. Legitimate cases:
+
+- a long-running tool whose result feeds a fixed pipeline regardless of the client;
+- a tool that should **never** webhook (e.g. read of a secret) — return `hook: ''` only if the
+  dispatcher treats empty string as "skip even if header is set". With the snippet above this works
+  naturally because `(toolResponse?.hook || header)` short-circuits on any truthy `hook`; to force
+  skip, have the handler strip the header from `ctx` or short-circuit `hookUrl` explicitly.
+
+If neither applies, do not set `hook` — let the client decide.
+
+#### Security
+
+- **URL validation** — reject anything that does not match `http(s)://…`. For public-facing MCPs,
+  restrict to a configured allow-list (`webhook.allowedHosts` in `config/default.yaml`).
+- **SSRF surface** — the webhook is a server-side `POST` to a client-supplied URL. Acceptable for
+  trusted MCP clients; not acceptable open on the internet without an allow-list.
+- **No secrets in the body** — `response` is the same JSON the client already received. Do **not**
+  add credentials, raw tokens, or PII not present in the response.
+- **No retries** — duplicate POSTs to a flaky collector are worse than a missed event. If the
+  collector needs guarantees, let it poll.
+- **Logging** — log `tool`, target host, and outcome at `warn`/`debug`; **never** log the full body
+  at `info` level (audit log noise + potential PII).
+
+#### Testing checklist
+
+- [ ] Header declared in `usedHttpHeaders` and visible at `/use://http-headers`.
+- [ ] Tool call **without** `x-web-hook` → no outbound POST.
+- [ ] Tool call **with** valid `x-web-hook` → exactly one POST, body matches the contract above.
+- [ ] Collector returns 500 → tool response still succeeds; one `warn` line in the log.
+- [ ] Collector hangs → tool response returns within normal latency; POST aborts at 10 s.
+- [ ] Malformed URL (`javascript:…`, missing scheme) → no POST, no error to client.
+- [ ] Per-tool `hook` set → wins over the header.
+- [ ] Sync user resolution hits → `user` populated immediately, no extra HTTP call.
+- [ ] Sync empty, async succeeds → POST fires after `/me` resolves; tool response was not delayed.
+- [ ] Both user paths fail → POST fires with `user` **field omitted** (not `null`, not `"unknown"`).
 
 
 ## REST API Endpoints

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

@@ -1,4 +1,4 @@
-# Configuration, Cache, and Database
+# Configuration, Cache, and Access Points
 
 ## Custom Startup Diagnostics
 
@@ -362,151 +362,23 @@ cache.close();
 const data = await cache.getOrSet('key', async () => await fetchData(), 3600);
 ```
 
-## Database Integration
+## Database
 
-To disable the use of the database, you need to set appConfig.db.postgres.dbs.main.host to an empty value.
-In this case, when the configuration is formed, appConfig.isMainDBUsed is set to false.
+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):
 
-If you enable database support (`isMainDBUsed: true` in config):
-
-```typescript
-import { queryMAIN, execMAIN, oneRowMAIN, queryRsMAIN, checkMainDB } from 'fa-mcp-sdk';
-
-// Check database connection. If there is no connection, the application stops
-await checkMainDB();
-
-// queryMAIN - the main function of executing SQL queries to the main database
-
-// Function Signature:
-const queryMAIN = async <R extends QueryResultRow = any> (
-        arg: string | IQueryPgArgsCOptional,
-        sqlValues?: any[],
-        throwError = false,
-): Promise<QueryResult<R> | undefined> {...}
-
-// Types used:
-export interface IQueryPgArgs {
-   connectionId: string,
-   poolConfig?: PoolConfig & IDbOptionsPg,
-   client?: IPoolPg,
-   sqlText: string,
-   sqlValues?: any[],
-   throwError?: boolean,
-   prefix?: string,
-   registerTypesFunctions?: IRegisterTypeFn[],
-}
-export interface IQueryPgArgsCOptional extends Omit<IQueryPgArgs, 'connectionId'> {
-   connectionId?: string
-}
-
-// Examples of use
-const users1 = await queryMAIN('SELECT * FROM users WHERE active = $1', [true]);
-// Alternative use case
-const users2 = await queryMAIN({ sqlText: 'SELECT * FROM users WHERE active = $1', sqlValues: [true] });
-
-
-// execMAIN - execute SQL commands without returning result set
-// Function Signature:
-const execMAIN = async (
-  arg: string | IQueryPgArgsCOptional,
-): Promise<number | undefined> {...}
-
-// Examples:
-await execMAIN({ sqlText: 'INSERT INTO logs (message, created_at) VALUES ($1, $2)', sqlValues: ['Server started', new Date()] });
-await execMAIN({ sqlText: 'UPDATE users SET active = $1 WHERE id = $2', sqlValues: [false, userId] });
-
-// queryRsMAIN - execute SQL and return rows array directly
-// Function Signature:
-const queryRsMAIN = async <R extends QueryResultRow = any> (
-  arg: string | IQueryPgArgsCOptional,
-  sqlValues?: any[],
-  throwError = false,
-): Promise<R[] | undefined> {...}
-
-// Example:
-const users = await queryRsMAIN<User>('SELECT * FROM users WHERE active = $1', [true]);
-
-// oneRowMAIN - execute SQL and return single row
-// Function Signature:
-const oneRowMAIN = async <R extends QueryResultRow = any> (
-  arg: string | IQueryPgArgsCOptional,
-  sqlValues?: any[],
-  throwError = false,
-): Promise<R | undefined> {...}
-
-// Example:
-const user = await oneRowMAIN<User>('SELECT * FROM users WHERE id = $1', [userId]);
-
-// getMainDBConnectionStatus - check database connection status
-// Function Signature:
-const getMainDBConnectionStatus = async (): Promise<string> {...}
-
-// Possible return values: 'connected' | 'disconnected' | 'error' | 'db_not_used'
-const status = await getMainDBConnectionStatus();
-
-// checkMainDB - verify database connectivity (stops application if failed)
-// Function Signature:
-const checkMainDB = async (): Promise<void> {...}
-
-// Example:
-await checkMainDB(); // Throws or exits process if DB connection fails
-
-// getInsertSqlMAIN - generate INSERT SQL statement
-// Function Signature:
-const getInsertSqlMAIN = async <U extends TDBRecord = TDBRecord> (arg: {
-  commonSchemaAndTable: string,
-  recordset: TRecordSet<U>,
-  excludeFromInsert?: string[],
-  addOutputInserted?: boolean,
-  isErrorOnConflict?: boolean,
-  keepSerialFields?: boolean,
-}): Promise<string> {...}
-
-// Example:
-const insertSql = await getInsertSqlMAIN({
-  commonSchemaAndTable: 'public.users',
-  recordset: [{ name: 'John', email: 'john@example.com' }],
-  addOutputInserted: true
-});
-
-// getMergeSqlMAIN - generate UPSERT (INSERT...ON CONFLICT) SQL statement
-// Function Signature:
-const getMergeSqlMAIN = async <U extends TDBRecord = TDBRecord> (arg: {
-  commonSchemaAndTable: string,
-  recordset: TRecordSet<U>,
-  conflictFields?: string[],
-  omitFields?: string[],
-  updateFields?: string[],
-  fieldsExcludedFromUpdatePart?: string[],
-  noUpdateIfNull?: boolean,
-  mergeCorrection?: (_sql: string) => string,
-  returning?: string,
-}): Promise<string> {...}
-
-// Example:
-const mergeSql = await getMergeSqlMAIN({
-  commonSchemaAndTable: 'public.users',
-  recordset: [{ id: 1, name: 'John Updated', email: 'john@example.com' }],
-  conflictFields: ['email'],
-  returning: '*'
-});
-
-// mergeByBatch - execute merge operations in batches
-// Function Signature:
-const mergeByBatch = async <U extends TDBRecord = TDBRecord> (arg: {
-  recordset: TRecordSet<U>,
-  getMergeSqlFn: Function
-  batchSize?: number
-}): Promise<any[]> {...}
-
-// Example:
-const results = await mergeByBatch({
-  recordset: largeDataSet,
-  getMergeSqlFn: (batch) => getMergeSqlMAIN({
-    commonSchemaAndTable: 'public.users',
-    recordset: batch
-  }),
-  batchSize: 500
-});
+```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]
 ```

package/cli-template/FA-MCP-SDK-DOC/09-database.md

@@ -0,0 +1,295 @@
+# PostgreSQL Database
+
+The SDK wraps [`af-db-ts`](https://www.npmjs.com/package/af-db-ts) with a thin sugar layer bound to a single
+logical connection — `main`. All helper functions below are pre-configured with `connectionId = 'main'`,
+automatically register `pgvector` when the extension is enabled, and normalize the call shape (SQL string or
+full argument object).
+
+For the vast majority of MCP servers **only the sugar layer is needed** — direct `af-db-ts` calls are
+reserved for edge cases (secondary databases, transactions on an explicit client, cursor streaming,
+cross-DB migration).
+
+## 1. Enabling / Disabling the Database
+
+Database support is driven entirely by `config/*.yaml`. The SDK computes `appConfig.isMainDBUsed` at startup
+based on whether a host is configured:
+
+```yaml
+db:
+  postgres:
+    dbs:
+      main:
+        label: 'My Database'        # shown in diagnostics and admin pages
+        host: ''                    # empty string disables DB (isMainDBUsed = false)
+        port: 5432
+        database: <database>
+        user: <user>
+        password: <password>
+        usedExtensions: []          # e.g. [pgvector]
+```
+
+- `host: ''` — DB is disabled. `getMainDBConnectionStatus()` returns `'db_not_used'`; the `MAIN` helpers
+  are not meant to be called in this state.
+- `host: <value>` — DB is enabled. Call `await checkMainDB()` early in startup so a misconfigured server
+  fails fast instead of returning 500s later.
+
+### Enabling `pgvector`
+
+```yaml
+db:
+  postgres:
+    dbs:
+      main:
+        # ...
+        usedExtensions:
+          - pgvector
+```
+
+When `pgvector` is listed, the SDK automatically injects `pgvector.registerType` into every `queryMAIN`
+call, so `vector` columns come back as `number[]` with no per-call setup.
+
+## 2. Sugar Layer — the `MAIN` Family
+
+All imports come from `fa-mcp-sdk`:
+
+```typescript
+import {
+  queryMAIN, queryRsMAIN, oneRowMAIN, execMAIN,
+  getInsertSqlMAIN, getMergeSqlMAIN, mergeByBatch,
+  checkMainDB, getMainDBConnectionStatus,
+  IQueryPgArgsCOptional,
+} from 'fa-mcp-sdk';
+```
+
+Every query-style helper accepts **two call shapes**:
+
+1. `fn(sqlText, sqlValues?, throwError?)` — shortest form, preferred for most reads.
+2. `fn({ sqlText, sqlValues, throwError, client, ... })` — full `IQueryPgArgsCOptional` object, needed when
+   you want to pass `client` (external pool client for transactions), a log `prefix`, or other advanced
+   options.
+
+### 2.1. `queryMAIN<R>(arg, sqlValues?, throwError?)`
+
+Returns the full `QueryResult<R>` (`rows`, `rowCount`, `fields`, …) or `undefined` on error when
+`throwError=false`.
+
+```typescript
+// Prepared parameters — always preferred for user input
+const res = await queryMAIN<{ id: number; email: string }>(
+  `SELECT id, email FROM public.users WHERE active = $1 ORDER BY id`,
+  [true],
+);
+const firstEmail = res?.rows?.[0]?.email;
+
+// Object form — e.g. inside an externally-opened transaction
+await queryMAIN({ client, sqlText: `TRUNCATE TABLE public.staging;` });
+```
+
+### 2.2. `queryRsMAIN<R>(arg, sqlValues?, throwError?)`
+
+"Rows only" — returns `R[] | undefined`. Use in ~90% of reads when metadata isn't needed.
+
+```typescript
+const rows = await queryRsMAIN<{ userId: number }>(
+  `SELECT "userId" FROM public.sessions WHERE "expiresAt" > NOW()`,
+);
+const ids = new Set((rows || []).map((r) => r.userId));
+```
+
+### 2.3. `oneRowMAIN<R>(arg, sqlValues?, throwError?)`
+
+Returns the first row or `undefined` — the most readable form for look-ups.
+
+```typescript
+const user = await oneRowMAIN<{ id: number; role: string }>(
+  `SELECT id, role FROM public.users WHERE email = $1`,
+  [email],
+);
+if (!user) throw new Error('User not found');
+```
+
+### 2.4. `execMAIN(arg): Promise<number | undefined>`
+
+For DDL/DML without consuming rows. Returns `rowCount` (or the **sum** of `rowCount` for batch SQL
+concatenated with `;`). Handy for "how many rows did I affect" counters and for transaction primitives.
+
+```typescript
+// Single statement
+await execMAIN(`UPDATE public.jobs SET status = 'done' WHERE id = ${jobId}`);
+
+// Batch UPDATE — sum of rowCount across ;-separated statements
+const sqls = await Promise.all(items.map((it) => buildUpdateSql(it)));
+const affected = await execMAIN(sqls.join('\n'));
+
+// Transaction primitives — simple flow on the cached pool
+try {
+  await execMAIN({ sqlText: 'BEGIN' });
+  // ... writes via queryMAIN / execMAIN ...
+  await execMAIN({ sqlText: 'COMMIT' });
+} catch (err) {
+  await execMAIN({ sqlText: 'ROLLBACK' });
+  throw err;
+}
+```
+
+### 2.5. `getInsertSqlMAIN<U>(arg): Promise<string>`
+
+Generates an `INSERT` statement from table metadata — the recordset is filtered against the table schema,
+so fields that don't exist in the table are silently dropped. Pair with `queryMAIN` to execute.
+
+| Field                  | Purpose                                                                           |
+|------------------------|-----------------------------------------------------------------------------------|
+| `commonSchemaAndTable` | `'schema.table'`                                                                  |
+| `recordset`            | `TRecordSet<U>` — rows to insert                                                  |
+| `excludeFromInsert`    | Columns to skip (typically the auto-increment PK)                                 |
+| `addOutputInserted`    | Append `RETURNING *` to get generated ids / defaults                              |
+| `isErrorOnConflict`    | Throw on uniqueness violation (default: swallowed)                                |
+| `keepSerialFields`     | Do **not** drop `serial` values from the recordset (used when migrating ids)      |
+
+```typescript
+const sql = await getInsertSqlMAIN({
+  commonSchemaAndTable: 'public.users',
+  recordset: [{ name: 'John', email: 'john@example.com' }],
+  excludeFromInsert: ['id'],       // PK is auto-increment
+  addOutputInserted: true,
+});
+const res = await queryMAIN<{ id: number; name: string }>(sql, undefined, true);
+const created = res?.rows?.[0];
+```
+
+### 2.6. `getMergeSqlMAIN<U>(arg): Promise<string>`
+
+Generates an upsert — `INSERT ... ON CONFLICT (...) DO UPDATE ...`.
+
+| Field                          | Purpose                                                                                       |
+|--------------------------------|-----------------------------------------------------------------------------------------------|
+| `commonSchemaAndTable`         | `'schema.table'`                                                                              |
+| `recordset`                    | `TRecordSet<U>` — rows to upsert                                                              |
+| `conflictFields`               | Columns for `ON CONFLICT (...)`. Defaults to the PK                                           |
+| `omitFields`                   | Excluded from both `INSERT` and `UPDATE` (no effect when `updateFields` is set explicitly)    |
+| `updateFields`                 | If set — only these fields appear in `DO UPDATE` (minus `fieldsExcludedFromUpdatePart`)       |
+| `fieldsExcludedFromUpdatePart` | Present in `INSERT`, excluded from `UPDATE` — typical for `createdAt`, `createdBy`            |
+| `noUpdateIfNull`               | Don't overwrite existing values with `NULL` — **critical for incremental syncs with partial payloads** |
+| `mergeCorrection`              | `(sql) => sql` — final rewrite hook                                                           |
+| `returning`                    | `'*'` or quoted field list for `RETURNING`                                                    |
+
+```typescript
+const mergeSql = await getMergeSqlMAIN({
+  commonSchemaAndTable: 'public.external_items',
+  recordset: batch,
+  noUpdateIfNull: true,                              // partial payload upsert
+  fieldsExcludedFromUpdatePart: ['createdBy', 'createdAt'],
+});
+await queryMAIN(mergeSql);
+```
+
+### 2.7. `mergeByBatch<U>({ recordset, getMergeSqlFn, batchSize? })`
+
+Universal batched-upsert runner. Slices `recordset` into batches, calls `getMergeSqlFn(batch)` for each, and
+executes the generated SQL through `queryMAIN`. Returns one entry per batch.
+
+- Default `batchSize` is `999`; in practice **use 50–100 for wide rows** — you hit Postgres' parameter
+  limit or statement-size limit well before 999.
+- **The runner mutates the input via `Array.prototype.splice`.** By the time it returns, `recordset` is
+  empty. Clone the array upfront if you need to retain the data.
+
+```typescript
+const getMergeSqlFn = async (batch: TRecordSet) => getMergeSqlMAIN({
+  commonSchemaAndTable: 'public.publications',
+  recordset: batch,
+  noUpdateIfNull: true,
+});
+await mergeByBatch({ recordset: dataset, getMergeSqlFn, batchSize: 100 });
+// dataset is now []
+```
+
+### 2.8. `checkMainDB()`
+
+Startup liveness check. Runs `SELECT 1 FROM pg_catalog.pg_class LIMIT 1` — a neutral query that works on
+any PostgreSQL instance. On failure (except under `NODE_ENV=test`) the process exits with code `1`. Call
+it early in `start.ts` so misconfigured servers fail immediately.
+
+### 2.9. `getMainDBConnectionStatus()`
+
+Returns one of `'connected' | 'disconnected' | 'error' | 'db_not_used'`. Safe to call from a `/health`
+endpoint or admin page — never throws, never exits.
+
+## 3. Types
+
+```typescript
+// Re-exported by the SDK
+import { IQueryPgArgsCOptional } from 'fa-mcp-sdk';
+
+// Directly from af-db-ts when you need them
+import { IQueryPgArgs, TDBRecord, TRecordSet } from 'af-db-ts';
+```
+
+- `IQueryPgArgs` — full query-arg shape used by `queryPg` directly; `connectionId` is required.
+- `IQueryPgArgsCOptional` — what the `MAIN` helpers accept; `connectionId` is pre-filled by the SDK.
+- `TDBRecord` — `Record<string, any>` — a generic row shape. Prefer concrete interfaces (`IUserRow`, …)
+  where they exist; use `TDBRecord` only when the row shape is not fixed.
+- `TRecordSet<U extends TDBRecord = TDBRecord>` — the array shape expected by `getInsertSqlMAIN`,
+  `getMergeSqlMAIN`, and `mergeByBatch`.
+
+## 4. Decision Tree
+
+```
+Need to talk to the main DB?
+├─ Yes → use the sugar layer
+│    ├─ rows only (R[])              → queryRsMAIN
+│    ├─ single row (R | undefined)   → oneRowMAIN
+│    ├─ full QueryResult (rowCount…) → queryMAIN
+│    ├─ DDL / DML, no rows           → execMAIN
+│    ├─ generate INSERT SQL          → getInsertSqlMAIN → queryMAIN
+│    ├─ generate UPSERT SQL          → getMergeSqlMAIN  → queryMAIN
+│    └─ batch upsert many rows       → mergeByBatch + getMergeSqlMAIN
+└─ No (secondary DB / low level)  → direct af-db-ts imports
+     ├─ plain query                 → queryPg + IQueryPgArgs (wrap it, mirror pg-db.ts)
+     ├─ transaction / cursor        → getPoolPg(<id>) + manual BEGIN/COMMIT/ROLLBACK
+     └─ cross-DB SQL generation     → getInsertSqlPg / getMergeSqlPg / getUpdateSqlPg
+```
+
+## 5. Best-Practice Checklist
+
+- [ ] Use the `MAIN` sugar for the main DB — reach for `queryPg` only when talking to a secondary database.
+- [ ] Always pass user input through `sqlValues` (`$1`, `$2`, …) — no string concatenation.
+- [ ] Type your rows: `queryMAIN<IUserRow>(...)`, `TRecordSet<IUserRow>` in SQL generators.
+- [ ] For auto-increment tables: `excludeFromInsert: ['<pk>']` + `addOutputInserted: true` when you need
+      the generated id back.
+- [ ] For incremental syncs of external sources with partial payloads: `noUpdateIfNull: true`; put audit
+      columns (`createdAt`, `createdBy`) into `fieldsExcludedFromUpdatePart`.
+- [ ] For large recordsets go through `mergeByBatch` — remember it **mutates** the input.
+- [ ] For transactions on the main DB the simplest form is
+      `execMAIN({ sqlText: 'BEGIN' | 'COMMIT' | 'ROLLBACK' })`. When you need a single physical client
+      across many operations, use `getPoolPg(...)` from `af-db-ts` and pass the resulting `client` through
+      the object form of the `MAIN` helpers.
+- [ ] Never call `client.release()` on a client obtained from `getPoolPg` — pool lifecycle is owned by the
+      SDK and closed during graceful shutdown (via `closeAllPgConnectionsPg`).
+- [ ] For writes whose success must be verified, pass `throwError = true` so failures surface instead of
+      silently returning `undefined`.
+- [ ] Call `await checkMainDB()` early at startup; expose `getMainDBConnectionStatus()` from `/health`.
+
+## 6. Secondary Databases (advanced)
+
+The SDK only exposes sugar for the single `main` connection. If your server needs extra databases, declare
+them under `db.postgres.dbs.<alias>` and write a small wrapper mirroring `src/core/db/pg-db.ts` — set the
+appropriate `connectionId` and, if needed, supply `registerTypesFunctions`. Typical cases: read-only
+replicas, legacy sources, cross-service ETL jobs.
+
+```typescript
+import { queryPg, IQueryPgArgs } from 'af-db-ts';
+import type { QueryResult, QueryResultRow } from 'pg';
+
+const SECONDARY = 'reporting';   // must match a key under db.postgres.dbs
+
+export const queryReporting = async <R extends QueryResultRow = any> (
+  arg: string | Omit<IQueryPgArgs, 'connectionId'>,
+  sqlValues?: any[],
+  throwError = false,
+): Promise<QueryResult<R> | undefined> => {
+  const q: IQueryPgArgs = typeof arg === 'string'
+    ? { sqlText: arg, connectionId: SECONDARY, sqlValues, throwError }
+    : { ...arg, connectionId: SECONDARY };
+  return queryPg<R>(q);
+};
+```

package/cli-template/package.json

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

package/package.json

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

package/scripts/update-doc.js

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