fa-mcp-sdk 0.4.66 → 0.4.68

package/cli-template/.claude/skills/deploy-mcp/SKILL.md

@@ -260,7 +260,11 @@ Follow the plan. For each tool/resource/prompt:
    leave demo code in the final build.
 2. Add new config keys to `config/default.yaml` (and matching env mappings in
    `config/custom-environment-variables.yaml` when appropriate). Mirror structural changes
-   in `config/_local.yaml`.
+   in `config/_local.yaml`. **If the feature talks to any third-party / external service
+   (REST API, legacy system, partner endpoint), put its connection attributes — `host`,
+   `port`, `protocol`, `token`, credentials, custom fields — under the `accessPoints` block,
+   not ad-hoc sections. See `FA-MCP-SDK-DOC/03-configuration.md` → "Access Points" for the
+   YAML shape and access pattern.**
 3. Update `tests/mcp/test-cases.js` with real cases.
 4. `yarn cb` after each meaningful change; don't accumulate type errors.
 

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

@@ -15,7 +15,7 @@ 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, cache, PostgreSQL | Server configuration, DB |
+| [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points for external services, cache, PostgreSQL | Server configuration, external services, DB |
 | [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 |

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

@@ -62,65 +62,208 @@ 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
+### Outbound Webhooks (`x-web-hook`)
 
-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).
+Handler-level pattern. The SDK does **not** ship a built-in webhook dispatcher — it exposes
+everything you need (`params.headers`, `appConfig`, `logger`) and leaves the policy to the project.
+This section is the **canonical recipe**: implement it as written so every fa-mcp-sdk-based MCP
+server behaves the same way for clients and downstream collectors.
 
-**Recipe:**
+**What it is:** after every tool invocation the server can `POST` the tool result to an external
+URL. Useful for audit trails, real-time dashboards, chaining MCP calls into CI/automation pipelines.
+Opt-in per request (via header) and optionally per tool (via the response object). A failing webhook
+**must never** fail the tool call.
 
-1. **Declare the header** so Agent Tester and `use://http-headers` advertise it:
+#### Contract (stable across all MCPs)
 
-   ```typescript
-   usedHttpHeaders: [
-     { name: 'x-web-hook', description: 'URL to POST the tool result to.', isOptional: true },
-   ],
-   ```
+**Inbound — precedence:**
 
-2. **Dispatch inside the handler** — fire-and-forget, never throw, never block the reply:
+| Source              | Form                                                    | Precedence |
+|---------------------|---------------------------------------------------------|------------|
+| Per-tool override   | `IToolResponse.hook: string` returned by the handler    | wins       |
+| Per-request header  | `x-web-hook: <http(s) URL>`                             | fallback   |
 
-   ```typescript
-   import axios from 'axios';
-   import { appConfig, logger, toStr, IToolHandlerParams } from 'fa-mcp-sdk';
+If neither is present, no webhook fires.
 
-   const URL_REGEX = /^https?:\/\/[^\s]+$/i;
+**Outbound request:**
 
-   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)}`));
-   };
+- Method: `POST`, `Content-Type: application/json`, timeout ≤ 10 000 ms
+- Body:
 
-   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);
-   };
-   ```
+```json
+{
+  "mcpName": "<appConfig.name>",
+  "tool": "<tool_name>",
+  "user": "<caller-id-or-omitted>",
+  "response": { "...": "tool's full JSON result" }
+}
+```
+
+| Field      | Description                                                                  |
+|------------|------------------------------------------------------------------------------|
+| `mcpName`  | `appConfig.name` — identifies which MCP sent the callback                    |
+| `tool`     | Name of the invoked tool                                                     |
+| `user`     | Best-effort caller identity (see *User resolution*); **omit** if unresolved  |
+| `response` | Full JSON returned by the tool handler (same payload sent to the client)     |
+
+Do **not** add ad-hoc fields on a per-project basis without versioning the body — downstream
+collectors rely on this exact shape.
+
+#### Implementation recipe
+
+**1. Declare the header** so `use://http-headers`, Agent Tester, and tool-call introspection
+advertise it:
+
+```typescript
+// src/start.ts
+usedHttpHeaders.push({
+  name: 'x-web-hook',
+  description:
+    'Optional URL called via POST after each tool invocation. '
+    + 'Body: { mcpName, tool, user, response }. Fire-and-forget; failures are logged only.',
+  isOptional: true,
+});
+```
+
+**2. Add `hook?` to the internal tool-response type** (lets a handler override the URL per tool):
+
+```typescript
+// src/_types_/tool.ts
+export interface IToolResponse {
+  text: string;
+  json: Record<string, any>;
+  hook?: string; // per-tool URL override; takes precedence over x-web-hook header
+}
+```
+
+**3. Dispatcher — fire-and-forget, never throws:**
+
+```typescript
+// src/tools/tools-manager.ts
+import axios from 'axios';
+import { appConfig, logger as lgr, toStr } from 'fa-mcp-sdk';
+
+const logger = lgr.getSubLogger({ name: 'tools' });
+const URL_REGEX = /^https?:\/\/[^\s]+$/i;
+
+const callWebHook = (
+  url: string,
+  toolName: string,
+  json: Record<string, any>,
+  user?: string,
+): void => {
+  if (!URL_REGEX.test(url)) { return; }                 // silently drop garbage URLs
+  const body = { mcpName: appConfig.name, tool: toolName, response: json, user };
+  axios.post(url, body, { timeout: 10_000 })
+    .catch((err) => logger.warn(`Web-hook POST ${url} failed: ${toStr(err?.message || err)}`));
+};
+```
+
+Rules:
 
-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:
+- **No `await`.** The webhook must not delay the MCP response.
+- **No re-throws.** A 5xx, timeout, or DNS failure is a `warn` log, nothing more.
+- **URL allow-list.** At minimum, require `http(s)://`. Add an internal-net allow-list via config
+  (e.g. `webhook.allowedHosts`) if the threat model requires it (see *Security*).
 
-   ```typescript
-   export interface IToolResponse { text: string; json: Record<string, any>; hook?: string; }
-   ```
+**4. Wire it into the tool-call entry point** — dispatch after the handler resolves and before
+the result is returned:
 
-**Body contract** (recommended; keep stable across tools):
+```typescript
+export const handleToolCall = async (params: IToolHandlerParams): Promise<any> => {
+  const { name: toolName, arguments: args, headers: mcpRequestHeaders = {} } = params;
+
+  const tool = (await getTools(mcpRequestHeaders)).get(toolName);
+  if (!tool?.handler) { throw new ToolExecutionError(toolName, `Unknown tool: ${toolName}`); }
+
+  const ctx: ToolContext = {
+    httpClient: createHttpClient(mcpRequestHeaders),
+    logger: logger.getSubLogger({ name: toolName }),
+    mcpRequestHeaders,
+  };
+
+  const toolResponse: IToolResponse = await tool.handler(args, ctx);
+
+  // ─── webhook dispatch (fire-and-forget) ─────────────────────────────────────
+  const hookUrl = (toolResponse?.hook || mcpRequestHeaders['x-web-hook'] || '').trim();
+  if (hookUrl) {
+    const syncUser = resolveActualUser(mcpRequestHeaders);     // see step 5
+    if (syncUser) {
+      callWebHook(hookUrl, toolName, toolResponse.json, syncUser);
+    } else {
+      // Async user resolution — still fire-and-forget; do not block the tool response.
+      getCachedSelfUser(ctx.httpClient, mcpRequestHeaders)
+        .then((u) => callWebHook(hookUrl, toolName, toolResponse.json, u));
+    }
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
+  return formatToolResult(toolResponse);
+};
+```
 
-| 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 |
+**5. User resolution — best-effort, two-step.** The `user` field is what makes the webhook useful
+for audit. Resolve carefully, but never let resolution fail the call.
+
+- **Step A — Sync (preferred):** derive from headers / JWT payload / config without I/O
+  (e.g. JWT `payload.user`, a custom `x-actual-user` header your auth layer stamps, etc.).
+- **Step B — Async fallback (only when sync returns nothing):** call the upstream "who am I"
+  endpoint with the same auth, **cache the result** (recommended TTL: 1 h, key by hashed
+  `Authorization`), and dedupe in-flight requests (thundering-herd protection).
+- If both steps fail → **omit** the `user` field. Never invent a placeholder like `"unknown"`.
+
+```typescript
+export function resolveActualUser (headers: Record<string, string>): string | undefined { /* … */ }
+
+export const getCachedSelfUser = async (
+  httpClient: AxiosInstance,
+  headers: Record<string, string>,
+): Promise<string | undefined> => { /* GET /me, cache by hashed Authorization, dedupe */ };
+```
+
+#### Per-tool override — when to use
+
+A handler may force a specific webhook URL:
+
+```typescript
+return { text, json, hook: 'https://collector.internal/special' };
+```
 
-**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.
+Use sparingly. Legitimate cases:
+
+- a long-running tool whose result feeds a fixed pipeline regardless of the client;
+- a tool that should **never** webhook (e.g. read of a secret) — return `hook: ''` only if the
+  dispatcher treats empty string as "skip even if header is set". With the snippet above this works
+  naturally because `(toolResponse?.hook || header)` short-circuits on any truthy `hook`; to force
+  skip, have the handler strip the header from `ctx` or short-circuit `hookUrl` explicitly.
+
+If neither applies, do not set `hook` — let the client decide.
+
+#### Security
+
+- **URL validation** — reject anything that does not match `http(s)://…`. For public-facing MCPs,
+  restrict to a configured allow-list (`webhook.allowedHosts` in `config/default.yaml`).
+- **SSRF surface** — the webhook is a server-side `POST` to a client-supplied URL. Acceptable for
+  trusted MCP clients; not acceptable open on the internet without an allow-list.
+- **No secrets in the body** — `response` is the same JSON the client already received. Do **not**
+  add credentials, raw tokens, or PII not present in the response.
+- **No retries** — duplicate POSTs to a flaky collector are worse than a missed event. If the
+  collector needs guarantees, let it poll.
+- **Logging** — log `tool`, target host, and outcome at `warn`/`debug`; **never** log the full body
+  at `info` level (audit log noise + potential PII).
+
+#### Testing checklist
+
+- [ ] Header declared in `usedHttpHeaders` and visible at `/use://http-headers`.
+- [ ] Tool call **without** `x-web-hook` → no outbound POST.
+- [ ] Tool call **with** valid `x-web-hook` → exactly one POST, body matches the contract above.
+- [ ] Collector returns 500 → tool response still succeeds; one `warn` line in the log.
+- [ ] Collector hangs → tool response returns within normal latency; POST aborts at 10 s.
+- [ ] Malformed URL (`javascript:…`, missing scheme) → no POST, no error to client.
+- [ ] Per-tool `hook` set → wins over the header.
+- [ ] Sync user resolution hits → `user` populated immediately, no extra HTTP call.
+- [ ] Sync empty, async succeeds → POST fires after `/me` resolves; tool response was not delayed.
+- [ ] Both user paths fail → POST fires with `user` **field omitted** (not `null`, not `"unknown"`).
 
 
 ## REST API Endpoints

package/cli-template/FA-MCP-SDK-DOC/03-configuration.md

@@ -183,6 +183,158 @@ webServer:
 
 ```
 
+## Access Points
+
+If your MCP server talks to third-party / external services (REST APIs, legacy systems, partner endpoints, etc.),
+declare their connection attributes (`host`, `port`, `protocol`, `token`, credentials, custom fields) under the
+top-level `accessPoints` block in the config — **not** scattered through code or ad-hoc config sections. Benefits:
+
+- Single registry of outbound dependencies visible in diagnostics and admin pages.
+- Automatic `host`/`port` resolution via Consul for services registered there.
+- Uniform access pattern (`appConfig.accessPoints.<alias>`) across all tools and modules.
+- Runtime updates — the SDK periodically refreshes dynamic access points from Consul without restarting the server.
+
+The SDK automatically wraps `appConfig.accessPoints` in an `AccessPoints` instance on startup and starts the Consul
+updater — **do not call `new AccessPoints(...)` or `accessPointUpdater.start()` manually**.
+
+### Declaring Access Points
+
+```yaml
+accessPoints:
+  # Dynamic AP — host/port resolved from Consul
+  wso2siAPI:
+    title: 'WSO2 SI API'
+    consulServiceName: 'dev01-wso2si-d2'
+    host: null               # filled in from Consul
+    port: 9443               # fallback; also used when Consul meta specifies a different port
+    protocol: 'https'
+    user: 'admin'
+    pass: '***'
+    myProp: 'anyValue'       # any custom field is preserved and available at runtime
+
+  # Static AP — Consul is NOT used
+  externalAPI:
+    noConsul: true
+    host: 'api.partner.com'
+    port: 443
+    protocol: 'https'
+    token: '***'
+    timeoutMs: 5000
+```
+
+### Using Access Points in Code
+
+```typescript
+import { appConfig } from 'fa-mcp-sdk';
+
+// Direct access — always works, for dynamic and static APs alike
+const ap = appConfig.accessPoints.wso2siAPI;
+const url = `${ap.protocol}://${ap.host}:${ap.port}`;
+const token = ap.token;              // custom fields available
+const custom = ap.myProp;
+
+// "Clean" copy without service fields
+const ap2 = appConfig.accessPoints.getAP('wso2siAPI');
+
+// All access points at once
+const all = appConfig.accessPoints.get();
+
+// For dynamic APs — wait until host/port are resolved from Consul (first run)
+await ap.waitForHostPortUpdated(5000);
+```
+
+**Strict typing for custom fields:**
+
+```typescript
+import type { IAccessPoint } from 'fa-consul';
+
+interface IWso2AP extends IAccessPoint {
+  user: string;
+  pass: string;
+  myProp: string;
+}
+
+const ap = appConfig.accessPoints.wso2siAPI as IWso2AP;
+```
+
+### Access Point Properties
+
+**User-defined (configured in YAML):**
+
+| Property                         | Required        | Purpose                                                                               |
+|----------------------------------|-----------------|---------------------------------------------------------------------------------------|
+| `consulServiceName`              | yes for dynamic | Consul service name used to resolve `host`/`port`                                     |
+| `host`                           | —               | IP/hostname. Dynamic: usually `null`, filled from Consul. Static (`noConsul`): manual |
+| `port`                           | —               | TCP port. Coerced to `Number` or `null`. Dynamic: from Consul (or `meta.port`)        |
+| `protocol`                       | —               | `http` or `https`. Anything other than `https?` is coerced to `http`, lowercased      |
+| `title`                          | —               | Human-readable name (defaults to the AP key)                                          |
+| `noConsul`                       | —               | `true` → static AP: Consul is not polled, `consulServiceName` is not required         |
+| `retrieveProps`                  | —               | `(host, meta) => ({host, port})`. Custom extractor for Consul response                |
+| `updateIntervalIfSuccessMillis`  | —               | Interval between successful Consul polls for this AP (default 2 min)                  |
+| `user`, `pass`, `token`, any key | —               | Application fields — stored as-is and available at runtime                            |
+
+**Service fields (added automatically by the SDK for dynamic APs):**
+
+| Property                     | Purpose                                                                 |
+|------------------------------|-------------------------------------------------------------------------|
+| `id`                         | The AP key from the config                                              |
+| `isAP`                       | Marker for a dynamic AP; absent on `noConsul` APs                       |
+| `meta`                       | Filled from `Service.Meta` of the Consul service on successful poll     |
+| `isReachable`                | `true` if the last Consul poll returned data                            |
+| `lastSuccessUpdate`          | Timestamp of the last successful update                                 |
+| `idHostPortUpdated`          | `true` once `host` + `port` have been populated at least once           |
+| `setProps(data)`             | Method for externally updating AP fields                                |
+| `waitForHostPortUpdated(ms)` | Promise that resolves when `host`/`port` have been populated            |
+| `getChanges()`               | Returns `[propName, oldValue, newValue][]` for the last `setProps` call |
+
+### `noConsul` Access Points
+
+Setting `noConsul: true` makes the access point **static** — its address is not resolved through Consul. Typical use
+cases: partner APIs, legacy systems, or services with fixed addresses that cannot (or should not) be registered in
+Consul.
+
+Differences from a dynamic AP:
+
+- `consulServiceName` is not required.
+- The AP object is stored **as-is** — no normalization of `port`/`protocol`, no service fields (`isAP`, `setProps`,
+  `waitForHostPortUpdated`, etc.) are added.
+- The AP is excluded from Consul polling; `host`/`port` are never overwritten.
+- `getAP('key')` and `get()` do **not** return static APs by default (they filter on `isAP`). Pass `andNotIsAP = true`
+  to include them, or use direct access — `appConfig.accessPoints.externalAPI` — which always works.
+
+```typescript
+appConfig.accessPoints.getAP('externalAPI', true);  // include static AP in lookup
+appConfig.accessPoints.externalAPI;                 // direct access always works
+```
+
+### Custom Fields
+
+Any additional property on an AP (`apiKey`, `timeoutMs`, `headers: {...}`, etc.) is preserved verbatim and accessible at
+runtime:
+
+- On creation, all fields from the config are copied onto the AP object.
+- Periodic Consul updates only refresh `host`/`port` (and optionally `meta`) — other properties are **never
+  overwritten**.
+- `get()` / `getAP()` copy all enumerable properties except `undefined` and functions.
+- Nested objects are copied shallowly — if a custom field is an object, its inner references are shared with the
+  original config.
+- Only `port` (coerced to `Number`) and `protocol` (coerced to `http`/`https`) are normalized; all other fields are
+  left untouched.
+
+### Subscribing to Updates
+
+When a dynamic AP is refreshed from Consul, events are emitted on the SDK's `eventEmitter`
+(see "Event System" in `06-utilities.md`):
+
+```typescript
+import { eventEmitter } from 'fa-mcp-sdk';
+
+eventEmitter.on('access-point-updated', ({ accessPoint, changes }) => {
+  // changes: [propName, oldValue, newValue][]
+});
+eventEmitter.on('access-points-updated', () => { /* any AP was updated this cycle */ });
+```
+
 ## Cache
 
 ```typescript

package/cli-template/FA-MCP-SDK-DOC/06-utilities.md

@@ -143,7 +143,9 @@ import { getConsulAPI, accessPointUpdater, deregisterServiceFromConsul } from 'f
 const consul = await getConsulAPI();
 const services = await consul.catalog.service.list();
 
-accessPointUpdater.start();  // Auto-update access points
+// accessPointUpdater is started/stopped by the SDK automatically — see 03-configuration.md → "Access Points".
+// The start()/stop() hooks below are exposed only for tests and diagnostics.
+accessPointUpdater.start();
 accessPointUpdater.stop();
 
 await deregisterServiceFromConsul();

package/cli-template/package.json

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

package/package.json

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

package/scripts/update-doc.js

@@ -1,18 +1,36 @@
 #!/usr/bin/env node
-import { cpSync, existsSync, rmSync } from 'fs';
-import { join } from 'path';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
 
-const src = join(process.cwd(), './node_modules/fa-mcp-sdk/cli-template/FA-MCP-SDK-DOC');
-const dest = join(process.cwd(), 'FA-MCP-SDK-DOC');
+const templateDir = join(process.cwd(), './node_modules/fa-mcp-sdk/cli-template');
+const cwd = process.cwd();
 
-if (!existsSync(src)) {
-  console.error('Source not found:', src);
-  process.exit(1);
-}
+const targets = [
+  { name: 'FA-MCP-SDK-DOC', src: join(templateDir, 'FA-MCP-SDK-DOC'), dest: join(cwd, 'FA-MCP-SDK-DOC') },
+  { name: '.claude', src: join(templateDir, '.claude'), dest: join(cwd, '.claude'), preserve: ['settings.json'] },
+];
 
-if (existsSync(dest)) {
-  rmSync(dest, { recursive: true });
+for (const { name, src, dest, preserve = [] } of targets) {
+  if (!existsSync(src)) {
+    console.error('Source not found:', src);
+    process.exit(1);
+  }
+  const saved = {};
+  for (const file of preserve) {
+    const p = join(dest, file);
+    if (existsSync(p)) saved[file] = readFileSync(p);
+  }
+  if (existsSync(dest)) {
+    rmSync(dest, { recursive: true });
+  }
+  cpSync(src, dest, {
+    recursive: true,
+    filter: (srcPath) => !preserve.includes(basename(srcPath)),
+  });
+  for (const [file, content] of Object.entries(saved)) {
+    const p = join(dest, file);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, content);
+  }
+  console.log(`${name} updated`);
 }
-
-cpSync(src, dest, { recursive: true });
-console.log('FA-MCP-SDK-DOC updated');