fa-mcp-sdk 0.4.68 → 0.4.70

package/cli-template/.claude/skills/{deploy-mcp → create-mcp-wizard}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: deploy-mcp
-description: "Implement an fa-mcp MCP server end-to-end in this already-scaffolded project: verify Agent Tester OpenAI creds, seed dev-time secrets and lenient config, push the scaffold to GitLab (creating a new repo OR reusing an existing one when instructed), draft an implementation plan, implement tools/prompts/resources, iterate via the Agent Tester headless API, then push the finished work. Use when the user asks to develop/implement/deploy the MCP server in this project, mentions 'deploy-mcp', 'развернуть MCP', 'реализовать MCP', or supplies a feature brief."
+name: create-mcp-wizard
+description: "Implement an fa-mcp MCP server end-to-end in this already-scaffolded project: verify Agent Tester OpenAI creds, seed dev-time secrets and lenient config, push the scaffold to GitLab (creating a new repo OR reusing an existing one when instructed), draft an implementation plan, implement tools/prompts/resources, iterate via the Agent Tester headless API, then push the finished work. Use when the user asks to develop/implement/deploy the MCP server in this project, mentions 'create-mcp-wizard', 'развернуть MCP', 'реализовать MCP', or supplies a feature brief."
 disable-model-invocation: true
 allowed-tools: Bash(node *), Bash(yarn *), Bash(npm *), Bash(git *), Bash(pwd), Bash(cd *), Bash(curl *), Read, Write, Edit, Glob, Grep
 ---
@@ -34,6 +34,13 @@ All supporting scripts live in `${CLAUDE_SKILL_DIR}/scripts/` and are invoked wi
   by the CLI / skill infrastructure and by the SDK maintainer. Do NOT modify, add, or delete files
   inside them unless the accompanying text explicitly instructs you to. This applies to every step
   below — implementation, tests, dev report, everything.
+- **Reporting language**. Language for all generated artifacts (`claudedocs/*.md`, commit
+  messages, user-facing summaries) is resolved in this order:
+    1. Explicit directive in the feature brief.
+    2. Else, contents of `preferred-language.txt` in the project root, if it exists.
+    3. Else — English.
+  Translate prose — headings and body text — to the resolved language; leave code, paths, YAML
+  keys, and CLI commands as-is. Report the resolved language and its source in the Step 1 summary.
 
 ## Step 1 — Scan the accompanying text for requirements
 
@@ -50,8 +57,10 @@ Before touching code, read every message/file the user attached and extract:
 - **Agent Tester OpenAI creds** — `apiKey` (required for Step 2) and `baseURL` (optional — Azure /
   proxy / local LLM). If the text already supplies them, use those. If `config/local.yaml` already
   has a working `agentTester.openAi.apiKey`, re-use it instead of asking again.
+- **Reporting language** — resolve per the Ground rule above; record it for later steps.
 
-Summarize what you found to the user in 3-6 bullets and get a one-line confirmation before proceeding.
+Summarize what you found to the user in 3-6 bullets (including the resolved reporting language
+and its source) and get a one-line confirmation before proceeding.
 
 ## Step 2 — Verify Agent Tester OpenAI credentials
 
@@ -128,7 +137,7 @@ what belongs in the initial commit. If the tree contains scratch notes, local-on
 anything the user flagged as not-for-commit, stash it with an untracked-inclusive stash:
 
 ```
-git stash push -u -m "deploy-mcp: pre-initial-push stash" -- <paths>
+git stash push -u -m "create-mcp-wizard: pre-initial-push stash" -- <paths>
 ```
 
 Announce what you stashed so the user can recover it later via `git stash list` / `git stash pop`.
@@ -205,7 +214,8 @@ OR switch to branch 4a if the "collision" is in fact the already-existing target
 
 ## Step 6 — Draft and commit to a plan
 
-Create `claudedocs/impl-plan.md` (create the directory if needed). Structure:
+Create `claudedocs/impl-plan.md` (create the directory if needed) in the reporting language.
+Structure:
 
 ```markdown
 # Implementation Plan — <project name>
@@ -245,7 +255,9 @@ Create `claudedocs/impl-plan.md` (create the directory if needed). Structure:
 - [ ] `yarn typecheck` clean
 - [ ] `yarn test:mcp`, `:mcp-http`, `:mcp-sse` all green
 - [ ] Agent Tester iterations done, `claudedocs/test-log.md` has entries
-- [ ] `claudedocs/dev-report.md` written
+- [ ] `claudedocs/dev-report.md` written (full report)
+- [ ] `claudedocs/breef-report.md` written (brief of work + problems — same content echoed to console)
+- [ ] `claudedocs/dev-problems.md` written (blockers, failed checks, open questions)
 - [ ] Final GitLab push (Step 10) complete
 ```
 
@@ -353,8 +365,9 @@ agent prompt, handler logic, error message — per `FA-MCP-SDK-DOC/08-agent-test
 fix, rebuild (`yarn cb`), restart, and re-run the scenario. After restart, in-memory sessions on
 the server are wiped — delete the stale `claudedocs/.agent-session` file before re-running.
 
-Log every iteration in `claudedocs/test-log.md` (session header + per-scenario: sent / expected /
-received / tools used / result / diagnosis / fix). This is the audit trail.
+Log every iteration in `claudedocs/test-log.md` in the reporting language (session header +
+per-scenario: sent / expected / received / tools used / result / diagnosis / fix). This is the
+audit trail.
 
 Stop the server with `node scripts/kill-port.js <port>` (or Ctrl+C) when you're done iterating.
 
@@ -373,9 +386,22 @@ yarn test:mcp-sse
 
 Zero errors, zero warnings that matter, all transport tests green.
 
-Write `claudedocs/dev-report.md` per the structure in `CLAUDE.md` → "Development Report"
-(what was built, architecture decisions, agent prompt rationale, test coverage, Agent Tester findings,
-configuration, known limitations).
+Write `claudedocs/dev-report.md` in the reporting language, following the structure in
+`CLAUDE.md` → "Development Report" (what was built, architecture decisions, agent prompt rationale,
+test coverage, Agent Tester findings, configuration, known limitations).
+
+Alongside the full report, produce two companion files in the reporting language:
+
+- **`claudedocs/breef-report.md`** — a brief of the work done and problems encountered. Keep it
+  short and scannable (not a duplicate of `dev-report.md`): what was implemented, what passed,
+  what failed, the key problems in 1–2 lines each. The same content is echoed verbatim to the
+  console as part of the "Final report" step below — that is the primary way the user sees it.
+- **`claudedocs/dev-problems.md`** — a focused list of what could NOT be done / tested / connected
+  to during this session, plus any open questions, unresolved blockers, or decisions the user
+  needs to make. Include: failed external connections (DB, upstream API, AD, Consul, etc.),
+  tests that were skipped or disabled and why, missing creds, ambiguous requirements from the
+  brief, anything deferred. If there are no problems, write the file anyway with a single
+  "No outstanding issues." line so the user can see the check was done.
 
 ## Step 10 — Final GitLab push
 
@@ -386,7 +412,7 @@ implemented feature and pushes it on top of the scaffold commit.
 content that shouldn't ship to the remote, stash it first:
 
 ```
-git stash push -u -m "deploy-mcp: pre-final-push stash" -- <paths>
+git stash push -u -m "create-mcp-wizard: pre-final-push stash" -- <paths>
 ```
 
 Leave anything stashed from Step 5 still stashed — if it shouldn't be in the initial commit, it
@@ -423,8 +449,14 @@ Tell the user:
    (Step 5) and the feature push (Step 10) landed on `main`.
 3. Summary of tools/resources/prompts/endpoints that were implemented.
 4. Any flagged limitations from the dev report.
-5. Link to `claudedocs/impl-plan.md`, `claudedocs/test-log.md`, `claudedocs/dev-report.md`.
+5. Links to `claudedocs/impl-plan.md`, `claudedocs/test-log.md`, `claudedocs/dev-report.md`,
+   `claudedocs/breef-report.md`, `claudedocs/dev-problems.md`.
 6. Anything still stashed from Step 5 / Step 10 (so the user remembers to `git stash pop` or drop).
+7. **Echo the full contents of `claudedocs/breef-report.md` to the console** (in the reporting
+   language, as written). This is the brief of work done + problems — it must appear inline in
+   the chat, not only as a file link, so the user can read it without opening the file. If
+   `claudedocs/dev-problems.md` contains anything other than "No outstanding issues.", also call
+   that out explicitly and point at the file.
 
 ## Troubleshooting
 

package/cli-template/.claude/skills/{deploy-mcp → create-mcp-wizard}/scripts/headless-test.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Thin wrapper around POST /agent-tester/api/chat/test — used by the deploy-mcp skill
+ * Thin wrapper around POST /agent-tester/api/chat/test — used by the create-mcp-wizard skill
  * to exercise the freshly-built MCP server through the full agent loop.
  *
  * Usage:
@@ -107,4 +107,4 @@ const req = http.request({
 req.on('error', (e) => { console.error(`request error: ${e.message}`); process.exit(1); });
 req.on('timeout', () => { req.destroy(new Error('timeout')); });
 req.write(payload);
-req.end();
+req.end();

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/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/gitignore

@@ -90,3 +90,4 @@ glm.sh
 /.serena/
 /.playwright-mcp/
 /claudedocs/
+preferred-language.txt

package/cli-template/package.json

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

package/cli-template/readme-docs/SKILLS.md

@@ -140,7 +140,7 @@ Characteristics:
 
 ---
 
-### `/deploy-mcp` — End-to-End MCP Server Implementation
+### `/create-mcp-wizard` — End-to-End MCP Server Implementation
 
 Orchestrates the full implementation workflow from feature brief to a live GitLab repo. The project
 must already be scaffolded by the `fa-mcp` CLI — this skill picks up from `yarn install` onwards.
@@ -169,20 +169,25 @@ Pipeline (10 steps):
 
 Characteristics:
 
-- **Launch**: **command-only** via `/deploy-mcp`. `disable-model-invocation: true` — does NOT
+- **Launch**: **command-only** via `/create-mcp-wizard`. `disable-model-invocation: true` — does NOT
   trigger on implicit mentions
 - **Input**: feature brief comes from the accompanying user message(s) and attached files. OpenAI
   and GitLab creds may be supplied inline or asked interactively
 - **Ground rules**: every step explicit and verified; free-form inputs asked in plain prose (never
   predefined options); exclusions from the brief honoured; dev defaults intentionally lenient;
   `.claude/`, `deploy/`, `FA-MCP-SDK-DOC/` are NOT modified unless the brief explicitly says to
+- **Reporting language**: all generated artifacts (`claudedocs/*.md`, commit messages, user-facing
+  summaries) are written in a language resolved in this order: (1) explicit directive in the
+  feature brief, else (2) contents of `preferred-language.txt` in the project root, else
+  (3) English. Prose (headings + body) is translated; code, paths, YAML keys, and CLI commands
+  stay as-is
 - **Output**: implemented project + `claudedocs/{impl-plan,test-log,dev-report}.md`, GitLab repo
   with two commits on `main` (scaffold + feature)
 
 **Examples:**
 
 ```
-/deploy-mcp
-/deploy-mcp реализуй инструменты из task.md, OpenAI key sk-..., GitLab group mcp-servers
-/deploy-mcp implement tools from the message; repo уже существует, push to git@gitlab.example:ai/mcp-foo.git
+/create-mcp-wizard
+/create-mcp-wizard реализуй инструменты из task.md, OpenAI key sk-..., GitLab group mcp-servers
+/create-mcp-wizard implement tools from the message; repo уже существует, push to git@gitlab.example:ai/mcp-foo.git
 ```

package/package.json

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