fa-mcp-sdk 0.4.57 → 0.4.58

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

@@ -30,6 +30,26 @@ Three-level information hierarchy:
 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.
 
+### Scannability devices: Quick Links + collapsible blocks
+
+Two devices keep the main README scannable even when it carries substantial inline content:
+
+- **Quick Links** — a short navigation block right after the badges, pointing to the *major* sections
+  a reader is likely to jump to. Include only headline topics (Tools, Quick Start, MCP Client
+  Integration, Key Features, Configuration, Build & Run, Authentication, and any enabled feature
+  sections that have their own heading — Impersonation, Admin Panel, Webhooks, Agent Tester, Skills,
+  etc.). Do **not** dump a full TOC: secondary headings such as Overview, Transports, Stack, License
+  stay out; minor sub-subsections stay out. Rule of thumb: 8–14 links, never more.
+- **Collapsible `<details>` blocks** — wrap content that *must* appear inline (so the `doc://readme`
+  RAG pipeline picks it up as part of the main document) but whose volume would drown neighbouring
+  sections on a casual scroll. The canonical case is the grouped Tools table (often 100+ rows across
+  a dozen sub-tables). Use `<details>` when all three hold: (1) content belongs in this section,
+  (2) it is long enough to push everything below off-screen, (3) a casual reader doesn't need every
+  row right away. Do **not** use `<details>` for content readers need at a glance (Quick Start
+  commands, Key Features bullets, the compact Configuration Basics table, Integration snippets).
+  See `reference/templates.md` for the required markup (the `<br>` after `</summary>` is mandatory —
+  GitHub won't render the first child block correctly without it).
+
 ## The `readme-docs/` folder is load-bearing
 
 Satellite Markdown files **must** live in `readme-docs/` at the project root. The fa-mcp-sdk
@@ -140,21 +160,26 @@ Canonical section order. Include only sections backed by actual findings; omit a
 
 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` /
+3. **Quick Links** — 8–14 anchor links to the major sections only (see *Scannability devices*
+   above for the inclusion rule and `reference/templates.md` for the canonical block)
+4. **Overview** — 2–4 sentences. Answers: what is this, for whom, core value
+5. **Tools** — grouped table, `## Tools (<count>)` with per-domain `###` subsections.
+   Wrap the whole tool-group listing in a `<details>` block (see the *collapsible blocks* rule
+   above). The `## Tools (<count>)` heading itself stays *outside* the block so it is visible on
+   scroll and anchor-linkable from Quick Links
+6. **Quick Start** — install, run, minimal verification (3 short steps)
+7. **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`,
+8. **Key Features** — 5–8 bullets. Include enabled SDK subsystems and project-specific capabilities
+9. **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
+10. **Configuration Basics** — 5–10 most important keys in a compact table; link to
+    `readme-docs/configuration.md` when the full reference is long
+11. **Build & Run / Deployment** — minimal commands, environment variables
+12. **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
+13. **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`
@@ -167,10 +192,13 @@ Canonical section order. Include only sections backed by actual findings; omit a
     - 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 `readme-docs/SKILLS.md` (kept under `readme-docs/`
+
+   Anchor rule: any feature section that is referenced from **Quick Links** must live at `##` level
+   (not `###`), so the anchor resolves from the top of the document.
+14. **Skills** — short paragraph linking to `readme-docs/SKILLS.md` (kept under `readme-docs/`
     so it is picked up as a satellite and assembled into the `doc://readme` resource)
-14. **Stack** — 4–7 bullets: framework (`fa-mcp-sdk`), transport, language, key libs
-15. **License**
+15. **Stack** — 4–7 bullets: framework (`fa-mcp-sdk`), transport, language, key libs
+16. **License**
 
 ### Step 4 — Generate `README.md`
 
@@ -211,7 +239,14 @@ to it from the main README's **Skills** section.
 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
+- [ ] **Quick Links** block is present, sits right after the badges, has 8–14 entries covering
+      only major sections, and every anchor resolves to an existing `##` heading in the file
+- [ ] **Tools** section is wrapped in `<details><summary>Expand to view ...</summary><br>` with
+      the heading `## Tools (<count>)` kept *outside* the block
+- [ ] No `<details>` used to hide content readers need at a glance (Quick Start commands,
+      Key Features, Configuration Basics table, Integration snippets)
+- [ ] Every section in the main README is ≤ ~40 lines (or wrapped in `<details>`, 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

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

@@ -32,6 +32,36 @@
 2. Why should I use it?
 3. How do I get started?
 
+### Progressive disclosure
+
+A long README is fine — a *cluttered* one is not. Two devices shrink perceived volume without
+dropping information the RAG pipeline needs:
+
+- **Quick Links** right after the badges. List only the major `##` sections (8–14 entries),
+  never a full TOC. The reader who knows what they want jumps; the reader who is browsing
+  ignores the list and keeps scrolling.
+- **`<details>` collapsible blocks** for sections that *must* live inline but would otherwise
+  dominate the page — the canonical case is a grouped tool listing that runs 100+ lines. The
+  heading stays visible and anchor-linkable; the bulk is one click away.
+
+Reach for `<details>` only when the content (a) belongs in this section, (b) is long enough to
+push the next section off-screen, and (c) is not needed at a glance. Do *not* hide Quick Start
+commands, Key Features bullets, a compact config table, or integration snippets.
+
+Required markup (GitHub Markdown):
+
+```markdown
+<details><summary>Expand to view <what is inside></summary><br>
+
+
+<bulky content>
+
+</details>
+```
+
+The `<br>` after `</summary>` is mandatory — GitHub otherwise collapses the first child block
+against the summary line.
+
 ### Use Headings Effectively
 
 ```markdown

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

@@ -38,6 +38,47 @@ Prefer shields.io. Include only badges that are meaningful (skip build status if
 
 ---
 
+## 2a. Quick Links
+
+Navigation block for the main README. Sits immediately after the badges, before **Overview**. Lists
+only the major sections a reader is likely to jump to — never a full TOC.
+
+**Inclusion rule.** Include a link for every `##` section that is either (a) one of the headline
+topics below, or (b) a dynamic feature section produced in Step 3 of the workflow (Impersonation,
+Admin Panel, Webhooks, Agent Tester, Consul, Active Directory, Database, …). Exclude Overview,
+Transports, Stack, License, and every `###` sub-subsection. Target 8–14 entries.
+
+```markdown
+## Quick Links
+
+- [Tools](#tools)
+- [Quick Start](#quick-start)
+- [MCP Client Integration](#mcp-client-integration)
+- [Key Features](#key-features)
+- [Configuration](#configuration-basics)
+- [Build & Run](#build--run)
+- [Authentication](#authentication)
+- [Impersonation](#impersonation)
+- [Admin Panel](#admin-panel)
+- [Webhooks](#webhooks)
+- [Agent Tester + Headless Agent Tester API](#agent-tester)
+- [Claude Code Skills](#claude-code-skills)
+```
+
+**Anchor-slug rules (GitHub Markdown).**
+
+- Lowercase the heading, replace spaces with `-`, strip punctuation (`,`, `.`, `:`, `?`, `!`, `()`).
+- `&` is dropped entirely and produces a double dash — `Build & Run` → `#build--run`.
+- `+` is dropped — `Agent Tester + Headless API` → `#agent-tester--headless-api`.
+- If the Quick Links label diverges from the exact heading text, anchor to the heading, not the
+  label (label is for humans, anchor must match the section's slug).
+- When two headings collide (e.g. two `## Configuration`), GitHub appends `-1`, `-2`; avoid that by
+  using distinct headings.
+
+Verify every anchor resolves after assembly — dead Quick Links are worse than no Quick Links.
+
+---
+
 ## 3. Overview
 
 2–4 sentences. Answer: *what is this / for whom / core value*. Active voice. No marketing fluff.
@@ -56,23 +97,41 @@ distinguishing features>. Use it when you need <primary use case>.
 
 Group by domain. Keep rows short — one-line descriptions only.
 
-```markdown
+The full grouped listing is wrapped in a `<details>` block so it doesn't dominate the page on first
+scroll. The `## Tools (<N>)` heading itself stays *outside* the block — it must remain visible and
+anchor-linkable from **Quick Links**.
+
+````markdown
 ## Tools (<N>)
 
+<details><summary>Expand to view detailed list of tools</summary><br>
+
+
+All tool names are prefixed with `<prefix>_`. Tools can be selectively enabled via
+`<upstream>.usedInstruments` — see [Configuration](./readme-docs/configuration.md).
+
 ### <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:
+</details>
+````
 
+Formatting rules specific to this block:
+
+- `<br>` immediately after `</summary>` is **mandatory** — without it GitHub collapses the first
+  child block against the summary line.
+- Keep one blank line between `<summary>` and the first `###` subsection, and one blank line
+  before `</details>`.
 - 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
@@ -383,3 +442,47 @@ Details, launch modes, and examples: [SKILLS](./readme-docs/SKILLS.md).
 
 <License name> © <Owner>. See [LICENSE](./LICENSE).
 ```
+
+---
+
+## 16. Collapsible `<details>` block (generic pattern)
+
+Use this pattern for any section where the content is important enough to stay inline (so the
+`doc://readme` RAG pipeline captures it) but bulky enough to drown neighbouring sections on a
+casual scroll. Canonical use: the Tools listing (see section 4). Other legitimate uses: long
+example request/response matrices, exhaustive troubleshooting tables, verbose per-endpoint
+catalogues.
+
+**Checklist before reaching for `<details>`:**
+
+1. The content must appear *in this section* (cannot be moved to a satellite file without
+   losing context).
+2. It spans enough lines that a reader scrolling past this section loses sight of the next
+   section on a standard screen.
+3. A casual first-time reader does not need every line immediately — the summary label alone
+   tells them what's hidden.
+
+If any of the three fails, either inline it normally or move it to `readme-docs/`.
+
+```markdown
+## <Section heading stays outside>
+
+<Optional 1–3 sentence intro stays outside too — gives readers enough to decide whether to expand.>
+
+<details><summary>Expand to view <what is inside>: <e.g. "detailed list of tools" /
+"full request/response schema" / "per-endpoint example matrix"></summary><br>
+
+
+<bulky content: tables, code blocks, nested subsections — anything markdown supports>
+
+</details>
+```
+
+**Do NOT wrap in `<details>`:**
+
+- Quick Start commands
+- Key Features bullet list
+- Configuration Basics table (short by design)
+- MCP Client Integration JSON snippets
+- Transports listing
+- Anything under ~20 lines

package/cli-template/package.json

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

package/package.json

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