fa-mcp-sdk 0.4.52 → 0.4.54

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

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

@@ -0,0 +1,218 @@
+# Documentation Best Practices
+
+## Writing Style
+
+### Be Clear and Concise
+
+**Good:**
+> Install the package using npm.
+
+**Bad:**
+> You can install this package by utilizing the npm package manager which is included with Node.js.
+
+### Use Active Voice
+
+**Good:**
+> The function returns a promise.
+
+**Bad:**
+> A promise is returned by the function.
+
+### Write for Your Audience
+
+- **Developers**: Include technical details, API references
+- **End Users**: Focus on features, benefits, screenshots
+- **Contributors**: Explain architecture, setup, testing
+
+## Structure
+
+### Start with the Most Important Information
+
+1. What is it?
+2. Why should I use it?
+3. How do I get started?
+
+### Use Headings Effectively
+
+```markdown
+# Main Title (H1) - Only one per document
+
+## Major Sections (H2)
+
+### Subsections (H3)
+
+#### Details (H4) - Use sparingly
+```
+
+### Keep Paragraphs Short
+
+- 2-4 sentences per paragraph
+- One idea per paragraph
+- Use bullet points for lists
+
+## Code Examples
+
+### Make Examples Runnable
+
+**Good:**
+```javascript
+const api = require('my-api');
+api.connect('https://api.example.com');
+const users = await api.getUsers();
+console.log(users);
+```
+
+**Bad:**
+```javascript
+// Connect to API
+api.connect(url);
+// Get users
+getUsers();
+```
+
+### Show Expected Output
+
+```javascript
+const result = add(2, 3);
+console.log(result);
+// Output: 5
+```
+
+### Include Error Handling
+
+```javascript
+try {
+  const data = await fetchData();
+} catch (error) {
+  console.error('Failed to fetch:', error.message);
+}
+```
+
+## Formatting
+
+### Use Consistent Terminology
+
+Pick one term and stick with it:
+- "function" not "function/method/procedure"
+- "parameter" not "parameter/argument/input"
+
+### Format Code Inline
+
+Use backticks for:
+- Function names: `getData()`
+- Variables: `userId`
+- File names: `config.json`
+- Commands: `npm install`
+
+### Use Tables for Comparisons
+
+| Feature | Option A | Option B |
+|---------|----------|----------|
+| Speed   | Fast     | Slow     |
+| Memory  | Low      | High     |
+
+## Common Sections
+
+### Installation
+
+Always include:
+- Prerequisites (if any)
+- Installation command
+- Verification step
+
+```markdown
+## Installation
+
+**Prerequisites:** Node.js 18+
+
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+Verify installation:
+\`\`\`bash
+package-name --version
+\`\`\`
+```
+
+### Configuration
+
+Show default values:
+
+```markdown
+## Configuration
+
+\`\`\`json
+{
+  "timeout": 5000,     // Default: 5000ms
+  "retries": 3,        // Default: 3
+  "debug": false       // Default: false
+}
+\`\`\`
+```
+
+### Troubleshooting
+
+Address common issues:
+
+```markdown
+## Troubleshooting
+
+### Error: "Module not found"
+
+**Cause:** Package not installed
+
+**Solution:**
+\`\`\`bash
+npm install missing-package
+\`\`\`
+```
+
+## Maintenance
+
+### Keep Documentation Updated
+
+- Update docs with code changes
+- Review docs during code review
+- Mark deprecated features clearly
+
+### Version Documentation
+
+```markdown
+## Version 2.0.0 (Breaking Changes)
+
+- Removed: `oldFunction()`
+- Changed: `newFunction()` now returns Promise
+- Added: `anotherFunction()`
+```
+
+### Link to External Resources
+
+```markdown
+For more information, see:
+- [Official Docs](https://example.com/docs)
+- [API Reference](https://example.com/api)
+- [Tutorial](https://example.com/tutorial)
+```
+
+## Accessibility
+
+### Use Descriptive Link Text
+
+**Good:**
+> See the [installation guide](link) for details.
+
+**Bad:**
+> Click [here](link) for more information.
+
+### Provide Alt Text for Images
+
+```markdown
+![Dashboard showing user analytics with graphs](screenshot.png)
+```
+
+### Use Semantic Markdown
+
+- Use proper heading hierarchy
+- Use lists for lists
+- Use code blocks for code