fa-mcp-sdk 0.11.8 → 0.11.10

package/cli-template/.env.example

@@ -22,12 +22,17 @@ DEBUG=config-info
 # 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:*
+# 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
 # ========================================================================

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/06-utilities.md

@@ -336,6 +336,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/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.10"
   },
   "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.10",
   "description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",