fa-mcp-sdk 0.4.124 → 0.4.134

package/cli-template/AGENTS.md

@@ -128,7 +128,7 @@ Detailed fa-mcp-sdk docs are in `FA-MCP-SDK-DOC/`:
 | `05-ad-authorization.md` | AD group authorization, AD config |
 | `06-utilities.md` | Error handling, logging, Consul |
 | `07-testing-and-operations.md` | Test clients (STDIO, HTTP, SSE, Streamable HTTP) |
-| `08-agent-tester-and-headless-api.md` | Agent Tester, Headless API, structured logging, automated testing |
+| `08-agent-tester-and-headless-api.md` | Agent Tester, Headless API, structured logging, automated testing, MCP Apps mode (capability negotiation, `appCalls[]`, widget rendering, App Inspector) |
 | `09-database.md` | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, upserts, `mergeByBatch`), `pgvector`, secondary DBs |
 | `10-mcp-apps.md` | Building / extending MCP Apps (UI-augmented tools) — protocol contract, SDK surface, patterns, pitfalls |
 

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

@@ -18,11 +18,11 @@ npm install fa-mcp-sdk
 | [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points for external services, cache | Server configuration, external services |
 | [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, MCP debug switches (`DEBUG=mcp:*`), Consul, graceful shutdown | Error handling, utilities, request tracing |
-| [07-testing-and-operations](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE, Streamable HTTP) | Testing, deployment |
-| [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 | Agent-driven tool development, CLI automation, UI E2E tests |
+| [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 |
+| [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 |
-| [10-mcp-apps](10-mcp-apps.md) | Self-contained digest of the MCP Apps protocol + SDK pinned to `@modelcontextprotocol/ext-apps v1.7.2` (spec 2026-01-26): `ui://` resources, `_meta.ui`, JSON-RPC messages, `App` class, host context, patterns, pitfalls | Building / extending MCP Apps (UI-augmented tools) |
+| [10-mcp-apps](10-mcp-apps.md) | Self-contained digest of the MCP Apps protocol + SDK pinned to `@modelcontextprotocol/ext-apps v1.7.2` (spec 2026-01-26): `ui://` resources, `_meta.ui`, JSON-RPC messages, `App` class, host context, patterns, pitfalls. **Canonical example** (`examples/mcp-apps-canonical/`, `npm run example:mcp-apps`) and widget-side debug helpers (`mcp-debug-log`, `mcp-debug-refresh`). Cross-links to Agent Tester as a dev-host (doc 08) | Building / extending MCP Apps (UI-augmented tools) |
 
 ## Key Exports
 
@@ -35,7 +35,9 @@ import { createAuthMW, generateToken, getAuthHeadersForTests, TTokenType, genera
 
 // Tools & Errors
 import {
-  formatToolResult, asTextContent, asJson, getJsonFromResult,
+  formatToolResult, formatToolError,                  // formatToolError → sets isError: true
+  asTextContent, asTextError, asJson, asJsonError,    // direct-shape helpers (text + structured, ok + error)
+  getJsonFromResult,
   TToolHandlerResponse, IToolHandlerTextResponse, IToolHandlerStructuredResponse,
   ToolExecutionError, ServerError, BaseMcpError, ValidationError, getTools,
 } from 'fa-mcp-sdk';
@@ -55,6 +57,18 @@ import { logger, fileLogger, Logger, applyLoggerSettings, trim, ppj, toError, to
 // MCP debug switches (DEBUG=mcp:tool|mcp:resource|mcp:prompt|mcp:notification or DEBUG=mcp:*)
 import { debugMcpTool, debugMcpResource, debugMcpPrompt, debugMcpNotification, debugTokenAuth } from 'fa-mcp-sdk';
 
+// JSON-lines debug sink (mcp.debug.logFile) — see 06-utilities → "JSON-lines Sink"
+import { emitTrace, configureDebugSink, initDebugTraceFromConfig } from 'fa-mcp-sdk';
+
+// Built-in debug tools (enabled by mcp.debug.builtinTools=true)
+// — see 06-utilities → "Built-in Debug Tools", 07-testing → "Universal debug-tool", 10-mcp-apps § 8.14
+import {
+  BUILTIN_MCP_DEBUG_TOOLS, BUILTIN_MCP_DEBUG_TOOL_NAMES,
+  MCP_DEBUG_LOG_TOOL_NAME, MCP_DEBUG_REFRESH_TOOL_NAME,
+  isBuiltinDebugTool, handleBuiltinDebugTool,
+  DEBUG_TOOL, DEBUG_TOOL_NAME, handleDebugTool, registerDebugTool,
+} from 'fa-mcp-sdk';
+
 // Test Clients
 import { McpHttpClient, McpStdioClient, McpSseClient, McpStreamableHttpClient } from 'fa-mcp-sdk';
 

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

@@ -56,6 +56,69 @@ The handler must return `TToolHandlerResponse` — a discriminated union of
 the value as-is to the MCP client over STDIO, SSE, and HTTP. Use `formatToolResult()`
 to pick the right shape based on `appConfig.mcp.tools.answerAs`.
 
+### Returning errors — `isError: true` vs `throw`
+
+The MCP spec distinguishes two error classes, and the LLM behaves very differently for each:
+
+| Error class            | How to return                                            | What the LLM sees                                  |
+|------------------------|----------------------------------------------------------|----------------------------------------------------|
+| **Tool-level**         | `return formatToolError(msg)` (`isError: true` in result) | Error text inside the conversation — can self-correct, retry, ask the user |
+| **Protocol-level**     | `throw new ToolExecutionError(name, msg)`                | JSON-RPC `error` envelope — most clients surface this as a hard sandbox failure the model cannot react to |
+
+**Use `formatToolError()` for:**
+
+- resource not found (`Issue AITECH-1 not found`)
+- business validation (`Date must be in the past`)
+- upstream API returned a recoverable error (404, 422, "rate limited, retry later")
+- partial success the LLM should explain to the user
+
+**Throw for:**
+
+- unknown tool name (`switch` default branch)
+- missing required transport feature (e.g. no `Mcp-Session-Id` for stateful clients)
+- genuine infrastructure failure (DB connection dead, secret missing) that the LLM cannot work around
+
+```typescript
+import {
+  formatToolResult, formatToolError, ToolExecutionError,
+  IToolHandlerParams, TToolHandlerResponse,
+} from 'fa-mcp-sdk';
+
+export const handleToolCall = async (
+  params: IToolHandlerParams,
+): Promise<TToolHandlerResponse> => {
+  const { name, arguments: args } = params;
+
+  switch (name) {
+    case 'get_issue': {
+      const issue = await jira.findIssue(args.key);
+      if (!issue) {
+        // Tool-level: LLM sees "Issue X not found" and can ask the user to clarify.
+        return formatToolError(`Issue ${args.key} not found`);
+      }
+      return formatToolResult(issue);
+    }
+
+    default:
+      // Protocol-level: client routing problem, not something the LLM should retry.
+      throw new ToolExecutionError(name, `Unknown tool: ${name}`);
+  }
+};
+```
+
+Direct-shape helpers (ignore `tools.answerAs`):
+
+```typescript
+import { asTextError, asJsonError } from 'fa-mcp-sdk';
+
+asTextError('Not found');                      // { content: [{type:'text', text:'Not found'}], isError: true }
+asJsonError({ code: 'NOT_FOUND', key: 'X' });  // { structuredContent: {...},                  isError: true }
+```
+
+> **Migration tip.** If your current handler does `throw new ToolExecutionError(name, 'Not found: ...')`
+> 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.
+
 ### Headers Access
 
 Headers are normalized to lowercase. Available in HTTP/SSE transports:

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

@@ -77,7 +77,8 @@ const normalized = normalizeHeaders({
 
 ```typescript
 import {
-  getTools, formatToolResult, getJsonFromResult, asTextContent, asJson,
+  getTools, formatToolResult, formatToolError, getJsonFromResult,
+  asTextContent, asTextError, asJson, asJsonError,
   TToolHandlerResponse, IToolHandlerTextResponse, IToolHandlerStructuredResponse,
 } from 'fa-mcp-sdk';
 
@@ -87,27 +88,40 @@ const tools = await getTools();  // Get registered tools
 // Return type: TToolHandlerResponse<T> = IToolHandlerTextResponse | IToolHandlerStructuredResponse<T>
 const result = formatToolResult<{ message: string; data: object }>({ message: 'Done', data: {} });
 
+// Tool-level error — `isError: true` so the LLM sees it in conversation
+// and can self-correct instead of treating it as a protocol failure.
+const fail = formatToolError(`Issue ${key} not found`);
+
 // Returns structuredContent or JSON from text depending on appConfig.mcp.tools.answerAs
 const original = getJsonFromResult<T>(result);
 
 // Direct formatting helpers (ignore tools.answerAs config):
-asTextContent('Hello');           // IToolHandlerTextResponse: { content: [{ type: 'text', text: 'Hello' }] }
-asJson({ status: 'ok' });         // IToolHandlerStructuredResponse: { structuredContent: { status: 'ok' } }
+asTextContent('Hello');            // { content: [{ type: 'text', text: 'Hello' }] }
+asJson({ status: 'ok' });          // { structuredContent: { status: 'ok' } }
+asTextError('Not found');          // { content: [{ type: 'text', text: 'Not found' }], isError: true }
+asJsonError({ code: 'NOT_FOUND' }); // { structuredContent: { code: 'NOT_FOUND' },       isError: true }
 ```
 
 ### Return Type Signatures
 
 ```typescript
 function formatToolResult<T = any>(json: T): TToolHandlerResponse<T>;
+function formatToolError<T = any>(json: T): TToolHandlerResponse<T>;     // sets isError: true
 function asTextContent(text: string): IToolHandlerTextResponse;
+function asTextError(text: string): IToolHandlerTextResponse;            // sets isError: true
 function asJson<T = any>(json: T): IToolHandlerStructuredResponse<T>;
+function asJsonError<T = any>(json: T): IToolHandlerStructuredResponse<T>; // sets isError: true
 function getJsonFromResult<T = any>(result: TToolHandlerResponse | any): T;
 ```
 
 ### When to Use Which
 
-- **`formatToolResult()`** — Primary choice in tool handlers. Respects `appConfig.mcp.tools.answerAs` config.
-- **`asTextContent()` / `asJson()`** — Direct formatting, ignores `tools.answerAs`. Use when specific format needed.
+- **`formatToolResult()` / `formatToolError()`** — Primary choices in tool handlers. Respect
+  `appConfig.mcp.tools.answerAs`. Use `formatToolError()` for *tool-level* failures (not found,
+  validation, upstream 4xx) so the LLM sees them in conversation. See
+  [02-1-tools-and-api.md → "Returning errors"](./02-1-tools-and-api.md) for the full guide.
+- **`asTextContent()` / `asTextError()` / `asJson()` / `asJsonError()`** — Direct formatting,
+  ignore `tools.answerAs`. Use when a specific shape is required.
 - **`getJsonFromResult()`** — Inverse of `formatToolResult()`. Extracts JSON from either format. Use in tests.
 
 ## Network Utilities
@@ -291,6 +305,120 @@ the category is off. The four built-in `debugMcpTool`/`debugMcpResource`/`debugM
 them from your own code (e.g. emit a custom line inside `handle-tool-call.ts` whenever
 `debugMcpTool.enabled` is true).
 
+## JSON-lines Sink (`mcp.debug.logFile`)
+
+`DEBUG=mcp:*` writes ANSI-coloured human-readable text to stderr — perfect for live development,
+useless for post-mortem (colours, interleaved process output, no structured fields). Set
+`mcp.debug.logFile` to an absolute path and the SDK additionally mirrors every `mcp:tool`,
+`mcp:resource`, `mcp:prompt` event as one JSON object per line. The stderr stream is unchanged —
+the sink is purely additive.
+
+```yaml
+# config/default.yaml — or any environment override
+mcp:
+  debug:
+    logFile: /var/log/mcp/server-debug.jsonl   # absolute path; parent dir is created on first event
+    builtinTools: false                         # see next section
+```
+
+Or via env (mapped through `config/custom-environment-variables.yaml`):
+
+```bash
+MCP_DEBUG_LOG_FILE=/var/log/mcp/server.jsonl yarn start
+```
+
+### Event Shape
+
+Each line is a self-contained JSON object. `ts` (ISO timestamp) and `ch` (channel) are always
+present; remaining fields depend on the channel and `kind`.
+
+```jsonl
+{"ts":"2026-05-19T12:34:56.124Z","ch":"mcp:tool","kind":"req","name":"get_rate","args":{"from":"EUR"},"corr":"a3f1c0d2"}
+{"ts":"2026-05-19T12:34:56.171Z","ch":"mcp:tool","kind":"res","name":"get_rate","ms":47,"corr":"a3f1c0d2","ok":true}
+{"ts":"2026-05-19T12:34:57.012Z","ch":"mcp:tool","kind":"err","name":"get_rate","ms":2998,"corr":"b9c20f3a","error":"Connection timeout"}
+{"ts":"2026-05-19T12:34:57.045Z","ch":"mcp:resource","kind":"read-res","uri":"ui://weather/view.html","ms":3}
+{"ts":"2026-05-19T12:34:57.090Z","ch":"mcp:prompt","kind":"get-res","name":"agent_prompt","ms":1}
+```
+
+| Channel         | `kind` values                                                  | Useful fields                |
+|-----------------|----------------------------------------------------------------|------------------------------|
+| `mcp:tool`      | `req` / `res` / `err`                                          | `name`, `args`, `ms`, `corr` |
+| `mcp:resource`  | `list-req` / `list-res` / `read-req` / `read-res` / `read-err` | `uri`, `count`, `ms`         |
+| `mcp:prompt`    | `list-req` / `list-res` / `get-req` / `get-res` / `get-err`    | `name`, `count`, `ms`        |
+| `app:view-log`  | `log` (emitted by built-in `mcp-debug-log` tool)               | `type`, `payload`            |
+
+`corr` is an 8-char hex correlation ID — pair `req` ↔ `res`/`err` for one tool call.
+
+### Working With The File
+
+Standard JSON toolchain works as-is:
+
+```bash
+# p95 latency by tool
+jq -r 'select(.ch=="mcp:tool" and .kind=="res") | "\(.name)\t\(.ms)"' /var/log/mcp/*.jsonl \
+  | sort | datamash -g 1 perc:95 2
+
+# all errors of the last hour
+jq 'select((.kind|test("err$")) and (.ts > "2026-05-19T11:00:00"))' /var/log/mcp/*.jsonl
+
+# events pushed by widgets via mcp-debug-log
+jq 'select(.ch=="app:view-log")' /var/log/mcp/*.jsonl
+```
+
+### Programmatic Access
+
+If you need to write into the same channel from your own code (e.g. tag a domain event so it shows
+up alongside MCP traffic), use the helpers directly:
+
+```typescript
+import { emitTrace, configureDebugSink } from 'fa-mcp-sdk';
+
+// At startup the SDK already calls configureDebugSink(appConfig.mcp.debug.logFile);
+// re-configure on the fly only in tests.
+configureDebugSink('/tmp/mcp-test.jsonl');
+
+emitTrace('app:billing', { kind: 'charge', userId, amountCents });
+// → {"ts":"…","ch":"app:billing","kind":"charge","userId":"…","amountCents":1299}
+```
+
+`emitTrace` is a no-op when no sink is configured — the guard is cheap, leave the calls in.
+
+## Built-in Debug Tools (`mcp.debug.builtinTools`)
+
+A single flag registers three SDK-provided tools that exist to be called from widget code or
+integration tests, never by the LLM. All three are marked `_meta.ui.visibility: ['app']`, so MCP App
+hosts (Agent Tester, Claude Desktop with apps support, etc.) hide them from the agent's tool list.
+
+```yaml
+mcp:
+  debug:
+    builtinTools: true     # or MCP_DEBUG_BUILTIN_TOOLS=true
+```
+
+| Tool name           | Caller         | Purpose                                                                     |
+|---------------------|----------------|-----------------------------------------------------------------------------|
+| `mcp-debug-log`     | Widget         | Push a structured event into the same channel as `DEBUG=mcp:*` / JSON-lines |
+| `mcp-debug-refresh` | Widget         | Read back lightweight server state (timestamp + counter) without the LLM    |
+| `debug-tool`        | Test client    | Universal CallToolResult fixture — see [07-testing-and-operations](07-testing-and-operations.md) → "Universal `debug-tool` for Integration Tests" |
+
+The widget-facing tools are covered in [10-mcp-apps](10-mcp-apps.md) → "Widget-side debug helpers"
+(the canonical example calls them through `app.callServerTool(...)`). Names and constants are
+exported when you need to reference them in test code:
+
+```typescript
+import {
+  MCP_DEBUG_LOG_TOOL_NAME,       // 'mcp-debug-log'
+  MCP_DEBUG_REFRESH_TOOL_NAME,   // 'mcp-debug-refresh'
+  DEBUG_TOOL_NAME,               // 'debug-tool'
+  BUILTIN_MCP_DEBUG_TOOLS,       // Tool[] descriptors for the two widget tools
+  DEBUG_TOOL,                    // Tool descriptor for the test fixture
+} from 'fa-mcp-sdk';
+```
+
+> Leave `builtinTools: false` in production unless a widget genuinely needs `mcp-debug-log` /
+> `mcp-debug-refresh` at runtime. The tools are inert to the LLM, but they still occupy space in the
+> `tools/list` payload and add a small amount of routing overhead per call.
+
 ## Event System
 
 ```typescript

package/cli-template/FA-MCP-SDK-DOC/07-testing-and-operations.md

@@ -102,6 +102,91 @@ const result = await client.callTool('my_tool', { query: 'test' }, headers);
 - **Transport parity** — same behavior across STDIO, HTTP, SSE
 - **Edge cases** — empty strings, large payloads, special characters
 
+## Universal `debug-tool` for Integration Tests
+
+When the system-under-test is a **client** (Agent Tester, custom MCP host, CI smoke test) rather
+than the server, you usually need a server that produces every kind of `CallToolResult` on demand —
+text, image, audio, embedded resources, mixed blocks, `isError: true`, slow responses, large
+payloads. The SDK ships a single parameterised fixture so test code never has to roll its own
+fake server.
+
+Enable it together with the other built-ins ([06-utilities](06-utilities.md) → "Built-in Debug
+Tools"):
+
+```yaml
+mcp:
+  debug:
+    builtinTools: true
+```
+
+This appends a tool named `debug-tool` to the server's `tools/list`, hidden from the LLM via
+`_meta.ui.visibility: ['app']`.
+
+### Input Schema
+
+| Argument                   | Type / values                                                 | Default | Purpose                              |
+|----------------------------|---------------------------------------------------------------|---------|--------------------------------------|
+| `contentType`              | `text` \| `image` \| `audio` \| `resource` \| `resourceLink` \| `mixed` | `text`  | Which content-block type to emit. `mixed` returns one of each (ignores `multipleBlocks`) |
+| `multipleBlocks`           | `boolean`                                                     | `true`  | Emit 3 blocks of the chosen type vs. 1 |
+| `includeStructuredContent` | `boolean`                                                     | `true`  | Include `result.structuredContent` with `{ config, timestamp, counter, largeInputLength? }` |
+| `includeMeta`              | `boolean`                                                     | `true`  | Include `result._meta.debugInfo`     |
+| `simulateError`            | `boolean`                                                     | `false` | Set `result.isError = true` (call still resolves) |
+| `delayMs`                  | `number` ≥ 0                                                  | none    | Artificial latency for timeout / loading-state tests |
+| `largeInput`               | `string`                                                      | none    | Large payload — echoed back as `structuredContent.largeInputLength` |
+
+### Example: Single Server, Every Variation
+
+```typescript
+// tests/agent-tester/content-types.test.ts
+import { McpHttpClient } from 'fa-mcp-sdk';
+
+const client = new McpHttpClient('http://localhost:9876');
+
+test('renders mixed text + image + audio', async () => {
+  const result = await client.callTool('debug-tool', { contentType: 'mixed' });
+  expect(result.content).toHaveLength(3);
+  expect(result.content.map((b: any) => b.type)).toEqual(['text', 'image', 'audio']);
+});
+
+test('isError: true is surfaced', async () => {
+  const result = await client.callTool('debug-tool', {
+    contentType: 'text',
+    simulateError: true,
+  });
+  expect((result as any).isError).toBe(true);
+});
+
+test('respects delayMs for loading-state tests', async () => {
+  const t0 = Date.now();
+  await client.callTool('debug-tool', { contentType: 'text', delayMs: 800 });
+  expect(Date.now() - t0).toBeGreaterThanOrEqual(800);
+});
+
+test('large payload survives the round trip', async () => {
+  const big = 'x'.repeat(200_000);
+  const result = await client.callTool('debug-tool', { contentType: 'text', largeInput: big });
+  expect((result as any).structuredContent.largeInputLength).toBe(200_000);
+});
+```
+
+### Standalone Test Server
+
+If you need a throw-away server outside `initMcpServer` (e.g. spinning up a bare
+`@modelcontextprotocol/sdk` `McpServer` for an in-process test), use `registerDebugTool` directly:
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerDebugTool, DEBUG_TOOL_NAME } from 'fa-mcp-sdk';
+
+const server = new McpServer({ name: 'test-fixture', version: '0.0.0' });
+registerDebugTool(server);
+// → callTool(DEBUG_TOOL_NAME, { contentType: 'mixed' }) works against this server.
+```
+
+The helper accepts any object with `registerTool(name, def, handler)` — structurally compatible
+with the high-level SDK API — so the SDK does not pull in a hard dependency on
+`@modelcontextprotocol/sdk/server/mcp.js`.
+
 ## Best Practices
 
 ### Project Organization