fa-mcp-sdk 0.4.141 → 0.11.2

package/README.md

@@ -16,6 +16,11 @@ This framework provides complete infrastructure for building enterprise-grade MC
 - **Database Integration**: PostgreSQL with pgvector for vector operations
 - **Service Discovery**: Consul integration for microservices
 - **Rate Limiting**: Configurable rate limiting for all endpoints
+- **Transport Hardening**: Per-tool execution timeout, JSON-RPC request body cap and tool-result truncation —
+  all driven by `mcp.limits` in `config/default.yaml`:
+  - `mcp.limits.maxPayloadBytes` — max accepted request body (default 1 MiB; JSON-RPC `-32005` / HTTP 413 above)
+  - `mcp.limits.maxToolResultBytes` — max serialized tool result (default 10 MiB; truncated with explicit marker)
+  - `mcp.limits.toolTimeoutMs` — per-tool execution timeout (default 30 000 ms; JSON-RPC `-32004` / HTTP 504 above)
 - **API Documentation**: Automatic Swagger/OpenAPI generation
 - **Production Logging**: Structured logging with data masking
 - **Configuration Management**: YAML-based with environment overrides

package/cli-template/.dockerignore

@@ -0,0 +1,16 @@
+node_modules
+dist
+.vscode
+.git
+.claude
+.junie
+.run
+deploy
+tests
+coverage
+_logs
+_api_responses
+*.md
+!README.md
+.env*
+!.env.example

package/cli-template/.gitlab-ci.yml

@@ -0,0 +1,135 @@
+stages:
+  - lint
+  - test-build
+  - build-image
+  - deploy
+
+# ── CI: Merge Request checks ──────────────────────────────────────
+
+.node-template: &node-template
+  image: node:22-alpine
+  tags:
+    - docker
+  before_script:
+    - yarn install --frozen-lockfile
+  cache:
+    key:
+      files:
+        - yarn.lock
+    paths:
+      - node_modules/
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+
+lint:
+  <<: *node-template
+  stage: lint
+  script:
+    - yarn lint
+
+test-build:
+  <<: *node-template
+  stage: test-build
+  script:
+    - yarn build
+
+# ── CD: Build Docker Image ────────────────────────────────────────
+
+build-image:
+  stage: build-image
+  image: docker:27
+  services:
+    - docker:27-dind
+  tags:
+    - docker
+  script:
+    - docker compose -f deploy/docker/docker-compose.yml up -d --build --force-recreate app
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "master"'
+      when: manual
+
+# ── CD: Deploy ────────────────────────────────────────────────────
+# Замените <SERVER_TAG> на тег вашего сервера, <BRANCH> на целевую ветку,
+# <DEPLOY_DIR> на путь к проекту на сервере.
+
+# deploy_<instance>:
+#   stage: deploy
+#   tags:
+#     - <SERVER_TAG>
+#   variables:
+#     HOST_PORT: {{port}}
+#   environment:
+#     name: <instance>
+#   script:
+#     - docker compose -f deploy/docker/docker-compose.yml --env-file .env up -d --build --force-recreate app
+#     - |
+#       echo "Waiting for health check..."
+#       for i in $(seq 1 60); do
+#         if docker compose -f deploy/docker/docker-compose.yml exec -T app wget -q -O /dev/null http://localhost:{{port}}/health 2>/dev/null; then
+#           echo "Health check passed after ${i}s"
+#           break
+#         fi
+#         if [ "$i" -eq 60 ]; then
+#           echo "Health check failed after 60s"
+#           docker compose -f deploy/docker/docker-compose.yml logs --tail=50 app
+#           exit 1
+#         fi
+#         sleep 1
+#       done
+#     - docker compose -f deploy/docker/docker-compose.yml logs --tail=50 app
+#   rules:
+#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
+#       when: manual
+
+# stop_<instance>:
+#   stage: deploy
+#   tags:
+#     - <SERVER_TAG>
+#   environment:
+#     name: <instance>
+#   script:
+#     - docker compose -f deploy/docker/docker-compose.yml down
+#   rules:
+#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
+#       when: manual
+
+# restart_<instance>:
+#   stage: deploy
+#   tags:
+#     - <SERVER_TAG>
+#   variables:
+#     HOST_PORT: {{port}}
+#   environment:
+#     name: <instance>
+#   script:
+#     - docker compose -f deploy/docker/docker-compose.yml --env-file .env restart app
+#     - |
+#       echo "Waiting for health check..."
+#       for i in $(seq 1 60); do
+#         if docker compose -f deploy/docker/docker-compose.yml exec -T app wget -q -O /dev/null http://localhost:{{port}}/health 2>/dev/null; then
+#           echo "Health check passed after ${i}s"
+#           break
+#         fi
+#         if [ "$i" -eq 60 ]; then
+#           echo "Health check failed after 60s"
+#           docker compose -f deploy/docker/docker-compose.yml logs --tail=100 app
+#           exit 1
+#         fi
+#         sleep 1
+#       done
+#     - docker compose -f deploy/docker/docker-compose.yml logs --tail=100 app
+#   rules:
+#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
+#       when: manual
+
+# logs_<instance>:
+#   stage: deploy
+#   tags:
+#     - <SERVER_TAG>
+#   environment:
+#     name: <instance>
+#   script:
+#     - docker compose -f deploy/docker/docker-compose.yml logs --tail=100 app
+#   rules:
+#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
+#       when: manual

package/cli-template/AGENTS.md

@@ -131,6 +131,7 @@ Detailed fa-mcp-sdk docs are in `FA-MCP-SDK-DOC/`:
 | `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 |
+| `11-public-contract.md` | Formal SDK public contract — transports, endpoints, JWT claims, tool/prompt/resource format, error mapping, headers, semver & deprecation policy |
 
 ## Development and Testing Through Agent Tester
 

package/cli-template/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this MCP server are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every breaking change
+MUST be tagged with `[BREAKING]`. See
+[FA-MCP-SDK-DOC/11-public-contract.md](FA-MCP-SDK-DOC/11-public-contract.md#8-versioning-policy-171)
+for the MAJOR / MINOR / PATCH rules.
+
+## Versioning policy (summary)
+
+| Change                                                          | Bump  |
+|-----------------------------------------------------------------|-------|
+| Removing a tool / prompt / resource                             | MAJOR |
+| Adding a `required` field to an `inputSchema`                   | MAJOR |
+| Removing a field from an `outputSchema`                         | MAJOR |
+| Renaming or removing an HTTP endpoint                           | MAJOR |
+| Adding a new tool / prompt / resource                           | MINOR |
+| Adding an optional field to a schema                            | MINOR |
+| Bug-fix without contract impact                                 | PATCH |
+
+## [Unreleased]
+
+### Added
+
+- New tool `<name>` — short description (MINOR).
+- New optional argument `<arg>` on tool `<name>` (MINOR).
+
+### Changed
+
+- `<tool_name>` description clarified to mention the default value of `<arg>` (PATCH).
+
+### Deprecated
+
+- Tool `<old_name>` — replaced by `<new_name>`. Removal scheduled for 2026-08-28
+  (≥ 2 MINOR releases or 3 months — whichever comes later, per the public contract). The
+  SDK now emits `[DEPRECATED until 2026-08-28, use <new_name>]` on `tools/list` and a
+  `logger.warn` the first time per hour an old call lands.
+
+### Removed [BREAKING]
+
+- Removed deprecated tool `<old_old_name>` (MAJOR). Migration window closed on 2026-05-01.
+
+### Fixed
+
+- Race condition in `<tool>` when called concurrently from multiple sessions (PATCH).
+
+### Security
+
+- Bumped `fa-mcp-sdk` to `^0.8.0` for `X-Request-Id` correlation and `traceparent` propagation.
+
+---
+
+## [0.1.0] - YYYY-MM-DD
+
+Initial release.
+
+### Added
+
+- MCP server scaffolded from `fa-mcp-sdk`.
+- Tools: `<tool>` …
+- Prompts: `agent_brief`, `agent_prompt`.
+- Resources: `project://version`, `use://auth`.

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

@@ -13,16 +13,17 @@ npm install fa-mcp-sdk
 | File | Content | Read When |
 |------|---------|-----------|
 | [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, 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 |
+| [02-1-tools-and-api](02-1-tools-and-api.md) | Tool definitions, **snake_case name validation**, **`$schema` 2020-12 + `additionalProperties:false`**, **server-side `arguments` validation**, **`outputSchema` + `structuredContent` mirror**, `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, **parameterised prompts (`IPromptArgument[]`)**, resources, **built-in `project://version`, `use://auth`, `<name>://agent/brief\|prompt`**, **opt-in `resources/templates/list` + `resources/subscribe`**, `requireAuth` | Configuring prompts/resources |
+| [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 |
 | [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. **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) |
+| [11-public-contract](11-public-contract.md) | Formal public-contract surface of `fa-mcp-sdk`: transports, HTTP endpoints, JWT claims, tool/prompt/resource shape, error mapping, limits & headers (`X-Request-Id`, `traceparent`, `Retry-After`, `WWW-Authenticate`, `MCP-Session-Id`), semver policy, deprecation process | Pinning SDK version, planning a SDK upgrade, drafting CHANGELOG entries, deciding MAJOR vs MINOR vs PATCH |
 
 ## Key Exports
 
@@ -40,6 +41,28 @@ import {
   getJsonFromResult,
   TToolHandlerResponse, IToolHandlerTextResponse, IToolHandlerStructuredResponse,
   ToolExecutionError, ServerError, BaseMcpError, ValidationError, getTools,
+  // Appendix B errors — emitted by the SDK transport; re-throwable from tool / API code
+  PayloadTooLargeError, TimeoutError, RateLimitedError, ResourceNotFoundError,
+  MCP_ERROR_CODES, IMcpErrorData, createJsonRpcErrorResponse,
+} from 'fa-mcp-sdk';
+
+// Prompts (parameterised — standard §10.5) & Resources (templates/subscribe — §11.5)
+import {
+  IPromptArgument, IPromptData,
+  IIcon,                                              // §10.5/§11.3 — optional title/icons UI metadata
+  IResourceTemplateInfo,
+  notifyResourceUpdated,                              // call to broadcast `notifications/resources/updated`
+} from 'fa-mcp-sdk';
+
+// SSE resumability (standard §6) — opt-in via mcp.sse.resumability; maskSensitive (§12.2) — opt-in
+// result masking, applied by the server inside a tool handler.
+import { InMemoryEventStore, maskSensitive, IMaskRules } from 'fa-mcp-sdk';
+
+// Task-augmented execution (standard §8.7) — opt-in via mcp.tasks.enabled; declare a long-running
+// tool with execution.taskSupport. Storage is pluggable (default: in-memory, per-process).
+import {
+  getTaskStore, resetTaskStore, InMemoryTaskStore, toTaskDto, isTerminalTaskStatus,
+  ITaskStore, ITaskRecord, ITaskCreateInput, ITaskStoreOptions, TTaskStatus, TTaskPatch,
 } from 'fa-mcp-sdk';
 
 // Database & Cache

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

@@ -9,14 +9,67 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
 export const tools: Tool[] = [{
   name: 'my_custom_tool',
+  title: 'My custom tool',                                  // SHOULD §9.1 — human-readable name
   description: 'Description of what this tool does',
   inputSchema: {
+    $schema: 'https://json-schema.org/draft/2020-12/schema', // standard §9.2
     type: 'object',
     properties: {
       query: { type: 'string', description: 'Input query' },
       options: { type: 'object', description: 'Optional config' },
     },
     required: ['query'],
+    additionalProperties: false,                             // reject unknown fields
+  },
+}];
+```
+
+**Standard §9.1 (MUST) — tool name `name` MUST match `/^[a-z][a-z0-9_]{0,62}$/`** (ASCII
+snake_case, 1..63 chars). The SDK validates names eagerly at `initMcpServer()` for static
+tool arrays and lazily on the first `getTools()` call for dynamic (function-form) tools — a
+violation throws with the offending name printed.
+
+**Standard §9.2 — `inputSchema` SHOULD declare `$schema: '…/draft/2020-12/schema'` and
+`additionalProperties: false`.** Both fields are recognised by the `IToolInputSchema` type.
+
+**Standard §9.3 (MUST) — arguments are validated server-side.** Before `toolHandler` is
+called, the SDK validates `request.params.arguments` against `inputSchema` via ajv (draft
+2020-12). On failure the response is JSON-RPC `-32602` with
+`error.data = { field, reason }`; the handler is **not** invoked. This means tool code
+no longer needs to repeat shape checks — by the time the handler runs, `args` already
+matches the schema.
+
+### Output schema and `structuredContent` (standard §9.4 / §12.4)
+
+A tool MAY declare `outputSchema` to describe its `structuredContent` payload. When set,
+the SDK validates the handler's response against the schema — a violation raises JSON-RPC
+`-32603` (internal error: the tool broke its own contract). Whenever a response includes
+`structuredContent`, the SDK mirrors a serialised JSON copy into `content[0].text` so
+legacy clients that only read `content` keep working without code changes.
+
+```typescript
+export const tools: Tool[] = [{
+  name: 'search_docs',
+  title: 'Search documents',
+  description: 'Vector search over the knowledge base.',
+  inputSchema: { /* …as above… */ },
+  outputSchema: {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+    properties: {
+      results: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { id: { type: 'string' }, score: { type: 'number' } },
+          required: ['id'],
+          additionalProperties: true,
+        },
+      },
+      total: { type: 'number' },
+    },
+    required: ['results'],
+    additionalProperties: true,
   },
 }];
 ```
@@ -135,6 +188,148 @@ const clientIP = headers?.['x-real-ip'] || headers?.['x-forwarded-for'];
 `clientCapabilities`). See
 [ITransportContext](./02-2-prompts-and-resources.md#itransportcontext).
 
+### Cancellation (`signal`) — standard §8.5
+
+`IToolHandlerParams.signal?: AbortSignal` is flipped when the client sends
+`notifications/cancelled` for the current request. Pass it straight to any downstream
+`AbortSignal`-aware API (`fetch`, `pg`, `axios` ≥ 0.22, …) — they will abort their work and
+let the rejection propagate. Tool handlers MUST stop work once the signal aborts; the SDK
+then suppresses the JSON-RPC response per §8.5.
+
+```typescript
+export const handleToolCall = async (params: IToolHandlerParams): Promise<TToolHandlerResponse> => {
+  const { name, arguments: args, signal } = params;
+
+  switch (name) {
+    case 'search_documents': {
+      // Native AbortSignal forwarding — fetch will throw AbortError when the client cancels.
+      const res = await fetch(`https://docs.example.com/search?q=${encodeURIComponent(args.q)}`, {
+        signal,
+      });
+      const items = await res.json();
+      return formatToolResult({ items });
+    }
+  }
+};
+```
+
+For libraries that do not understand `AbortSignal` natively, gate the work with
+`signal.aborted` checks at safe seams (between DB pages, loop iterations, retry attempts):
+
+```typescript
+case 'long_running': {
+  for (const chunk of chunks) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new Error('cancelled');
+    }
+    await process(chunk);
+  }
+  return formatToolResult({ ok: true });
+}
+```
+
+When `signal` is `undefined` (legacy transports or older SDK consumers), behave as if it were
+never aborted — handlers should remain forward-compatible.
+
+### Progress (`sendProgress`) — standard §8.6
+
+`IToolHandlerParams.sendProgress?` emits `notifications/progress` whenever the request
+carried `_meta.progressToken`. When the client did not request progress, the SDK passes a
+no-op so the handler can call it unconditionally — no `if` guard needed.
+
+Rules enforced server-side:
+
+- progress values MUST be monotonically non-decreasing (smaller values are silently dropped);
+- emissions are throttled by `mcp.progress.throttleMs` (default 100 ms → max 10 events/s).
+
+```typescript
+case 'bulk_import': {
+  const rows = await loadRows(args.source);
+  for (let i = 0; i < rows.length; i++) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new Error('cancelled');
+    }
+    await importRow(rows[i]);
+    sendProgress?.(i + 1, rows.length, `imported ${rows[i].id}`);
+  }
+  return formatToolResult({ inserted: rows.length });
+}
+```
+
+The client receives:
+
+```json
+{
+  "method": "notifications/progress",
+  "params": {
+    "progressToken": "abc-123",
+    "progress": 42,
+    "total": 100,
+    "message": "imported acct-42"
+  }
+}
+```
+
+Choose `total` only when the upper bound is known up-front; otherwise omit it and the client
+will render an indeterminate spinner.
+
+### Task-augmented execution (long-running tools) — standard §8.7
+
+A normal `tools/call` is synchronous: the client holds the connection open until the tool returns,
+and the call is bound by the tool timeout (`mcp.limits.toolTimeoutMs`, 30 seconds by default). For
+operations that legitimately take minutes — bulk exports, report generation, long searches — the
+SDK supports **task-augmented execution**: the server returns a task identifier immediately and runs
+the tool in the background; the client then polls for status and fetches the result when ready.
+
+This feature is **opt-in and off by default**. To enable it:
+
+1. Set `mcp.tasks.enabled: true` in the configuration. The server then advertises the `tasks`
+   capability and accepts the lifecycle methods `tasks/list`, `tasks/get`, `tasks/result` and
+   `tasks/cancel`.
+2. Mark the long-running tool with `execution.taskSupport` in its declaration:
+
+```typescript
+{
+  name: 'generate_report',
+  title: 'Generate a large report',
+  description: 'Builds a multi-page report. Long-running — call it as a task.',
+  inputSchema: { /* … */ },
+  // 'optional' — the client MAY ask for a task but can still call synchronously.
+  // 'required' — the tool runs only as a task (a synchronous call is rejected with -32602).
+  // 'forbidden' / omitted — synchronous only.
+  execution: { taskSupport: 'optional' },
+}
+```
+
+The same handler runs whether the tool is invoked synchronously or as a task — the SDK always
+supplies `signal` and `sendProgress`. When the tool runs as a task, `signal` is flipped by
+`tasks/cancel`, progress is delivered through `notifications/progress`, and the SDK emits a
+`notifications/tasks/status` on every status change. On completion the task transitions to
+`completed` (carrying the same result a synchronous call would return); on a thrown error it
+transitions to `failed` with a sanitized message; on cancellation it transitions to `cancelled`.
+
+The client drives the lifecycle by sending a `task` parameter on `tools/call` and then polling:
+
+```jsonc
+// 1. Create — returns immediately with { task: { taskId, status: "working", … } }
+{ "method": "tools/call", "params": { "name": "generate_report", "arguments": {}, "task": {} } }
+
+// 2. Poll status until terminal
+{ "method": "tasks/get",    "params": { "taskId": "…" } }   // → { status: "working" | "completed" | … }
+
+// 3. Fetch the result once completed (same shape a synchronous tools/call returns)
+{ "method": "tasks/result", "params": { "taskId": "…" } }
+
+// Optional — abort a running task
+{ "method": "tasks/cancel", "params": { "taskId": "…" } }
+```
+
+The default task store keeps records **in process memory only** — it does not survive a server
+restart, and it is scoped to a single instance (no shared store across a cluster). Retention,
+poll interval and the retained-task cap are configured under `mcp.tasks.*` (see
+[03-configuration.md](./03-configuration.md)); the full method contract is in
+[11-public-contract.md](./11-public-contract.md) §4.
+
 ### MCP Apps — Reading Client Capabilities
 
 `params.clientCapabilities` carries the client's `initialize`-time capabilities (including the