fa-mcp-sdk 0.4.67 → 0.4.68

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/package.json

@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.4.67"
+    "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.67",
+  "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,23 +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 templateDir = join(process.cwd(), './node_modules/fa-mcp-sdk/cli-template');
 const cwd = process.cwd();
 
 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') },
+  { name: '.claude', src: join(templateDir, '.claude'), dest: join(cwd, '.claude'), preserve: ['settings.json'] },
 ];
 
-for (const { name, src, dest } of targets) {
+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 });
+  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`);
 }