fa-mcp-sdk 0.4.51 → 0.4.53

package/README.md

@@ -219,7 +219,7 @@ Note: The `dist/` directory (compiled JavaScript) is created after running `npm
 `http://localhost:3000` with:
 - MCP endpoints at `/mcp/*`
 - Admin panel for generating access tokens at `/admin`
-  - When `adminAuth.type` includes `jwtToken`, the JWT **must** carry `allow: 'gen-token'`
+  - When `adminPanel.authType` includes `jwtToken`, the JWT **must** carry `allow: 'gen-token'`
     in its payload to be accepted. Tokens without this claim (e.g. the short-lived JWT
     auto-generated for the Agent Tester page) are rejected — this prevents them from
     being replayed to mint arbitrary long-lived tokens. `permanentServerTokens` and

package/cli-template/.claude/settings.json

@@ -16,7 +16,9 @@
       "Read(./**/_tmp/**)",
       "Read(./**/*.private.*)",
       "Read(./**/*.local.*)",
-      "Read(./**/*local-*)"
+      "Read(./**/*local-*)",
+      "Write(.claude/**)",
+      "Edit(.claude/**)"
     ]
   },
   "env": {

package/cli-template/.claude/skills/edit-claude-files/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: edit-claude-files
+description: "Protocol for editing or creating any file under .claude/ (SKILL.md, scripts, hooks, agents, settings.json, etc.). Use whenever a file path starts with .claude/ — direct Write/Edit is blocked by settings.json, so changes MUST go through the scripts/fcp.js temp-copy workflow."
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(node scripts/fcp.js *), Bash(rm:*)
+---
+
+# Editing files in `.claude/`
+
+**Scope of this rule — read carefully.** It applies to **every file under `.claude/`** — not only
+`SKILL.md`. This includes scripts in `.claude/skills/<skill>/scripts/`, hooks in `.claude/hooks/`,
+agent configs in `.claude/agents/`, supporting reference files, `settings.json`, and anything else
+inside the directory. Claude Code watches the whole tree and reloads on change; direct writes risk
+partial reads and inconsistent state during multi-edit sessions.
+
+To enforce this, `settings.json` denies the `Write` and `Edit` tools on `.claude/**` outright.
+Attempting a direct edit will fail the permission check — that is intentional, not a bug.
+
+**Protocol — every file, every time:**
+
+1. **Copy** the target file to a temp location outside `.claude/` (works for any file type: md, js,
+   json, cjs, …):
+   ```bash
+   node scripts/fcp.js tmp-edit.md .claude/skills/<skill-name>/SKILL.md
+   node scripts/fcp.js tmp-helper.js .claude/skills/<skill-name>/scripts/helper.js
+   ```
+2. **Edit** the temp file — make ALL changes there (multiple Edit calls are fine).
+3. **Save** atomically via the helper script (same command, reversed argument order):
+   ```bash
+   node scripts/fcp.js .claude/skills/<skill-name>/SKILL.md tmp-edit.md
+   node scripts/fcp.js .claude/skills/<skill-name>/scripts/helper.js tmp-helper.js
+   ```
+4. **Remove** the temp file:
+   ```bash
+   rm tmp-edit.md
+   ```
+
+**Creating a new file in `.claude/`** — same protocol, just start from an empty temp file:
+
+```bash
+# Write the new file somewhere OUTSIDE .claude/, then fcp.js it in:
+node scripts/fcp.js .claude/skills/<skill-name>/scripts/new-script.js tmp-new-script.js
+rm tmp-new-script.js
+```
+
+CRITICAL: Never use `Edit` or `Write` directly on files inside `.claude/` — always go through the
+temp-copy workflow above. This covers SKILL.md, scripts, hooks, agents, settings — everything.

package/cli-template/.claude/skills/feature-generator/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: feature-generator
+description: >-
+  Command-only META-SKILL (invoked explicitly, no auto-trigger). Produces an exhaustive,
+  self-sufficient prompt for an AI CLI (Claude Code) to implement a feature turnkey.
+  Thinks first (Karpathy-style), inspects real code via Read/Grep/Glob, finds reusable
+  functions and packages, designs the minimal sufficient solution, drafts a plan, code
+  examples, and testing scenario. Universal for any fa-mcp-sdk project.
+disable-model-invocation: true
+argument-hint: "[feature description | path to task file]"
+allowed-tools: Read, Grep, Glob, Bash(git *), Bash(yarn *), Bash(npm *), Bash(node *), Bash(ls *), Bash(cat *)
+---
+
+# feature-generator — META-SKILL for generating prompts for an AI CLI
+
+## Essence
+
+You **do NOT write code**. You generate a **self-sufficient prompt for an AI CLI**, which will then:
+
+- study the code itself,
+- design the solution itself,
+- implement it itself,
+- test it itself.
+
+This is a **META-skill** (agent-building agent). Your output is a clean prompt, not an
+implementation. You do not touch any code in the target repository.
+
+## How to invoke
+
+**Command-only.** The skill is **never auto-invoked by the model** — `disable-model-invocation`
+is set to `true`. Runs solely when the operator explicitly calls it (e.g. `/feature-generator`
+or the equivalent UI invocation). Ignore any implicit triggers from phrasing in user messages.
+
+## When to use
+
+- The operator describes a feature/functionality but does not write code themselves.
+- A production-ready prompt is needed to hand off to Claude Code / another AI agent.
+
+## Core principles (Karpathy-style, think-before-code)
+
+1. **Think before code.** Architecture first, implementation second. Do not rush to code.
+2. **Simplicity first.** KISS / YAGNI / DRY — the minimal sufficient solution. No speculative features.
+3. **Surgical changes.** Touch only what is required. Do not "improve" adjacent code.
+4. **Goal-driven.** Every step has a verifiable success criterion.
+5. **Anti-hallucination.** Do not invent files, functions, or APIs. Only what actually exists in
+   the code (verified via Read/Grep/Glob).
+6. **Surface assumptions.** Explicitly mark anything inferred on behalf of the operator as
+   `ASSUMPTION:`.
+7. **Ask, don't guess.** If anything is ambiguous — stop, name the ambiguity, ask.
+
+## Input
+
+The operator passes via `$ARGUMENTS`:
+
+- a free-form feature description, OR
+- a path to a file with the description (`task.md`, issue dump from a tracker, dialog excerpt).
+
+If `$ARGUMENTS` is empty — request a feature description. Do not infer requirements on the
+operator's behalf. If the project uses an issue tracker (Jira/Linear/GitHub Issues) — ask for
+the task ID and reference it in the final prompt.
+
+## Pipeline
+
+### STEP 1 — Understanding
+
+Extract from the input:
+
+- **Goal** — one sentence: what the user gets in the end.
+- **SDK components** — which layers are affected: `tool`, `prompt`, `resource`, `config`, `auth`,
+  `transport` (STDIO/HTTP/SSE), REST endpoint, CLI script, tests, documentation.
+- **Input / expected output** — for features with an API or MCP tool: request format → response
+  format.
+- **Constraints** — performance, security, compatibility, deadline, dependencies.
+- **Ambiguities** — enumerate them explicitly.
+
+If ambiguities exist — ask the operator clarifying questions **before** analyzing the code.
+If the operator says "decide yourself" — record the decision as `ASSUMPTION:`.
+
+### STEP 2 — Codebase Discovery
+
+**Real Read/Grep/Glob only. No guesses.**
+
+Baseline input reads (universal for fa-mcp-sdk projects):
+
+- `CLAUDE.md` — project rules, commands, protocols.
+- `package.json` — dependencies, scripts, `fa-mcp-sdk` version, package manager in use.
+- `README.md` — general context.
+- `tsconfig.json` — TypeScript settings (`strict`, `moduleResolution`, `paths`).
+- `FA-MCP-SDK-DOC/` (if present) — framework documentation; entry point
+  `00-FA-MCP-SDK-index.md`, then by topic: `02-1-tools-and-api.md`,
+  `02-2-prompts-and-resources.md`, `03-configuration.md`, `04-authentication.md`,
+  `06-utilities.md`, `07-testing-and-operations.md`.
+- `config/default.yaml` (+ `config/local.yaml` if present) — current configuration.
+- `src/start.ts` (or equivalent) — entry point; how `McpServerData` is assembled and
+  `initMcpServer()` is called.
+
+Then — targeted by the feature's topic:
+
+- `src/tools/` — if the feature adds/changes an MCP tool: find similar tools, learn the pattern
+  (`ToolWithHandler`, `inputSchema`, `annotations`, `handler`).
+- `src/prompts/`, `src/resources/` — if the feature concerns prompts/resources.
+- `src/lib/` — common utilities: HTTP client, logger, errors, cache, concurrency.
+- `src/_types_/` (or `src/types/`) — domain types, `CustomAppConfig`.
+- `tests/` — test layout (STDIO/HTTP), existing helpers, emulators.
+- `scripts/` — auxiliary scripts that might be reused.
+
+Identify and document:
+
+1. **Reusable artifacts** — functions/classes/types that already solve adjacent problems.
+   For each, cite `path/to/file.ts:<line>` and describe what it does.
+2. **Similar features/tools** — the implementation pattern to be replicated (do not reinvent).
+3. **Dependencies in `package.json`** — what is already installed and solves adjacent tasks.
+   Do not pull new npm packages without necessity.
+4. **SDK extension points** — which `fa-mcp-sdk` exports to use: `initMcpServer`, `appConfig`,
+   `formatToolResult`, `ToolExecutionError`, types `ToolWithHandler`, `IToolHandlerParams`,
+   `ITransportContext`, etc.
+5. **Configuration** — which new fields are needed in `config/default.yaml`, whether mapping in
+   `config/custom-environment-variables.yaml` is required, how to type them in `CustomAppConfig`.
+6. **Authentication / authorization** — if the feature introduces an endpoint or tool requiring
+   permissions, cross-check with `webServer.auth` and `jiraHeadersAuthValidator`-style patterns.
+7. **Duplication risks** — where logic might get duplicated; how to avoid it.
+
+The step's output is a "Reusable Artifacts" section, e.g.
+`src/lib/http-client.ts:42 — createHttpClient(): use for all requests with per-request auth`.
+
+### STEP 3 — Architecture Design
+
+Apply **multi-role thinking**:
+
+- **Architect**: system integrity, module boundaries, how the feature fits the SDK architecture
+  (tool vs prompt vs resource vs REST endpoint vs lib). Abstraction selection.
+- **Senior dev**: correctness, typing, error handling, idempotency, concurrency, performance,
+  transport compatibility (STDIO/HTTP/SSE).
+- **QA**: edge cases, failure modes, regressions, observability (logs, metrics).
+
+Describe:
+
+- The minimal sufficient solution (KISS).
+- Which **existing** abstractions are reused, which **new** ones are introduced — and why.
+- If alternatives exist — briefly list them with a justification for the chosen variant.
+- Data flow: `input → validation → action → formatting → output`.
+- SDK patterns: tool handler via `ToolWithHandler`, per-request context (`httpClient`, `logger`,
+  `mcpRequestHeaders`), response via `formatToolResult`, errors via `ToolExecutionError`.
+
+Explicit prohibitions:
+
+- Do not invent SDK methods/exports that do not exist. Cross-check with `FA-MCP-SDK-DOC/`.
+- Do not add "for the future" (YAGNI). Only what is required now.
+- Do not introduce a new npm dependency if the same task is solved by an existing one.
+
+### STEP 4 — Implementation Plan
+
+Table: each row is one file, one action.
+
+```
+<path/to/file> — <create | modify | delete> — <what exactly we do, one line>
+```
+
+Under each row — 2–5 specific bullets: which function, where exactly, with what signature.
+
+Group by layers in dependency order:
+
+1. Types (`src/_types_/*.ts`)
+2. Configuration (`config/*.yaml`, `src/bootstrap/*.ts`)
+3. Utilities / lib (`src/lib/*.ts`)
+4. Tool / prompt / resource / REST handler (`src/tools/**/*.ts` or `src/rest/*.ts`)
+5. Registration in `src/start.ts` (if needed)
+6. Tests (`tests/**`)
+7. Documentation (`CLAUDE.md`, `README.md`, `FA-MCP-SDK-DOC/*` — only if the feature genuinely
+   requires it)
+
+For each "create", reference an **existing template file** (file:line) whose pattern must be
+replicated. For each "modify" and "delete", verify via Read/Glob that the file actually exists.
+
+### STEP 5 — Code Examples
+
+Concrete TypeScript snippets:
+
+- Strict typing, no `any`, no stubs, no `TODO`/`FIXME`.
+- Signatures of new functions/classes.
+- Interfaces/DTOs with TSDoc on every field.
+- Tool-handler skeleton following the project pattern:
+
+  ```ts
+  import type { ToolWithHandler, ToolContext } from '../../_types_/tool.js';
+
+  export const <tool_name>: ToolWithHandler = {
+    name: '<tool_name>',
+    description: '...',
+    inputSchema: { type: 'object', properties: { /* ... */ }, required: [/* ... */] },
+    annotations: { title: '...', readOnlyHint: <bool>, destructiveHint: <bool> },
+    handler: async (args, ctx: ToolContext) => { /* ... */ },
+  };
+  ```
+
+- YAML config fragment and matching typing in `CustomAppConfig`.
+- SQL / migrations — only if the project actually uses a DB and the feature requires it.
+
+File names, imports (`.js` extensions for ESM), comment style — as used in the project
+(cross-check existing files and `CLAUDE.md`).
+
+### STEP 6 — Testing Strategy
+
+Describe:
+
+- **Unit tests** — which functions to cover; cases happy + edge + error.
+- **Integration tests** — if the project provides an MCP test runner
+  (`tests/mcp/<project>.js`, STDIO/HTTP transports) — describe scenarios for those mechanisms.
+- **Agent Tester / Headless API** — if the feature changes a tool and the project has an Agent
+  Tester (`/agent-tester/api/chat/test`): describe expected LLM behavior (which tool it picks,
+  with what arguments, how it formulates the answer).
+- **Manual checks** — `yarn build && yarn start`, then HTTP (curl/PowerShell) or an MCP client;
+  command + expected output.
+- **Edge cases** — empty input, invalid values, missing external service, concurrent calls,
+  limit overflow, network failure, 401/403/5xx.
+- **Response format** — structure of the success and error responses of the tool/API.
+
+Each test case: "action → expected result". Numbered.
+
+### STEP 7 — Execution Instructions
+
+Commands with expected output. **Check `package.json`** to use the correct package manager
+(`yarn` vs `npm`) and correct script names. Typical set:
+
+```bash
+<yarn|npm run> lint         # expect: 0 errors
+<yarn|npm run> typecheck    # expect: 0 errors
+<yarn|npm run> build        # expect: dist/ compiled
+<yarn|npm> test             # expect: all tests pass
+<yarn|npm> start            # expect: server boots, tools registered
+```
+
+Plus a smoke test of the feature itself: a concrete curl / MCP request / STDIO call with
+expected response.
+
+### STEP 8 — Success Criteria
+
+Binary checklist:
+
+- [ ] Tool `<name>` (or endpoint/prompt/resource) is registered and visible in the tools list.
+- [ ] Unit and integration tests are added and passing.
+- [ ] Lint + typecheck green.
+- [ ] New config fields are documented (`config/default.yaml` + `CLAUDE.md`, where appropriate).
+- [ ] No duplication with existing code (explicitly list what was reused).
+- [ ] All enumerated edge cases are covered by tests.
+- [ ] Observability: logs/errors are informative, no secrets leaked.
+
+## Multi-agent review (internal check before release)
+
+Run the result through three roles:
+
+**🏗️ Architect check**
+- Does the feature fit the SDK architecture without distortions?
+- Are existing abstractions reused?
+- Are there any extra layers / premature abstractions?
+
+**👨‍💻 Senior dev check**
+- Is the code strictly typed; are errors handled via `ToolExecutionError` / typed classes?
+- Any race conditions, leaks, unhandled rejections?
+- ESM imports with `.js` extensions? Project style followed?
+
+**🧪 QA check**
+- Are all edge cases covered by tests?
+- Are there tests for errors, not just the happy path?
+- How does the feature behave when external dependencies are missing (network, DB, auth service)?
+
+If any check fails — rework the prompt and only then release it.
+
+## Skill output
+
+The operator's response consists of two parts + mandatory saving to a file.
+
+### Mandatory saving of the result to a file
+
+**ALWAYS** after generation, save the result (Part A + Part B in full, exactly as it goes to the
+operator) into a **markdown file in the repository root**.
+
+- File name: `prop-<short-descriptive-name>.md`
+- `<short-descriptive-name>` — kebab-case, 2–6 English words capturing the feature's essence.
+  Examples: `prop-oauth2-token-refresh.md`, `prop-config-env-override.md`,
+  `prop-bulk-comment-tool.md`.
+- If a file with that name already exists — append a numeric suffix `-2`, `-3`, … **without
+  overwriting**.
+- File content — identical to what is printed in chat: Part A → separator → Part B
+  (including the heading `# === PROMPT FOR AI CLI — …`).
+- In the operator reply, explicitly state the path to the saved file.
+
+### Part A — brief summary for the operator
+
+- **Goal** (one sentence)
+- **Expanded problem statement** (2–5 lines)
+- **SDK components and affected layers** (tool/prompt/config/auth/...)
+- **3–5 key architectural decisions** (with justification)
+- **Reusable artifacts** (list with `file:line` paths)
+- **Explicit assumptions** (if any)
+- **Open questions** (if any remain)
+
+### Part B — self-sufficient prompt for the AI CLI
+
+Separate with an explicit heading:
+
+```
+# === PROMPT FOR AI CLI — <TICKET-ID | FEATURE-SLUG>: <title> ===
+```
+
+The prompt contains exactly 15 sections:
+
+1. **Context** — goal, components, affected layers.
+2. **Mandatory input reads** — list of files "read before starting":
+   `CLAUDE.md`, `package.json`, `FA-MCP-SDK-DOC/*.md` (if present), `config/default.yaml`,
+   `src/start.ts`, + targeted files by topic.
+3. **Preconditions** — system state, access, dependencies, environment variables.
+4. **Functional requirements** — numbered list of "what must work".
+5. **Non-functional requirements** — performance, security, logging, compatibility
+   (if critical — different transports / API versions), concurrency.
+6. **Workflow** — step-by-step "who → to whom → what → result".
+7. **Branches and errors** — explicit deviation cases and how they are handled
+   (via `ToolExecutionError`, HTTP codes, structured logs).
+8. **Interfaces** — tool `inputSchema` / REST signature / DTOs with sample payloads.
+9. **Data changes** — migrations/DDL, if the feature uses a DB; otherwise
+   "not required — feature without DB".
+10. **Change plan** — table "file → action → what we do" (from STEP 4).
+11. **Code examples** — concrete snippets (from STEP 5), with file headers and TSDoc.
+12. **Code standard** — short extract of project rules from `CLAUDE.md` + key SDK rules:
+    ESM imports with `.js` extension, use `appConfig` instead of reading config directly,
+    response via `formatToolResult`, strict typing.
+13. **Test cases** — numbered "action → expected result" (from STEP 6).
+14. **Execution instructions** — commands with expected outcomes (from STEP 7).
+15. **Success criteria** — checklist (from STEP 8).
+
+Hard rules for the prompt:
+
+- The prompt **does not reference** this skill. No phrases like "as said in the skill" or
+  "per the instructions above".
+- Do not leave `TODO`/`FIXME`, stubs, "code example omitted", `any`, empty sections.
+- If a section is not applicable — state it explicitly: "not required — <one-line reason>".
+- All paths — relative to the repository root, POSIX separators (`/`).
+- The prompt must read as a standalone spec — without knowledge that it was produced by a skill.
+
+## Anti-bullshit mode (hard prohibitions)
+
+- ❌ Inventing files, functions, exports, SDK methods. Only what is verified via Read/Grep/Glob
+  and/or documented in `FA-MCP-SDK-DOC/`.
+- ❌ Vague wording like "implement correctly", "handle properly". Specifics only: what, where, how.
+- ❌ "Bonus features" — do not add what was not asked for (YAGNI).
+- ❌ `any`, stubs, `throw new Error('Not implemented')`, `// TODO: ...`.
+- ❌ Suggesting to rewrite adjacent modules if not asked (Surgical changes).
+- ❌ Hardcoding secrets, URLs, credentials — only via `appConfig` / ENV.
+- ✅ All disputable decisions — EXPLICITLY as `ASSUMPTION:` with rollback possibility.
+
+## Quality gate before release (mandatory checklist)
+
+- [ ] Part B contains all 15 sections, or an explicit "not required — …" with justification.
+- [ ] Every cited source file actually exists (verified via Read/Glob).
+- [ ] Every reusable function is cited with a `file:line` path.
+- [ ] No references to "see the skill" / "as agreed earlier" / "per our conversation".
+- [ ] Code examples are compilable: types imported, no `any`, TSDoc present, correct
+      `.js` extensions in ESM imports.
+- [ ] Execution commands match `package.json` (correct package manager and script names).
+- [ ] Tests cover edge cases and errors, not just the happy path.
+- [ ] All three reviews passed: Architect, Senior dev, QA.
+- [ ] Result saved to `prop-<kebab-name>.md` in the repository root; path reported to the operator.
+
+If at least one item fails — improve the prompt, then release.

package/cli-template/.claude/skills/readme-generator/README.md

@@ -0,0 +1 @@
+https://www.skillsdirectory.com/skills/armanzeroeight-readme-generator?utm_source=chatgpt.com

package/cli-template/.claude/skills/readme-generator/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: readme-generator
+description: Generates structured, user-friendly README.md for MCP servers built with fa-mcp-sdk. Detects which SDK subsystems are enabled (Consul, AD, DB, Admin Panel, Agent Tester, Webhooks, etc.) and which project-specific features exist, then decides which sections to inline vs. move to satellite readme-docs/*.md files. Use when creating or refreshing README for an fa-mcp-sdk-based MCP server project.
+---
+
+# MCP Server README Generator
+
+Generates a `README.md` tailored to MCP servers built on `fa-mcp-sdk`. The README answers three
+progressive questions — *what is this?*, *how do I use it?*, *how do I operate it?* — without
+drowning casual readers in operational detail.
+
+## Philosophy
+
+Three-level information hierarchy:
+
+**Level 1 — What & how to use it (first 30 seconds for the consumer)**
+
+- What this MCP server is for
+- What tools it exposes
+- How to connect from Claude Code / Claude Desktop / Qwen Code (the simplest path)
+
+**Level 2 — Features & basics (interested reader)**
+
+- Enabled fa-mcp-sdk subsystems, project-specific capabilities, transports, essential config
+
+**Level 3 — Operations (deployer / maintainer)**
+
+- Build & run, full configuration, deep technical topics
+
+Level 1 and 2 live in the main README. Level 3 content longer than ~15 lines moves to satellite
+Markdown files under `readme-docs/`. The main README stays scannable; deep detail is one click away.
+
+## The `readme-docs/` folder is load-bearing
+
+Satellite Markdown files **must** live in `readme-docs/` at the project root. The fa-mcp-sdk
+`doc://readme` MCP resource looks for exactly that folder name: on server start it reads
+`README.md`, finds every link pointing into `readme-docs/`, appends those satellite files (each
+separated by `\n\n---\n\n`) and rewrites the in-text links to `See "<heading>" below` so the
+assembled document reads naturally.
+
+This means:
+
+- The entire documentation is delivered through `doc://readme` as one searchable markdown
+  document — essential for the MCP registry's RAG indexing.
+- Any satellite file *not* linked from `README.md` is **not** included in the resource. If you
+  add a new `readme-docs/*.md` file, link to it from the main README.
+- Do not rename the folder. Any other name (`docs/`, `doc/`, `readme-parts/` etc.) will be
+  ignored by the SDK and the satellite content will not reach RAG.
+
+## Dynamic detection is mandatory
+
+The set of satellite files is **not fixed**. The skill inventories the project, decides per feature
+whether it is enabled, and only then produces the matching README sections and `readme-docs/*.md` files.
+**Do not create a satellite file for a disabled feature.** Do not emit empty sections.
+
+## Workflow
+
+### Step 1 — Inventory the project
+
+Collect, from the actual repository:
+
+**Metadata**
+
+- `package.json` → `name`, `version`, `description`, `dependencies`
+- Git remote URL, license file
+
+**Configuration** (merge `config/default.yaml` with `config/local.yaml` if present)
+
+- `webServer.port` — default port for Quick Start commands
+- Custom per-request header names (grep `x-<prefix>-` in `src/`)
+- Enabled/disabled status for each optional subsystem (see table below)
+
+**Code surface**
+
+- `src/tools/` — tool list + each tool's domain group
+- `src/start.ts` — transports registered, custom auth validators
+- `src/api/` — existence + routes (custom REST API)
+- `src/prompts/` — existence + prompt list
+- `src/custom-resources.ts` — existence
+- `.claude/skills/*/SKILL.md` — catalog of in-project skills
+
+**Optional fa-mcp-sdk subsystems — detect each**
+
+| Subsystem                        | Detect via                                           | Enabled marker          |
+|----------------------------------|------------------------------------------------------|-------------------------|
+| Consul (service discovery)       | `consul.service.enable`                              | `true`                  |
+| Active Directory (group checks)  | `ad.domains.*`                                       | non-empty               |
+| PostgreSQL (with pgvector)       | `db.*` + imports from `pg-db.js`                     | both present            |
+| Custom REST API                  | `src/api/` + `webServer.customApi.*`                 | folder non-empty        |
+| Prompts                          | `src/prompts/`                                       | folder non-empty        |
+| Custom Resources                 | `src/custom-resources.ts`                            | file exists             |
+| Admin Panel (token UI)           | `adminPanel.enabled`                                 | `true`                  |
+| Agent Tester + Headless API      | `agentTester.enabled`                                | `true`                  |
+| Swagger UI                       | `swagger.enabled`                                    | `true`                  |
+| Cache (node-cache)               | `cache.*` referenced in `src/`                       | used                    |
+| Webhook callback (`x-web-hook`)  | `x-web-hook` in `src/` OR tool handler returns `hook` | used                   |
+| Impersonation (`x-on-behalf-of-user`) | `impersonalizationPlugin.*` in config          | present                 |
+| JWT auth                         | `webServer.auth.jwt.*` or `webServer.genJwtApiEnable` | present/true           |
+| Configurable tool set            | `<upstream>.usedInstruments`                         | present                 |
+
+**Project-specific capabilities** — anything non-trivial not covered above:
+
+- Fuzzy entity resolution, batch-operation limits, per-endpoint caching strategy,
+  API-version auto-detection (Cloud vs Server), automatic labeling of created entities,
+  required-fields pre-flight validation, content-format conversion (Markdown ↔ ADF / Storage
+  Format), etc.
+- Any tool-group-specific quirks worth highlighting.
+
+Record all findings in a working note — they drive the decisions in the next step.
+
+### Step 2 — Classify findings: drop / inline / satellite
+
+For each finding, pick placement:
+
+- **Drop** — feature not used; no section, no satellite file.
+- **Inline** — description ≤ ~15 lines. Put a short subsection in the main README.
+- **Satellite** — description > ~15 lines, OR the topic contains reference tables, priority rules,
+  request/response schemas, long examples. Create `readme-docs/<kebab-name>.md` and link to it from the
+  main README with a 2–3 sentence summary.
+
+**Always satellite** (do not inline even if short):
+
+- Authentication resolution order / priority tables
+- Webhook body schema + per-tool hook priority rules
+- Headless Agent Tester full argument list and scenario matrix
+- Full configuration reference tables (> 15 parameters)
+- Consul / AD / Database detailed setup
+
+**Always inline in the main README** (never moved out):
+
+- Tool list (grouped table) — users need to see the API surface
+- Quick Start commands
+- **MCP Client Integration** JSON snippets (Claude Code / Desktop / Qwen Code) — adapted to this
+  server's actual custom header names
+- Key Features bullet list
+
+### Step 3 — Build main README section list
+
+Canonical section order. Include only sections backed by actual findings; omit anything empty.
+
+1. **Title + one-line description** (from `package.json`)
+2. **Badges** — build, license, language, key stack badges via shields.io
+3. **Overview** — 2–4 sentences. Answers: what is this, for whom, core value
+4. **Tools** — grouped table, `## Tools (<count>)` with per-domain `###` subsections
+5. **Quick Start** — install, run, minimal verification (3 short steps)
+6. **MCP Client Integration** — Claude Code (HTTP), Claude Desktop (STDIO + `mcp-remote` /
+   direct STDIO), Qwen Code. Use the server's actual custom header names
+   (e.g. `x-jira-token`, `x-wiki-username`)
+7. **Key Features** — 5–8 bullets. Include enabled SDK subsystems and project-specific capabilities
+8. **Transports** — short bulleted list with endpoints (`/mcp`, `/api/*`, `/docs`, `/health`,
+   `/admin`, `/agent-tester`, STDIO for Claude Desktop)
+9. **Configuration Basics** — 5–10 most important keys in a compact table; link to
+   `readme-docs/configuration.md` when the full reference is long
+10. **Build & Run / Deployment** — minimal commands, environment variables
+11. **Authentication** — 2–4 sentences + link to `readme-docs/authentication.md` (satellite is mandatory
+    when non-trivial auth is present)
+12. **Feature sections (dynamic)** — one short subsection per enabled optional subsystem and per
+    notable project-specific capability. Each: 2–3 sentences + link to its `readme-docs/*.md` when a
+    satellite is warranted. Typical candidates:
+    - Consul service discovery → `readme-docs/consul.md`
+    - Active Directory integration → `readme-docs/active-directory.md`
+    - PostgreSQL / pgvector → `readme-docs/database.md`
+    - Custom REST API → link to Swagger UI (`/docs`) and/or `readme-docs/api.md`
+    - Admin panel → inline or `readme-docs/admin-panel.md`
+    - Agent Tester + Headless API → `readme-docs/testing.md`
+    - Webhook callback → `readme-docs/webhooks.md`
+    - Impersonation → `readme-docs/impersonation.md`
+    - Project-specific: fuzzy resolution, caching strategy, API version detection, batch limits,
+      content-format conversion, etc. → `readme-docs/<topic>.md` as appropriate
+13. **Skills** — short paragraph linking to `SKILL_README.md` in repo root (kept at root by
+    convention established in existing fa-mcp-sdk projects)
+14. **Stack** — 4–7 bullets: framework (`fa-mcp-sdk`), transport, language, key libs
+15. **License**
+
+### Step 4 — Generate `README.md`
+
+Apply the canonical section order from Step 3. Respect these rules:
+
+- H1 is the project name only — no duplicate title in the next line.
+- Tool table column widths consistent within the file. Tool names as inline code.
+- Every code fence has a language specifier (` ```bash `, ` ```json `, ` ```yaml `, ` ```typescript `).
+- `webServer.port` in commands matches the actual value from `config/default.yaml`.
+- Custom header names in Client Integration snippets match what the server actually reads.
+- Relative links for internal references: `[…](./readme-docs/authentication.md)`.
+- Line length ≤ 120 chars where practical. Exceptions: URLs, code blocks, tables.
+- No marketing superlatives. Active voice. Short paragraphs (2–4 sentences).
+
+See `reference/templates.md` for canonical blocks.
+
+### Step 5 — Generate satellite `readme-docs/*.md` files
+
+For each finding classified as *satellite* in Step 2, create a Markdown file under `readme-docs/` (create
+the folder if missing). Use `reference/satellite-templates.md` as a starting point — skeletons are
+provided for common topics (authentication, testing, webhooks, consul, active-directory, database,
+configuration). **Adapt every skeleton to actual values from the project.**
+
+For project-specific capabilities (fuzzy resolution, custom endpoints, etc.) compose a new
+`readme-docs/<kebab-name>.md` with sections: *Overview*, *How it works*, *Configuration*, *Examples*.
+
+Every satellite MD begins with a 1-sentence summary so it stands alone when opened directly.
+
+### Step 6 — Update `SKILL_README.md`
+
+If `.claude/skills/` is non-empty, regenerate `SKILL_README.md` in the repository root. Keep the
+existing format (seen in mcp-jira / mcp-wiki): per-skill sections with command, launch mode,
+arguments table, examples. **Do not move this file into `readme-docs/`** — the projects' convention keeps
+it at the root.
+
+### Step 7 — Validate
+
+Run through this checklist before declaring done:
+
+- [ ] Canonical section order followed; no empty headings
+- [ ] Every section in the main README is ≤ ~40 lines, or split into a satellite
+- [ ] Tool count in the `## Tools (<count>)` heading matches the table
+- [ ] Every satellite link resolves to an existing file in `readme-docs/`
+- [ ] No satellite file for a disabled feature
+- [ ] `webServer.port` in all commands matches `config/default.yaml`
+- [ ] Custom header names in Client Integration match those the server parses
+- [ ] JSON snippets are valid JSON; YAML snippets are valid YAML
+- [ ] Every code fence has a language tag
+- [ ] Relative links use `./readme-docs/...` form
+- [ ] Line length ≤ 120 chars outside URLs / code / tables
+- [ ] Previous README backed up to `README.backup.md` when rewriting
+
+## Output
+
+1. `README.md` — restructured per canonical order
+2. `readme-docs/<topic>.md` — one per satellite topic, only those the project needs
+3. `SKILL_README.md` — regenerated if `.claude/skills/` is present
+4. `README.backup.md` — backup of previous README when rewriting
+
+## References
+
+- `reference/templates.md` — canonical section blocks for the main README
+- `reference/satellite-templates.md` — skeletons for common `readme-docs/*.md` files
+- `reference/best-practices.md` — writing style and formatting guidelines