fa-mcp-sdk 0.4.51 → 0.4.53

package/cli-template/.claude/skills/readme-generator/reference/templates.md

@@ -0,0 +1,385 @@
+# Section Templates (Main README)
+
+Canonical blocks for the main `README.md` of an `fa-mcp-sdk`-based MCP server. Copy, then adapt
+placeholders (`<NAME>`, `<PORT>`, `<prefix>`, `<upstream>`) to the actual project.
+
+---
+
+## 1. Title + one-liner
+
+```markdown
+# <Project Name>
+
+<One-sentence description: "MCP server for <Upstream System> — lets AI agents <primary action>.">
+```
+
+Example:
+
+```markdown
+# MCP Wiki
+
+MCP server for Atlassian Confluence. Lets AI agents search, read, create, and edit wiki pages via
+the Model Context Protocol.
+```
+
+---
+
+## 2. Badges
+
+Prefer shields.io. Include only badges that are meaningful (skip build status if no CI yet).
+
+```markdown
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Server-DA7857)](https://modelcontextprotocol.io/)
+[![fa-mcp-sdk](https://img.shields.io/badge/built%20with-fa--mcp--sdk-526CFE)](https://github.com/Bazilio-san/fa-mcp-sdk)
+```
+
+---
+
+## 3. Overview
+
+2–4 sentences. Answer: *what is this / for whom / core value*. Active voice. No marketing fluff.
+
+```markdown
+## Overview
+
+<Project> provides comprehensive <upstream> integration for AI agents via the Model Context Protocol.
+It exposes <N> tools covering <main domains>, supports <auth methods>, and ships with <one or two
+distinguishing features>. Use it when you need <primary use case>.
+```
+
+---
+
+## 4. Tools
+
+Group by domain. Keep rows short — one-line descriptions only.
+
+```markdown
+## Tools (<N>)
+
+### <Domain 1>
+| Tool                  | Description                                        |
+|-----------------------|----------------------------------------------------|
+| `<tool_name>`         | <Short description, verb-first, ≤ 80 chars>        |
+| `<tool_name>`         | <Short description>                                |
+
+### <Domain 2>
+| Tool                  | Description                                        |
+|-----------------------|----------------------------------------------------|
+| `<tool_name>`         | <Short description>                                |
+```
+
+Notes:
+
+- Column widths consistent within the file.
+- Tool names always inline-code.
+- If a tool has a caveat (e.g. server vs. cloud behaviour), use a footnote `*` and explain below
+  the table.
+
+---
+
+## 5. Quick Start
+
+Three steps. Target: a user running the server in under 2 minutes.
+
+```markdown
+## Quick Start
+
+```bash
+npm install
+cp config/_local.yaml config/local.yaml   # configure <upstream> credentials
+npm run build
+npm start                                 # HTTP mode, port <PORT>
+```
+
+For STDIO mode (Claude Desktop direct spawn):
+
+```bash
+node dist/src/start.js stdio
+```
+```
+
+---
+
+## 6. MCP Client Integration
+
+Always in main README. Adapt custom header names (`x-<prefix>-*`) to this server's actual scheme.
+
+```markdown
+## MCP Client Integration
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "<name>": {
+      "type": "http",
+      "url": "http[s]://<host[:port]>/mcp",
+      "headers": {
+        "x-<prefix>-username": "<your username>",
+        "x-<prefix>-password": "<your password>"
+      }
+    }
+  }
+}
+```
+
+Alternatively, use a Personal Access Token:
+
+```json
+"headers": {
+  "x-<prefix>-token": "<your PAT>"
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`.
+
+**Option 1 — STDIO (local build, direct spawn):**
+
+```json
+{
+  "mcpServers": {
+    "<name>": {
+      "command": "node",
+      "args": ["<path>/<project>/dist/src/start.js", "stdio"],
+      "env": {}
+    }
+  }
+}
+```
+
+**Option 2 — HTTP (remote server via `mcp-remote`):**
+
+```json
+{
+  "mcpServers": {
+    "<name>": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "http[s]://<host[:port]>/mcp",
+        "--header",
+        "x-<prefix>-username:<your username>",
+        "--header",
+        "x-<prefix>-password:<your password>",
+        "--allow-http",
+        "--transport",
+        "http-only"
+      ]
+    }
+  }
+}
+```
+
+### Qwen Code
+
+Add to `~/.qwen/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "<name>": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "http[s]://<host[:port]>/mcp",
+        "--header",
+        "x-<prefix>-username:<your_username>",
+        "--header",
+        "x-<prefix>-password:<your_password>",
+        "--allow-http",
+        "--transport",
+        "http-only"
+      ]
+    }
+  }
+}
+```
+```
+
+---
+
+## 7. Key Features
+
+5–8 bullets. Include enabled SDK subsystems and project-specific capabilities. One line each.
+
+```markdown
+## Key Features
+
+- **Multi-auth**: Basic, PAT, OAuth 2.0 with automatic token refresh
+- **Per-request credentials**: override server config via `x-<prefix>-*` headers
+- **Batch operations** for high-throughput scenarios
+- **Fuzzy entity resolution** via external microservice
+- **Aggressive caching** with thundering-herd protection
+- **Webhook callbacks** for audit / chaining (`x-web-hook`)
+- **Agent Tester UI + Headless API** for end-to-end testing
+```
+
+---
+
+## 8. Transports
+
+```markdown
+## Transports
+
+- **HTTP** — web integrations. Endpoints:
+  - `/mcp` — MCP protocol (JSON-RPC 2.0)
+  - `/api/*` — REST API (if custom API is present)
+  - `/docs` — Swagger UI
+  - `/health` — healthcheck
+  - `/admin` — token generator UI
+  - `/agent-tester` — Agent Tester web UI
+- **STDIO** — for Claude Desktop direct spawn (no network)
+
+Port is set in `config/default.yaml` → `webServer.port` (default <PORT>).
+```
+
+Keep endpoints that actually exist; drop the rest.
+
+---
+
+## 9. Configuration Basics
+
+Compact table with 5–10 most important keys. Link to full reference when the list grows.
+
+```markdown
+## Configuration Basics
+
+Priority: env vars > `config/local.yaml` > `config/{NODE_ENV}.yaml` > `config/default.yaml`.
+
+| Key                              | Description                         | Default   |
+|----------------------------------|-------------------------------------|-----------|
+| `<upstream>.url`                 | <Upstream> base URL                 | —         |
+| `<upstream>.auth.pat`            | Personal Access Token               | —         |
+| `<upstream>.auth.basic.username` | Basic auth username                 | —         |
+| `<upstream>.auth.basic.password` | Basic auth password                 | —         |
+| `webServer.port`                 | HTTP server port                    | `<PORT>`  |
+| `webServer.auth.enabled`         | MCP server authorization on/off     | `false`   |
+| `mcp.toolAnswerAs`               | Response format (`text` / `json`)   | `text`    |
+
+Full reference: [Configuration](./readme-docs/configuration.md).
+```
+
+---
+
+## 10. Build & Run
+
+```markdown
+## Build & Run
+
+```bash
+npm run build        # tsc + copy static assets
+npm start            # HTTP server
+npm run dev          # tsc --watch
+```
+
+Lint / typecheck / test:
+
+```bash
+npm run lint:fix
+npm run typecheck
+npm test
+```
+
+Environment variables:
+
+- `NODE_ENV` — picks `config/{NODE_ENV}.yaml` overlay
+- `DEBUG` — namespace-based logging (see [Debug Logging](./readme-docs/debugging.md))
+```
+
+---
+
+## 11. Authentication (summary + link)
+
+Keep this short. Push tables and invariants into `readme-docs/authentication.md`.
+
+```markdown
+## Authentication
+
+The server supports per-request credentials via `x-<prefix>-*` headers (Basic, PAT) and
+config-level defaults with OAuth 2.0 token refresh. When `x-on-behalf-of-user` is set, the request
+is routed through the impersonation proxy.
+
+Priority rules, resolution order, and invariants: [Authentication](./readme-docs/authentication.md).
+```
+
+---
+
+## 12. Dynamic feature sections
+
+One short subsection per enabled optional subsystem. 2–3 sentences each, with a link to the
+satellite file when details warrant one.
+
+```markdown
+### Consul service discovery
+
+Server registers itself on startup and deregisters on SIGTERM; health check path is `/health`.
+Setup: [Consul](./readme-docs/consul.md).
+
+### Active Directory
+
+Tools can gate access by AD group membership. Configuration and per-domain setup:
+[Active Directory](./readme-docs/active-directory.md).
+
+### Webhooks
+
+After every tool invocation the server can POST the result to an external URL via the `x-web-hook`
+header or a per-tool `hook` return value. Body schema and priority:
+[Webhooks](./readme-docs/webhooks.md).
+
+### Agent Tester
+
+Built-in web UI (`/agent-tester`) and Headless API (`/agent-tester/api/chat/test`) for end-to-end
+testing with a real LLM. Full guide: [Testing](./readme-docs/testing.md).
+```
+
+---
+
+## 13. Skills
+
+```markdown
+## Claude Code Skills
+
+The project ships with custom skills in `.claude/skills/`:
+
+| Command             | Description                                         |
+|---------------------|-----------------------------------------------------|
+| `/gen-jwt`          | Generate JWT tokens for MCP server authentication   |
+| `/headless-test`    | Run headless tests for all MCP tools via curl API   |
+| `/upgrade-guide`    | Generate migration guide for fa-mcp-sdk upgrades    |
+
+Details, launch modes, and examples: [SKILL_README.md](./SKILL_README.md).
+```
+
+---
+
+## 14. Stack
+
+```markdown
+## Stack
+
+- **Framework**: [fa-mcp-sdk](https://github.com/Bazilio-san/fa-mcp-sdk)
+- **Transport**: MCP (STDIO, HTTP, SSE)
+- **Language**: TypeScript (ESM)
+- **HTTP client**: Axios
+- **Key libs**: <fill in the notable dependencies>
+```
+
+---
+
+## 15. License
+
+```markdown
+## License
+
+<License name> © <Owner>. See [LICENSE](./LICENSE).
+```

package/cli-template/CLAUDE.md

@@ -342,25 +342,11 @@ This log serves as:
 - **Progress tracker** — which tools/scenarios are covered, which remain
 - **Handoff document** — if the session is interrupted, the next session can read the log and continue
 
-## Editing files in `.claude/`
-
-Files inside `.claude/` (SKILL.md and others) are monitored by Claude Code and reloaded on change. To avoid partial reads during multi-edit sessions, follow this protocol:
-
-1. **Copy** the target file to a temp location outside `.claude/`:
-   ```bash
-   node scripts/fcp.js tmp-skill.md .claude/skills/<skill-name>/SKILL.md
-   ```
-2. **Edit** `tmp-skill.md` — make ALL changes there (multiple Edit calls are fine).
-3. **Save** atomically via the helper script:
-   ```bash
-   node scripts/fcp.js .claude/skills/<skill-name>/SKILL.md tmp-skill.md
-   ```
-4. **Remove** the temp file:
-   ```bash
-   rm tmp-skill.md
-   ```
-
-CRITICAL: Never use `Edit` or `Write` directly on files inside `.claude/` — always go through the temp-copy workflow above.
+## Editing files in `.claude/` (Skill /edit-claude-files)
+
+Any edit or new file under `.claude/**` (SKILL.md, scripts, hooks, agents, `settings.json`) is blocked
+by `settings.json` — direct `Write`/`Edit` will fail. Invoke the `/edit-claude-files` skill, which
+describes the required `scripts/fcp.js` temp-copy protocol.
 
 
 ## Formatting

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

@@ -13,7 +13,7 @@ npm install fa-mcp-sdk
 | File | Content | Read When |
 |------|---------|-----------|
 | [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`, REST API with tsoa, OpenAPI/Swagger | Creating tools, REST endpoints |
+| [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, cache, PostgreSQL | Server configuration, DB |
 | [04-authentication](04-authentication.md) | JWT, Basic auth, server tokens, `createAuthMW()`, Token Generator, CLI Token Generator, JWT Generation API | Authentication setup |

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

@@ -62,6 +62,66 @@ 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
+
+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).
+
+**Recipe:**
+
+1. **Declare the header** so Agent Tester and `use://http-headers` advertise it:
+
+   ```typescript
+   usedHttpHeaders: [
+     { name: 'x-web-hook', description: 'URL to POST the tool result to.', isOptional: true },
+   ],
+   ```
+
+2. **Dispatch inside the handler** — fire-and-forget, never throw, never block the reply:
+
+   ```typescript
+   import axios from 'axios';
+   import { appConfig, logger, toStr, IToolHandlerParams } from 'fa-mcp-sdk';
+
+   const URL_REGEX = /^https?:\/\/[^\s]+$/i;
+
+   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)}`));
+   };
+
+   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);
+   };
+   ```
+
+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:
+
+   ```typescript
+   export interface IToolResponse { text: string; json: Record<string, any>; hook?: string; }
+   ```
+
+**Body contract** (recommended; keep stable across tools):
+
+| 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 |
+
+**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.
+
 
 ## REST API Endpoints
 

package/cli-template/FA-MCP-SDK-DOC/04-authentication.md

@@ -50,16 +50,18 @@ The admin panel (`/admin`) supports 4 authentication types and can be configured
 
 ```yaml
 # config/default.yaml
-webServer:
-  adminAuth:
-    enabled: true
-    # Single type (string)
-    type: 'basic'
-    # Or multiple types (array) — login page shows tabs to choose
-    type: ['jwtToken', 'basic']
+adminPanel:
+  enabled: true
+  # Single type (string)
+  authType: 'basic'
+  # Or multiple types (array) — login page shows tabs to choose
+  authType: ['jwtToken', 'basic']
+  # 'none' / null / empty array / not set — panel opens WITHOUT authentication
+  # (convenience for local development; do NOT use in production).
+  authType: 'none'
 ```
 
-**Supported types:** `permanentServerTokens`, `basic`, `jwtToken`, `ntlm`
+**Supported types:** `permanentServerTokens`, `basic`, `jwtToken`, `ntlm`, `none` (= open access)
 
 When multiple types are configured (e.g. `['jwtToken', 'basic']`), the login page shows tabs:
 - **Token** tab — for `permanentServerTokens` and `jwtToken` authentication

package/cli-template/README.md

@@ -76,25 +76,81 @@ Same as `agent_prompt` prompt. **MIME:** text/plain
 **Option B: Environment Variables**
 
 
-## Claude Desktop Setup
+## Usage with AI CLIs
 
-Add to `claude_desktop_config.json`:
+The server exposes an HTTP MCP endpoint at `http[s]://<host[:port]>/mcp`. Authentication (when enabled in
+`config/default.yaml` → `webServer.auth`) is passed via the standard `Authorization` header — most commonly a
+JWT Bearer token generated by the `/gen-jwt` skill or by `node scripts/generate-jwt.js`.
+
+### With Claude Code
+
+Add to `~\.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "{{project.name}}": {
-      "command": "node",
-      "args": [
-        "<path-to-project>/mcp-staff-db/dist/src/index.js"
-      ],
-      "env": {
+      "type": "http",
+      "url": "http[s]://<host[:port]>/mcp",
+      "headers": {
+        "Authorization": "Bearer <jwt-token>"
       }
     }
   }
 }
 ```
 
+### With Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "{{project.name}}": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "http[s]://<host[:port]>/mcp",
+        "--header",
+        "Authorization: Bearer <jwt-token>",
+        "--allow-http",
+        "--transport",
+        "http-only"
+      ]
+    }
+  }
+}
+```
+
+### With Qwen Code
+
+Add to `~\.qwen\settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "{{project.name}}": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "http[s]://<host[:port]>/mcp",
+        "--header",
+        "Authorization: Bearer <jwt-token>",
+        "--allow-http",
+        "--transport",
+        "http-only"
+      ]
+    }
+  }
+}
+```
+
+> For STDIO transport (local Claude Desktop integration without an HTTP server), run
+> `node <path-to-project>/dist/src/start.js stdio` — see `CLAUDE.md` for details.
+
 ## HTTP Mode Endpoints
 
 - **/** - Home page
@@ -104,28 +160,22 @@ Add to `claude_desktop_config.json`:
 
 ## Claude Code Skills
 
-### `/upgrade-guide`
+The project ships with custom skills in `.claude/skills/`:
 
-Generates a migration guide for upgrading `fa-mcp-sdk` to the latest (or specified) version. Analyzes config changes, template diffs, new exports, and breaking changes, then saves a step-by-step guide to `upgrade-guide-<old>-to-<new>.md`.
+| Command              | Description                                                             |
+|----------------------|-------------------------------------------------------------------------|
+| `/gen-jwt`           | Generate JWT tokens for MCP server authentication                       |
+| `/upgrade-guide`     | Generate migration guide for `fa-mcp-sdk` upgrades                      |
+| `/feature-generator` | Turn a feature description into a self-sufficient prompt for an AI CLI  |
+| `/readme-generator`  | Generate structured README.md + satellite `readme-docs/*.md`            |
 
-By default versions and commit hashes refer to THIS project — the skill looks up which SDK version was used in each project commit/tag. To pass SDK references directly, mention "SDK" explicitly.
-
-```
-/upgrade-guide                                             # current SDK → latest SDK
-/upgrade-guide 1.2.3                                       # project version 1.2.3 → latest SDK
-/upgrade-guide 1.2.3 1.2.7                                 # project versions
-/upgrade-guide abc1234 def5678                             # project commits
-/upgrade-guide от версии 0.1.30 SDK                        # SDK versions directly → latest SDK
-/upgrade-guide от версии 0.4.30 SDK до 0.5.0 SDK           # SDK versions directly
-/upgrade-guide от комита sdk abc1234 до комита sdk def5678 # SDK commits directly
-/upgrade-guide 1.2.3 1.2.7 на русском
-```
+Details, launch modes, and examples: [SKILL_README.md](SKILL_README.md)
 
 ## Security
 
 ### Admin panel JWT requirement
 
-When `adminAuth.type` includes `jwtToken`, the admin panel (`/admin`) accepts a JWT
+When `adminPanel.authType` includes `jwtToken`, the admin panel (`/admin`) accepts a JWT
 **only if its payload contains `allow: 'gen-token'`**. JWTs without this claim are
 rejected with `401` — this blocks short-lived tokens issued for other purposes (for
 example, the 5-minute JWT auto-generated by the Agent Tester page and written into its