fa-mcp-sdk 0.11.8 → 0.11.12

package/cli-template/.env.example

@@ -1,43 +1,48 @@
-# SERVICE_NAME - service name. If this variable is not specified, it is taken from package.json.name
-SERVICE_NAME={{project.name}}
-# PRODUCT_NAME - If this variable is not specified, it is taken from package.json.productName
-# PRODUCT_NAME=
-
-NODE_ENV={{NODE_ENV}}
-# Used for PM2
-SERVICE_INSTANCE={{SERVICE_INSTANCE}}
-PM2_NAMESPACE={{PM2_NAMESPACE}}
-
-# Affects how the Consul service ID is formed - as a product or development ID
-NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
-
-DEBUG=config-info
-# Used for PM2 service configuration
-#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
-#│ id │ name                                                      │ namespace       │
-#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
-#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
-
-## DEBUG patterns ##
-# AP-UPDATER - consul/access-points-updater
-# fa-consul:reg | fa-consul:* - consul/cyclic-register
-# fa-consul:curl - consul/prepare-consul-api
-# token:auth
-# mcp:tool
-# mcp:resource
-# mcp:notification
-# mcp:prompt
-# mcp:*
-# ========================================================================
-# AGENT TESTER - Built-in AI agent for testing MCP tools
-# ========================================================================
-# AGENT_TESTER_ENABLED=true
-# AGENT_TESTER_USE_AUTH=false
-# AGENT_TESTER_OPENAI_API_KEY=sk-...
-# AGENT_TESTER_OPENAI_BASE_URL=
-
-# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
-# TEST_MCP_SERVER_URL=
-
-# The directory to store test result logs
-TEST_RESULT_LOGS_DIR='_logs/mcp'
+# SERVICE_NAME - service name. If this variable is not specified, it is taken from package.json.name
+SERVICE_NAME={{project.name}}
+# PRODUCT_NAME - If this variable is not specified, it is taken from package.json.productName
+# PRODUCT_NAME=
+
+NODE_ENV={{NODE_ENV}}
+# Used for PM2
+SERVICE_INSTANCE={{SERVICE_INSTANCE}}
+PM2_NAMESPACE={{PM2_NAMESPACE}}
+
+# Affects how the Consul service ID is formed - as a product or development ID
+NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
+
+DEBUG=config-info
+# Used for PM2 service configuration
+#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
+#│ id │ name                                                      │ namespace       │
+#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
+#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
+
+## DEBUG patterns ##
+# AP-UPDATER - consul/access-points-updater
+# fa-consul:reg | fa-consul:* - consul/cyclic-register
+# fa-consul:curl - consul/prepare-consul-api
+# token:auth         - authentication: which auth method matched, token parsing/validation outcome
+# mcp:tool           - tools/call: tool name + arguments in, response (text or JSON) out
+# mcp:resource       - resources/list and resources/read: URI in, body out
+# mcp:notification   - all incoming notifications/* (method + params)
+# mcp:prompt         - prompts/list and prompts/get: name/args in, messages out
+# mcp:*              - all four MCP channels above at once
+# mcp-handshake      - HTTP transport: per-request dump (method, id, session routing, protocol, auth, IP)
+# mcp-rpc            - HTTP transport: one-line summary of every successful JSON-RPC response
+#
+#(session-lifecycle events, the -32600 "no valid session" rejection and JSON-RPC errors log always)
+#
+# ========================================================================
+# AGENT TESTER - Built-in AI agent for testing MCP tools
+# ========================================================================
+# AGENT_TESTER_ENABLED=true
+# AGENT_TESTER_USE_AUTH=false
+# AGENT_TESTER_OPENAI_API_KEY=sk-...
+# AGENT_TESTER_OPENAI_BASE_URL=
+
+# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
+# TEST_MCP_SERVER_URL=
+
+# The directory to store test result logs
+TEST_RESULT_LOGS_DIR='_logs/mcp'

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

@@ -18,7 +18,7 @@ npm install fa-mcp-sdk
 | [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points, cache, **`mcp.limits` (payload/result/timeout)**, **`mcp.pagination`**, **`mcp.resources` (MAY)**, **`mcp.rateLimit.scope` + `maxConcurrentPerSubject` (§14)**, **`webServer.trustProxy`**, **`webServer.tokenCheck.allowQueryToken` (§7.1)**, **/health & /ready**, **CORS hardening**, **MCP error codes** (`-32002…-32005`) | Server configuration, external services, transport-level hardening |
 | [04-authentication](04-authentication.md) | JWT (**4 modes: legacyAesCtr / embedded / localKey / remoteJwks**), Basic auth, server tokens, **OAuth discovery + `/oauth/token` + JWKS**, **`requiredScopes` enforcement (§7.5)**, **`WWW-Authenticate` realm + invalid_token (§7.4)**, **HTTP 403 `forbidden` flag**, `createAuthMW()`, Token Generator, CLI Token Generator (mode-aware), 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, MCP debug switches (`DEBUG=mcp:*`), JSON-lines sink (`mcp.debug.logFile` → `emitTrace`), built-in debug tools (`mcp.debug.builtinTools`), Consul, graceful shutdown | Error handling, utilities, request tracing, post-mortem analysis |
+| [06-utilities](06-utilities.md) | `ServerError`, `normalizeHeaders`, logging, MCP debug switches (`DEBUG=mcp:*`), **HTTP connection & RPC tracing (`DEBUG=mcp-handshake` / `mcp-rpc`, always-on session-lifecycle + `-32600` + error logging)**, JSON-lines sink (`mcp.debug.logFile` → `emitTrace`), built-in debug tools (`mcp.debug.builtinTools`), Consul, graceful shutdown | Error handling, utilities, request tracing, post-mortem analysis |
 | [07-testing-and-operations](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE, Streamable HTTP); universal `debug-tool` fixture covering every `CallToolResult` shape | Testing, deployment, exercising client code against image/audio/resource/error/delay variants |
 | [08-agent-tester-and-headless-api](08-agent-tester-and-headless-api.md) | Agent Tester, Headless API, structured logging, automated testing, UI `data-testid` reference. **MCP Apps mode**: capability negotiation, `appCalls[]` / `app_calls[]`, widget iframe bridge, App Inspector tab | Agent-driven tool development, CLI automation, UI E2E tests, MCP Apps host for development |
 | [09-database](09-database.md) | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, `getInsertSqlMAIN`, `getMergeSqlMAIN`, `mergeByBatch`), `pgvector`, secondary DBs | Database access, upserts, batching |

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

@@ -172,6 +172,92 @@ asJsonError({ code: 'NOT_FOUND', key: 'X' });  // { structuredContent: {...},
 > for missing resources, convert those branches to `return formatToolError('Not found: ...')`. The
 > LLM will start surfacing "Such an issue does not exist" to the user instead of failing the call.
 
+### Normalizing upstream API errors
+
+The `isError` vs `throw` decision above is easy when the handler discovers the problem itself (a `null`
+issue). It is harder when the failure surfaces as a raw error thrown deep inside an HTTP client — a 404
+from the upstream API arrives as an Axios/`fetch` rejection, not as a clean `formatToolError`. Catching
+that in every handler is repetitive and easy to get wrong. The pattern below centralizes it in the single
+`catch` of `handleToolCall`, and implements standard
+[§13.4 "Mapping upstream errors"](./12-implementation-standard.md#134-mapping-upstream-downstream-api-errors).
+
+It has three pure steps — translate, classify, surface:
+
+```typescript
+import {
+  formatToolError, ToolExecutionError, ServerError, RateLimitedError,
+  UpstreamUnavailableError, ValidationError, ConflictError, ResourceNotFoundError, toStr,
+} from 'fa-mcp-sdk';
+
+// 1. TRANSLATE — convert a raw upstream HTTP error into a typed error class (no throw here).
+//    Map the upstream status onto the Appendix B error set instead of one opaque ServerError.
+function handleAxiosError(error: any, toolName: string): never {
+  const status = error?.response?.status;
+  const msg = extractUpstreamMessage(error?.response?.data) ?? error?.message ?? 'Unknown error';
+  const data = { toolName, status };                       // safe: no body, no headers, no stack
+
+  if (!status || status >= 502) throw new UpstreamUnavailableError(`Upstream unavailable: ${msg}`, data);
+  if (status === 400)           throw new ValidationError(`Invalid request: ${msg}`);
+  if (status === 404)           throw new ResourceNotFoundError(msg, data);
+  if (status === 409)           throw new ConflictError(`State conflict: ${msg}`, data);
+  if (status === 429) {
+    const retryAfter = parseInt(error?.response?.headers?.['retry-after'], 10) || 60;
+    throw new RateLimitedError(`Rate limited: ${msg}`, retryAfter);
+  }
+  // 401/403 and other 5xx — keep the upstream status in `data.status` so step 2 can recognize it.
+  throw new ServerError(`Upstream error (HTTP ${status}): ${msg}`, data);
+}
+
+// 2. NORMALIZE — turn ANY thrown value into a concrete Error, still WITHOUT throwing.
+//    A pure function lets the MCP path (may surface to the LLM) and a REST path (always throws)
+//    share one step.
+export function normalizeToolError(error: any, toolName: string): Error {
+  if (error instanceof ToolExecutionError || error instanceof ServerError ||
+      typeof error?.jsonRpcCode === 'number') {
+    return error;                                          // already a domain error
+  }
+  if (isAxiosError(error)) {
+    try { handleAxiosError(error, toolName); } catch (converted) { return converted as Error; }
+  }
+  return new ServerError(toStr(error), { toolName }, true); // catch-all, sanitized (no upstream status)
+}
+
+// 3. CLASSIFY — decide whether the model should SEE the message (isError) or get a thrown protocol error.
+export function isLlmVisibleError(error: any): boolean {
+  if (error instanceof RateLimitedError) return false;     // retry contract — keep -32003 thrown
+  if (error instanceof ToolExecutionError) return true;    // JQL/validation written for the model
+  if (typeof error?.jsonRpcCode === 'number') return true; // ValidationError/NotFound/Conflict/Upstream
+  if (error instanceof ServerError && error?.details?.status != null) return true; // upstream 401/403/5xx
+  return false;                                            // catch-all ServerError → "Internal error"
+}
+```
+
+Wire all three into the single `catch`, so every handler benefits without its own try/catch:
+
+```typescript
+} catch (error: any) {
+  const normalized = normalizeToolError(error, toolName);
+  if (isLlmVisibleError(normalized)) {
+    // The model reads the upstream reason ("Issue AITECH-123 does not exist") and self-corrects.
+    return formatToolError(normalized.message);
+  }
+  throw normalized;                                        // RateLimitedError / internal → protocol error
+}
+```
+
+Why this split matters:
+
+- A **404 raised by the upstream API** becomes `ResourceNotFoundError` (numeric `jsonRpcCode`), so
+  `isLlmVisibleError` returns `true` and the model gets `result.isError=true` — exactly like the manual
+  `formatToolError` branch in the previous section, but for an error it never saw directly.
+- **`RateLimitedError` stays thrown** as `-32003` with `retryAfter` — clients depend on that contract, so
+  it must not collapse into an `isError` text result.
+- A **catch-all `ServerError`** (no `details.status`) stays thrown and is sanitized by the SDK to
+  `Internal error` — its text may carry internal detail and MUST NOT reach the model (standard §13.3).
+
+> Keep `normalizeToolError` **pure** (never throws). A throwing normalizer forces every call site into its
+> own try/catch and defeats the point of centralizing the logic.
+
 ### Headers Access
 
 Headers are normalized to lowercase. Available in HTTP/SSE transports:

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

@@ -37,6 +37,26 @@ class MyError extends BaseMcpError {
 | `RateLimitedError` | `RATE_LIMITED` | `-32003` | 429 | Appendix B |
 | `TimeoutError` | `TIMEOUT` | `-32004` | 504 | Appendix B |
 | `PayloadTooLargeError` | `PAYLOAD_TOO_LARGE` | `-32005` | 413 | Appendix B |
+| `UpstreamUnavailableError` | `UPSTREAM_UNAVAILABLE` | `-32006` | 503 | Appendix B |
+| `ConflictError` | `CONFLICT` | `-32007` | 409 | Appendix B |
+
+### Mapping a Downstream API Status to a Typed Error
+
+When a tool proxies a downstream HTTP API, translate the upstream status into one of these classes instead
+of a single opaque `ServerError`. This gives the JSON-RPC layer a meaningful code and lets the surfacing
+logic (next) decide whether the model should see the message. This is standard §13.4; the end-to-end
+`normalizeToolError` / `isLlmVisibleError` / `formatToolError` pattern is in
+[02-1-tools-and-api.md → "Normalizing upstream API errors"](./02-1-tools-and-api.md).
+
+| Upstream HTTP                 | Throw                       | Surfaced to model as `isError`? |
+|-------------------------------|-----------------------------|---------------------------------|
+| 400                           | `ValidationError`           | yes                             |
+| 401 / 403                     | `ServerError` (status in data) | yes                          |
+| 404                           | `ResourceNotFoundError`     | yes                             |
+| 409                           | `ConflictError`             | yes                             |
+| 429                           | `RateLimitedError`          | no — thrown, keeps `retryAfter` |
+| 502 / 503 / 504 / no response | `UpstreamUnavailableError`  | yes                             |
+| other 5xx / unexpected        | `ServerError` (no status)   | no — thrown, sanitized          |
 
 ## Error Utilities
 
@@ -336,6 +356,48 @@ echo "DEBUG=mcp:tool,mcp:resource" >> .env
 > `stdout` via `console.log`, so enabling `DEBUG=mcp:*` in STDIO mode **will corrupt the framing**
 > the client sees. Use these switches with HTTP/SSE transport, or redirect stdout.
 
+## HTTP Connection & RPC Tracing (`DEBUG=mcp-handshake`, `DEBUG=mcp-rpc`)
+
+Separate from the `mcp:*` channel switches above, the **Streamable HTTP transport** carries its own
+connection- and response-level tracing in `web/server-http.ts`. These switches use hyphenated names
+(`mcp-handshake`, `mcp-rpc`) and are read straight from the comma-split `DEBUG` env var — they do
+**not** go through the `af-tools-ts` `Debug()` machinery, so they are not covered by `mcp:*` or `*`.
+List them explicitly, e.g. `DEBUG=mcp-handshake,mcp-rpc`. They exist to answer the two questions the
+`mcp:*` taps cannot: *why did the client get a session/protocol error?* and *what did the server
+actually send back?*
+
+| Env value             | What it logs                                                                          |
+|-----------------------|---------------------------------------------------------------------------------------|
+| *(always on)*         | Session created / closed / transport-closed (with active-session count); the `-32600` "no valid session" rejection with the reason. |
+| `DEBUG=mcp-handshake` | Per-request dump for every `/mcp` call: JSON-RPC method + id, short session id, routing hit/miss, protocol version, `Accept` / `Content-Type`, whether an auth header is present, and client IP. |
+| `DEBUG=mcp-rpc`       | One-line summary of every **successful** JSON-RPC response (status, ids, `result=ok` / notifications). |
+
+Two things always log regardless of the switches, because they are otherwise silent failure modes:
+
+- **The `-32600` rejection.** When a request reaches `/mcp` without a valid session and is not an
+  `initialize`, the server now logs *why* — the client must send `initialize` first or echo a valid
+  `mcp-session-id` header — and notes when the supplied session id is unknown or expired (with the
+  count of known sessions). This is the trace to look for when the client reports `-32600` but the
+  server log was previously empty.
+- **Every JSON-RPC error response.** A response tee on `POST /mcp` and the `GET`/`DELETE` session
+  routes captures the outgoing body, parses it (auto-detecting a plain `application/json` answer vs.
+  the `data:` frames of an SSE stream), and logs each error's HTTP status, request id, `code`,
+  `message`, and truncated `data`, together with the originating request summary. The capture is
+  capped at 256 KB per response so a long SSE stream cannot exhaust memory (`[capture truncated]`
+  marks a hit), and the trace is wrapped so it can never break the real response.
+
+```bash
+# Why is the client getting "no valid session" / -32600? (handshake dump on every request)
+DEBUG=mcp-handshake yarn start
+
+# Also summarise successful responses (otherwise only errors are logged)
+DEBUG=mcp-handshake,mcp-rpc yarn start
+```
+
+> These switches are HTTP-transport only — STDIO never opens sessions, so they have no effect there.
+> They are safe to leave off in production; the always-on session-lifecycle and error lines are the
+> ones worth keeping in normal operation.
+
 ### Extending with Custom Debug Categories
 
 Add your own switches with the same `Debug()` helper from `af-tools-ts`:

package/cli-template/FA-MCP-SDK-DOC/12-implementation-standard.md

@@ -2,9 +2,9 @@
 
 | Parameter                  | Value                              |
 |----------------------------|------------------------------------|
-| Version                    | 1.2                                |
+| Version                    | 1.3                                |
 | Status                     | Active                             |
-| Date                       | 2026-06-03                         |
+| Date                       | 2026-06-05                         |
 | Scope                      | All internal company MCP servers   |
 | Base MCP                   | MCP 2025-11-25                      |
 | Starter SDK (optional)     | `fa-mcp-sdk`                       |
@@ -13,7 +13,8 @@
 > This document is the English translation of the corporate implementation standard. It restates the
 > explicit MCP 2025-11-25 requirements plus the corporate Avatar / AI Platform profile in a single
 > self-contained document. Version 1.2 adds the side-effect tools and risk-level rules and fixes the
-> `-32007` error-code inconsistency.
+> `-32007` error-code inconsistency. Version 1.3 adds §13.4 on mapping upstream (downstream API) errors
+> to typed error classes and the rule for surfacing model-correctable errors via `result.isError=true`.
 
 ## Table of Contents
 
@@ -765,6 +766,50 @@ An error returned externally MUST NOT contain:
 - raw SQL/expression text with user data;
 - internal service names that are not part of the public contract.
 
+### 13.4. Mapping upstream (downstream API) errors
+
+This section is a corporate recommendation for servers that proxy a downstream HTTP API (Jira, GitLab, an
+internal microservice, etc.). It defines how a failed upstream call is translated into the two error types
+of §13.1 so that the model receives an actionable reason instead of one opaque `-32603 Internal error`.
+
+When a tool calls a downstream API, the server SHOULD translate the upstream HTTP status into the matching
+typed error class from [Appendix B](#appendix-b-error-codes) rather than collapsing every failure into a
+generic internal error. The recommended mapping is:
+
+| Upstream HTTP                     | Typed error class      | JSON-RPC | Returned to the model |
+| --------------------------------- | ---------------------- | -------- | --------------------- |
+| 400                               | `ValidationError`      | -32602   | `isError=true`        |
+| 401 / 403                         | `ServerError` (with upstream status in `data`) | -32000 | `isError=true` |
+| 404                               | `ResourceNotFoundError`| -32002   | `isError=true`        |
+| 409                               | `ConflictError`        | -32007   | `isError=true`        |
+| 429                               | `RateLimitedError`     | -32003   | thrown (see below)    |
+| 502 / 503 / 504 / no response     | `UpstreamUnavailableError` | -32006 | `isError=true`      |
+| other 5xx                         | `ServerError`          | -32000   | thrown                |
+
+The decision whether to surface an error to the model or to throw it follows three rules:
+
+- An error whose message is **safe to expose and actionable** — built from the structured upstream error
+  body, not from internal state — SHOULD be returned as a tool execution result with `result.isError=true`
+  (§9.4, §13.1). The model reads the upstream reason (for example `Issue AITECH-123 does not exist`) and
+  self-corrects instead of treating the call as a hard sandbox failure. A `404` raised by the downstream
+  API is the canonical case: it MUST reach the model as `result.isError=true`, not as a thrown protocol
+  error.
+- `-32003 Rate limited` MUST remain a **thrown** protocol error and MUST carry the `Retry-After` header /
+  `retryAfter` value (§14, Appendix B.3). It MUST NOT be flattened into an `isError` text result, because
+  clients rely on the numeric code and the retry hint to schedule a retry.
+- An internal failure with **no upstream status** (the catch-all wrapper around an unexpected exception)
+  MUST stay a thrown protocol error and MUST be sanitized per §13.3 — typically `-32603 Internal error`
+  with no stack trace and no secrets.
+
+A reference implementation of this pattern — a pure `normalizeToolError()` that converts any thrown value
+into a typed error without throwing, an `isLlmVisibleError()` predicate that applies the three rules above,
+and the `formatToolError()` call that surfaces the message — is documented in
+[02-1-tools-and-api.md → "Normalizing upstream API errors"](./02-1-tools-and-api.md).
+
+Whatever message is exposed (via `isError=true` or a thrown error) MUST still satisfy the §13.3
+prohibitions: the upstream error body is forwarded only after it has been reduced to its human-readable
+text, never as a raw payload that could carry internal paths, tokens, or stack traces.
+
 ## 14. Limits and protection
 
 Each server MUST document and enforce:

package/cli-template/package.json

@@ -58,7 +58,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.11.8"
+    "fa-mcp-sdk": "^0.11.12"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/package.json

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