fa-mcp-sdk 0.4.141 → 0.11.2

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

@@ -3,27 +3,53 @@
 ## Error Classes
 
 ```typescript
-import { BaseMcpError, ToolExecutionError, ValidationError, ServerError } from 'fa-mcp-sdk';
+import {
+  BaseMcpError, ToolExecutionError, ValidationError, ServerError,
+  // Phase 1 HTTP hardening — Appendix B specific errors:
+  PayloadTooLargeError, TimeoutError, RateLimitedError, ResourceNotFoundError,
+  MCP_ERROR_CODES, IMcpErrorData,
+} from 'fa-mcp-sdk';
 
 throw new ValidationError('Input validation failed');
 throw new ToolExecutionError('my_tool', 'Execution failed');
 throw new ServerError('Database connection failed', { key: 'value' });
 
-// Custom error
+// Standard §13 / Appendix B — already used by the SDK transport, but exported for tool / API code:
+throw new PayloadTooLargeError('Image exceeds 1 MiB');                   // -32005 / 413
+throw new TimeoutError('Upstream did not respond in time');               // -32004 / 504
+throw new RateLimitedError('Too many calls', 30);                        // -32003 / 429 (retryAfter=30s)
+throw new ResourceNotFoundError('Ticket not found', { field: 'key' });   // -32002 / 404
+
+// Custom error — supply both the legacy string code and the JSON-RPC numeric code
 class MyError extends BaseMcpError {
-  constructor(msg: string) { super(msg, 'MY_ERROR'); }
+  constructor(msg: string) {
+    super('MY_ERROR', msg, undefined, 422, undefined, -32600, { reason: 'my_reason' });
+  }
 }
 ```
 
-**ServerError**: `code: 'SERVER_ERROR'`, `httpStatus: 500`
+| Class | `code` | `jsonRpcCode` | HTTP | Standard |
+|-------|--------|---------------|------|----------|
+| `ServerError` | `SERVER_ERROR` | `-32000` (default) | 500 | — |
+| `ToolExecutionError` | `TOOL_EXECUTION_ERROR` | `-32000` (default) | 400 | — |
+| `ValidationError` | `VALIDATION_ERROR` | `-32000` (default) | 400 | — |
+| `ResourceNotFoundError` | `RESOURCE_NOT_FOUND` | `-32002` | 404 | Appendix B |
+| `RateLimitedError` | `RATE_LIMITED` | `-32003` | 429 | Appendix B |
+| `TimeoutError` | `TIMEOUT` | `-32004` | 504 | Appendix B |
+| `PayloadTooLargeError` | `PAYLOAD_TOO_LARGE` | `-32005` | 413 | Appendix B |
 
 ## Error Utilities
 
 ```typescript
 import { createJsonRpcErrorResponse, toError, toStr, addErrorMessage } from 'fa-mcp-sdk';
 
-// Create JSON-RPC error response
-const response = createJsonRpcErrorResponse(error, 'request-123');
+// Create JSON-RPC error response. Optional third argument injects extra `error.data` keys
+// (standard Appendix B.3 — { requestId?, field?, reason?, retryAfter?, … }).
+const response = createJsonRpcErrorResponse(error, 'request-123', { requestId: 'req-abc' });
+
+// Resulting body:
+// { jsonrpc: '2.0', id: 'request-123',
+//   error: { code: -32004, message: '…', data: { reason: 'tool_timeout', requestId: 'req-abc' } } }
 
 // Safe error conversion
 const err = toError(anything);      // → Error object
@@ -124,6 +150,41 @@ function getJsonFromResult<T = any>(result: TToolHandlerResponse | any): T;
   ignore `tools.answerAs`. Use when a specific shape is required.
 - **`getJsonFromResult()`** — Inverse of `formatToolResult()`. Extracts JSON from either format. Use in tests.
 
+## Masking Sensitive Data (`maskSensitive`, standard §12.2)
+
+Masking personal / sensitive data in tool results is the **server's** responsibility — the SDK never
+masks automatically (it does not know the domain model). `maskSensitive(value, rules)` is an optional,
+reusable helper: call it inside a tool handler before returning the result.
+
+```typescript
+import { maskSensitive } from 'fa-mcp-sdk';
+
+const result = await fetchUserRecord(args);
+// Mask by field name (case-insensitive) and/or regex on string values at any depth.
+const safe = maskSensitive(result, {
+  fieldNames: ['password', 'token', 'ssn', 'emailAddress'],
+  patterns: [/\b\d{13,19}\b/g],                 // card-like number sequences
+  replacement: '***',                            // default; or a function for partial masking
+});
+return formatToolResult(safe);
+
+// Partial masking via a replacement function:
+maskSensitive({ card: '4111111111111111' }, {
+  fieldNames: ['card'],
+  replacement: (v) => `${v.slice(0, 4)}********${v.slice(-4)}`,  // → '4111********1111'
+});
+```
+
+`IMaskRules`: `fieldNames?: string[]` (whole value of a matching key is replaced), `patterns?: RegExp[]`
+(matches in string values are replaced; use a global flag to replace all in one string), `replacement?:
+string | ((original: string) => string)` (default `'***'`). The input is never mutated; primitives pass
+through unchanged. It is **not** wired into `tools/call` — applying it and choosing the rules stays with
+the server.
+
+> **Caveat.** Mask what genuinely must not leave the server (secrets, raw emails, account ids). Avoid
+> blanket-masking display names the assistant actually needs to be useful (e.g. an issue's assignee) —
+> that trades correctness for nothing. Pick field names deliberately.
+
 ## Network Utilities
 
 ```typescript

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

@@ -20,13 +20,20 @@ const prompt = await client.getPrompt('agent_brief');
 
 ### HTTP Transport
 
+> **Deprecated:** `McpHttpClient` is now a thin alias of `McpStreamableHttpClient` (see below). The
+> server's `/mcp` endpoint runs the SDK `StreamableHTTPServerTransport`, so the old plain-POST client
+> no longer applies — both names speak the same Streamable HTTP protocol. Prefer
+> `McpStreamableHttpClient` in new code.
+
 ```typescript
 import { McpHttpClient } from 'fa-mcp-sdk';
 
-const client = new McpHttpClient('http://localhost:3000');
-const result = await client.callTool('my_tool', { query: 'test' }, {
-  'Authorization': 'Bearer token'
+// Auth headers go in the constructor (not as a per-call argument).
+const client = new McpHttpClient('http://localhost:3000', {
+  headers: { Authorization: 'Bearer token' },
 });
+await client.initialize();
+const result = await client.callTool('my_tool', { query: 'test' });
 ```
 
 ### SSE Transport
@@ -38,41 +45,50 @@ const client = new McpSseClient('http://localhost:3000');
 const result = await client.callTool('my_tool', { query: 'test' });
 ```
 
-### Streamable HTTP (MCP 2025)
+### Streamable HTTP (MCP 2025-11-25)
+
+Wraps the official `@modelcontextprotocol/sdk` `Client` + `StreamableHTTPClientTransport`. The SDK
+transport sets `Accept: application/json, text/event-stream`, captures/resends `Mcp-Session-Id`,
+negotiates the protocol version, and sends `DELETE /mcp` on `close()`.
 
 ```typescript
 import { McpStreamableHttpClient } from 'fa-mcp-sdk';
 
 const client = new McpStreamableHttpClient('http://localhost:3000', {
-  headers: { 'Authorization': 'Bearer token' },
+  headers: { Authorization: 'Bearer token' },
   requestTimeoutMs: 60000,
 });
 
-await client.initialize({
-  protocolVersion: '2024-11-05',
-  clientInfo: { name: 'test-client', version: '1.0.0' },
-});
+// `initialize()` runs the full handshake; the server answers the negotiated version (2025-11-25).
+await client.initialize();
 
 const result = await client.callTool('my_tool', { query: 'test' });
 const prompt = await client.getPrompt('agent_brief');
 const resources = await client.listResources();
 const content = await client.readResource('custom://data');
 
-// Notifications
-const unsub = client.onNotification('notifications/tools/list_changed', (p) => console.log(p));
-
 await client.close();
 ```
 
-**Methods:** `initialize`, `close`, `callTool`, `getPrompt`, `listResources`, `readResource`, `listTools`, `listPrompts`, `sendRpc`, `notify`, `onNotification`
+**Methods:** `initialize`, `close`, `callTool`, `getPrompt`, `listResources`, `readResource`,
+`listTools`, `listPrompts`. After `initialize()`, `client.serverInfo`, `client.capabilities` and
+`client.protocolVersion` are populated.
 
 ## Transport Types
 
 | Transport | Config | Use Case |
 |-----------|--------|----------|
 | STDIO | `mcp.transportType: "stdio"` | CLI, local dev |
-| HTTP | `mcp.transportType: "http"` | Web integrations, REST API |
-| SSE | HTTP transport | Long-running ops, streaming |
+| HTTP (Streamable HTTP) | `mcp.transportType: "http"` | Web integrations, REST API |
+| SSE (legacy) | HTTP transport | Long-running ops, streaming; older clients |
+
+The HTTP transport is **Streamable HTTP** (SDK `StreamableHTTPServerTransport`), stateful per session:
+
+| Method `/mcp` | Behaviour |
+|---------------|-----------|
+| `POST` | `initialize` opens a session (server returns `Mcp-Session-Id`); subsequent calls must echo it. Notifications → **202**. No session + not `initialize` → **400**. |
+| `GET` | Server→client SSE stream for the session. |
+| `DELETE` | Tears down the session. |
 
 ## Running Tests
 

package/cli-template/FA-MCP-SDK-DOC/10-mcp-apps.md

@@ -485,7 +485,7 @@ import {
 |-----------|--------|--------------|
 | STDIO | `Server.getClientCapabilities()` (low-level SDK) read inside every handler in `createMcpServer()`. | Every call. |
 | SSE | Same as STDIO, but resolved per-connection (each SSE session owns its own `Server`). | Every call. |
-| Streamable HTTP | Cached on `initialize` keyed by `Mcp-Session-Id` (in-memory `Map`, soft FIFO cap of 4096 sessions). | Subsequent calls only when the client sends the `Mcp-Session-Id` header. `undefined` otherwise — handlers MUST fall back to text-only. |
+| Streamable HTTP | Same as STDIO — each session owns its own `Server` + `StreamableHTTPServerTransport` (stateful, keyed by `Mcp-Session-Id`, in-memory `Map` with soft FIFO cap of 4096 sessions). `getClientCapabilities()` is read per handler. | Every call within a session. A client that never sends `Mcp-Session-Id` cannot make post-`initialize` calls (→ 400), so handlers still treat `undefined` as text-only. |
 
 ```ts
 export const handleToolCall = async (params: IToolHandlerParams) => {

package/cli-template/FA-MCP-SDK-DOC/11-public-contract.md

@@ -0,0 +1,342 @@
+# 11 — Public Contract
+
+This document is the **formal public contract** of the `fa-mcp-sdk` package. Everything listed
+here is part of the API surface that the SDK guarantees, and every change to it follows the
+versioning policy at the bottom of this file (semver: MAJOR / MINOR / PATCH).
+
+If a behaviour is **not** described here — even if it is currently observable in the source — it
+is considered an implementation detail and may change in any release.
+
+---
+
+## 1. Transports
+
+| Transport          | Standard | Status | Notes                                                       |
+|--------------------|----------|--------|-------------------------------------------------------------|
+| `stdio`            | §6       | MUST   | Single JSON-RPC stream over stdin/stdout                    |
+| `streamable_http`  | §6       | MUST   | `POST/GET/DELETE /mcp` driven by the SDK transport          |
+| `legacy_http_sse`  | §6       | SHOULD | `GET /sse` + `POST /messages` — kept for backwards-compat   |
+
+All HTTP routes hosted by the SDK are listed in §2.
+
+**SSE resumability (opt-in, §6 MAY).** With `mcp.sse.resumability: true` the Streamable HTTP transport
+keeps recent SSE events in a per-process in-memory ring buffer (`mcp.sse.maxStoredEvents`, default 1000),
+so a client reconnecting to `GET /mcp` with a `Last-Event-ID` header replays the events it missed. Off by
+default. The buffer does not survive a restart and does not span multiple server instances — a persistent
+store would be required for that.
+
+---
+
+## 2. HTTP endpoints
+
+| Path                                              | Method | Auth | Level  | Purpose                                                       |
+|---------------------------------------------------|--------|------|--------|---------------------------------------------------------------|
+| `/mcp`                                            | POST   | Yes  | MUST   | JSON-RPC entry point (`initialize`, `tools/*`, …)             |
+| `/mcp`                                            | GET    | Yes  | MUST   | Server-initiated SSE stream for the active session            |
+| `/mcp`                                            | DELETE | Yes  | MUST   | Session teardown                                              |
+| `/sse`                                            | GET    | Yes  | SHOULD | Legacy SSE connect                                            |
+| `/sse`                                            | POST   | Yes  | SHOULD | Legacy direct JSON-RPC                                        |
+| `/messages`                                       | POST   | Yes  | SHOULD | Legacy SSE message channel                                    |
+| `/health`                                         | GET    | No   | MUST   | Liveness; returns `{status, version, uptime, details}`        |
+| `/ready`                                          | GET    | No   | SHOULD | Readiness; `{status, checks}`                                 |
+| `/metrics`                                        | GET    | No   | SHOULD | Prometheus exposition (opt-in via `webServer.metrics.enabled`) |
+| `/`                                               | GET    | No   | MAY    | Static home page                                              |
+| `/ct`                                             | POST   | No   | MUST   | Token validity check via JSON body                            |
+| `/ct?t=…`                                         | GET    | No   | MAY    | Disabled by default (`webServer.tokenCheck.allowQueryToken`)  |
+| `/used-http-headers`                              | GET    | No   | MAY    | Returns the project's `usedHttpHeaders` declaration           |
+| `/.well-known/oauth-protected-resource`           | GET    | No   | MUST*  | Active in JWT modes `embedded` / `localKey` / `remoteJwks`    |
+| `/.well-known/openid-configuration`               | GET    | No   | MUST*  | OIDC discovery                                                |
+| `/.well-known/jwks.json`                          | GET    | No   | MUST*  | JWK Set with the active public key                            |
+| `/oauth/token`                                    | POST   | No   | MUST*  | Embedded IdP — `grant_type=password`                          |
+| `/gen-jwt`                                        | POST   | Yes  | MAY    | JWT issuance API (`webServer.genJwtApiEnable`)                |
+| `/admin`                                          | GET    | Yes  | MAY    | Token Generator UI                                            |
+| `/agent-tester`                                   | GET    | Yes? | MAY    | Built-in chat UI (`agentTester.enabled`)                      |
+| `/api/openapi.json` / `/api/openapi.yaml` / `/docs` | GET  | -    | MAY    | OpenAPI when the project supplies `httpComponents.apiRouter`  |
+
+`MUST*` rows are mandatory only when the corresponding feature is active.
+
+---
+
+## 3. Authentication
+
+The SDK accepts the following `Authorization` schemes, picked by header format (not order):
+
+- `Bearer <token>` — JWT (any of the four modes: `legacyAesCtr` / `embedded` / `localKey` /
+  `remoteJwks`) or a permanent server token.
+- `Basic <base64>` — HTTP Basic auth.
+- Optional `customAuthValidator` — last fallback for project-specific schemes.
+
+JWT modes are documented in [04-authentication](04-authentication.md). Public contract:
+
+| Claim       | Required | Notes                                                                    |
+|-------------|----------|--------------------------------------------------------------------------|
+| `sub`       | MUST     | Subject — drives rate-limit bucket and concurrency cap                   |
+| `exp`       | MUST     | Expiration; SDK enforces with `clockSkew` (default 30 s, max 60 s)       |
+| `aud`       | SHOULD   | Defaults to `appConfig.name`; configurable via `expectedAudience`        |
+| `iss`       | SHOULD*  | Required in modes `embedded` / `localKey` / `remoteJwks`                 |
+| `scope`     | MAY      | Space-separated scopes; matched against `requiredScopes` per §7.5        |
+| `ip`        | MAY      | When set + `isCheckIP=true`, client IP must match                        |
+| `service`   | MAY      | When set + `checkMCPName=true`, must contain `appConfig.name`            |
+| `jti`       | MAY      | Used by the revocation list                                              |
+
+Scopes are matched against `requiredScopes` on tools, prompts, and resources (§7.5).
+
+`WWW-Authenticate: Bearer realm="<name>" resource_metadata="<url>"` is emitted on every 401
+from MCP endpoints per §7.4. 403 responses (authenticated but forbidden) carry NO
+`WWW-Authenticate` header.
+
+---
+
+## 4. MCP methods
+
+| Method                                | Status | Notes                                                     |
+|---------------------------------------|--------|-----------------------------------------------------------|
+| `initialize`                          | MUST   |                                                           |
+| `notifications/initialized`           | MUST   |                                                           |
+| `tools/list`                          | MUST   | Server-side pagination via `mcp.pagination.pageSize`      |
+| `tools/call`                          | MUST   | Honours `signal`, `_meta.progressToken`, `requiredScopes` |
+| `prompts/list`                        | MUST   | Capability advertised only when the server has prompts (§8.2) |
+| `prompts/get`                         | MUST   | Returns `-32601` when no prompts are configured           |
+| `resources/list`                      | MUST   | Same pagination contract                                  |
+| `resources/read`                      | MUST   | Returns `text` or base64 `blob` per entry (§11.4)         |
+| `resources/templates/list`            | MAY    | `mcp.resources.templatesEnabled`                          |
+| `resources/subscribe` / `unsubscribe` | MAY    | `mcp.resources.subscribeEnabled`                          |
+| `completion/complete`                 | MAY    | `mcp.completions.enabled` + `completionProvider` (§8.2)   |
+| `tasks/list`                          | MAY    | `mcp.tasks.enabled`; caller's own tasks, newest first, paginated (§8.7) |
+| `tasks/get`                           | MAY    | `mcp.tasks.enabled`; current task metadata (§8.7)        |
+| `tasks/result`                        | MAY    | `mcp.tasks.enabled`; the `tools/call` result once completed (§8.7) |
+| `tasks/cancel`                        | MAY    | `mcp.tasks.enabled`; aborts a running task, idempotent (§8.7) |
+| `logging/setLevel`                    | SHOULD | Capability `logging: {}` (default ON)                     |
+| `notifications/message`               | SHOULD | Emitted by `sendLoggingMessage()`                         |
+| `notifications/progress`              | SHOULD | Emitted by `IToolHandlerParams.sendProgress()` (§8.6)     |
+| `notifications/cancelled`             | SHOULD | Aborts `IToolHandlerParams.signal` (§8.5)                 |
+| `notifications/tasks/status`          | MAY    | Emitted on every task status transition (§8.7)           |
+
+When `mcp.tasks.enabled` is `true`, the server advertises the `tasks` capability
+(`{ list, cancel, requests: { tools: { call } } }`) and a `tools/call` carrying a `task` parameter
+is executed as a task: the server returns a `CreateTaskResult` (`{ task: { taskId, status, … } }`)
+immediately and runs the tool in the background. A tool opts in via `execution.taskSupport`
+(`optional` / `required` / `forbidden`, see §5) — sending `task` to a tool that does not support it,
+or omitting `task` for a `required` tool, returns `-32602`. The default task store keeps records in
+process memory only; it does **not** survive a restart. When `mcp.tasks.enabled` is `false` (the
+default) the capability is not advertised and all four `tasks/*` methods return `-32601`.
+
+---
+
+## 5. Tool / Prompt / Resource format
+
+### Tool (`Tool` from `@modelcontextprotocol/sdk`)
+
+- `name` — MUST be `snake_case` and unique (validated at boot via
+  `validate-tool-names.ts`).
+- `description` — MUST be non-empty. Deprecation prefix `[DEPRECATED until …]` is added
+  automatically when `_meta.deprecated` is set.
+- `inputSchema` — MUST declare `$schema: 'https://json-schema.org/draft/2020-12/schema'` and
+  `additionalProperties: false`.
+- `outputSchema` — MAY; when present, the SDK validates `structuredContent` against it and
+  mirrors the value into `content[0]` as JSON text (§12.4).
+- `title` — SHOULD; user-facing label.
+- `execution.taskSupport` — MAY; one of `optional` / `required` / `forbidden` (default — absence is
+  treated as `forbidden`, i.e. synchronous only). Controls task-augmented execution (§8.7); passed
+  through verbatim in `tools/list`. Effective only when `mcp.tasks.enabled` is `true`.
+- `annotations` — MAY; may be hidden via `mcp.tools.hideAnnotations`.
+- `_meta._meta.requiredScopes` (or top-level `requiredScopes`) — MAY; OAuth scopes enforced
+  before dispatch.
+- `_meta.deprecated` — MAY; structured `IDeprecationInfo`.
+- `_meta.ui` — MAY; MCP Apps widget metadata.
+
+### Prompt (`IPromptData`)
+
+`name`, `description`, `arguments[]` (each `IPromptArgument`), `content` (string or function),
+`requireAuth`, `requiredScopes`, `deprecated`. Optional UI metadata (§10.5, MAY): `title` (human-facing
+label, falls back to `name`) and `icons` (`IIcon[]` — `{ src; mimeType?; sizes? }`). Both pass through
+`prompts/list` unchanged; built-in `agent_brief` / `agent_prompt` carry a `title`.
+
+### Resource (`IResourceData` / `IResourceInfo`)
+
+`uri`, `name`, `description`, `mimeType`, optional `title`, `size` (bytes, §11.3 MAY),
+`icons` (`IIcon[]`, §11.3 MAY), `requireAuth`, `requiredScopes`, `_meta`, `deprecated`. On
+`resources/list` the SDK computes `size` from the content (UTF-8 byte length for text/objects, buffer
+length for blobs) when the author did not set it; lazy (function) content omits `size`. `content` is a
+string / object / function for text resources, or
+`IResourceBinaryContent` (`{ blob: Buffer | base64-string, base64?: boolean }`) for binary
+resources — `resources/read` then returns base64 `contents[0].blob` (no `text`) with the
+resource's `mimeType` (§11.4 / §12.2). Built-in URI schemes are guaranteed by the SDK:
+
+| URI                                        | Purpose                                        |
+|--------------------------------------------|------------------------------------------------|
+| `project://version`                        | Returns `appConfig.version`                    |
+| `use://auth`                               | Authentication self-description                |
+| `<service>://agent/brief`                  | Mirrors `agent_brief` prompt                   |
+| `<service>://agent/prompt`                 | Mirrors `agent_prompt` prompt                  |
+| `doc://...`                                | Application docs                               |
+
+### Sensitive data masking (`maskSensitive`, §12.2)
+
+Masking personal / sensitive data in tool results is the server's responsibility — the SDK never masks
+automatically. The optional helper `maskSensitive(value, rules)` (exported from the barrel, with the
+`IMaskRules` type) is a reusable building block: it walks an object / array / string and applies explicit
+rules — `fieldNames` (case-insensitive field-name match) and `patterns` (regular expressions on string
+values at any depth) — replacing matches with `replacement` (a string, default `'***'`, or a function for
+partial masking like `4111********1111`). It returns a new value and never mutates the input. Call it
+inside a tool handler before returning the result; choosing the rules and where to apply them stays with
+the server.
+
+---
+
+## 6. Error format
+
+JSON-RPC errors follow Appendix B of the standard. Mapping (JSON-RPC → HTTP):
+
+| JSON-RPC code | HTTP | Class                | Trigger                                       |
+|---------------|------|----------------------|-----------------------------------------------|
+| `-32600`      | 400  | (none)               | Invalid Request                               |
+| `-32601`      | 404  | `ResourceNotFoundError` (when applicable) | Method/resource not found  |
+| `-32602`      | 400  | `ValidationError`    | Invalid params (input schema, unknown tool)   |
+| `-32603`      | 500  | `ServerError`        | Internal error                                |
+| `-32000`      | varies | `BaseMcpError`     | Generic SDK error                             |
+| `-32002`      | 404  | `ResourceNotFoundError` | Resource lookup failed                     |
+| `-32003`      | 429  | `RateLimitedError`   | Rate limit / concurrent-call cap (+ `Retry-After`) |
+| `-32004`      | 504  | `TimeoutError`       | `mcp.limits.toolTimeoutMs` exceeded           |
+| `-32005`      | 413  | `PayloadTooLargeError` | `mcp.limits.maxPayloadBytes` exceeded       |
+| `-32006`      | 503  | `UpstreamUnavailableError` | Dependency (DB / downstream) unreachable  |
+| `-32007`      | 409  | `ConflictError`      | State conflict (duplicate / optimistic lock)  |
+
+Unrecognized internal errors are sanitized (§13.3 / Appendix C.3): the outward `error.message`
+collapses to `Internal error`, the full text is written to the internal log keyed by `requestId`,
+and absolute filesystem paths are scrubbed from any outward message. Recognized domain errors (any
+class above) keep their message verbatim.
+
+`error.data` is structured per Appendix B.3:
+
+```jsonc
+{
+  "requestId": "uuid…",         // §15.1, always set by the SDK if absent
+  "field": "name",              // input validation diagnostics
+  "reason": "invalid_type",     // machine-readable hint
+  "retryAfter": 12              // seconds, for -32003
+  // …implementation-specific keys are allowed but not part of the contract
+}
+```
+
+---
+
+## 7. Limits and headers
+
+| Limit / Header               | Source / Default                                                        |
+|------------------------------|-------------------------------------------------------------------------|
+| `mcp.limits.maxPayloadBytes` | 1 MiB                                                                   |
+| `mcp.limits.maxToolResultBytes` | 10 MiB                                                                |
+| `mcp.limits.toolTimeoutMs`   | 30 000 ms                                                               |
+| `mcp.rateLimit.maxRequests`  | 100 / window                                                            |
+| `mcp.rateLimit.windowMs`     | 60 000 ms                                                               |
+| `mcp.rateLimit.maxConcurrentPerSubject` | 16                                                            |
+| `mcp.pagination.pageSize`    | 100                                                                     |
+| `mcp.logging.defaultLevel`   | `info` (Syslog ladder)                                                  |
+| `mcp.progress.throttleMs`    | 100 (10 events/s/token)                                                 |
+| `mcp.completions.enabled`    | `false` (opt-in; needs `completionProvider`)                            |
+| `mcp.tasks.enabled`          | `false` (opt-in; advertises `tasks` capability)                        |
+| `mcp.tasks.defaultTtlMs`     | 3 600 000 ms (finished-task retention; clamped to `[minTtlMs, maxTtlMs]`) |
+| `mcp.tasks.maxTtlMs`         | 86 400 000 ms (hard retention ceiling)                                  |
+| `mcp.tasks.pollIntervalMs`   | 1000 ms (suggested to client in every task object)                     |
+| `mcp.tasks.maxTasks`         | 1000 (retained tasks; oldest finished evicted first)                   |
+| `webServer.metrics.enabled`  | `false` (opt-in)                                                        |
+| `X-Request-Id` (response)    | Always present — generated when client did not supply one (§15.1)       |
+| `tracestate` (response)      | Echoed back unchanged when client supplied a valid value                |
+| `WWW-Authenticate`           | On every 401 from MCP endpoints (§7.4)                                  |
+| `Retry-After`                | On every 429 (§14)                                                      |
+| `MCP-Session-Id`             | Set by SDK on `initialize`; subsequent requests MUST echo it            |
+| `MCP-Protocol-Version`       | Negotiated by the SDK transport                                         |
+
+---
+
+## 8. Versioning policy (§17.1)
+
+| Change                                                          | Bump  |
+|-----------------------------------------------------------------|-------|
+| Removing a tool / prompt / resource                             | MAJOR |
+| Adding a `required` field to an `inputSchema`                   | MAJOR |
+| Removing a field from an `outputSchema`                         | MAJOR |
+| Changing the default JWT algorithm / mode                       | MAJOR |
+| Renaming or removing an HTTP endpoint                           | MAJOR |
+| Removing a configuration key (`mcp.*`, `webServer.*`, …)        | MAJOR |
+| Backwards-incompatible change to `error.data` shape             | MAJOR |
+| Adding a new tool / prompt / resource                           | MINOR |
+| Adding an optional field to any schema                          | MINOR |
+| Adding a new capability or behaviour gated by an opt-in flag    | MINOR |
+| Adding a new optional configuration key (with safe default)     | MINOR |
+| Extending `description` or `title`                              | PATCH |
+| Bug-fix without changing the contract                           | PATCH |
+| Documentation-only change                                       | PATCH |
+
+`[BREAKING]` is the required marker in `CHANGELOG.md` for any MAJOR entry.
+
+### Historical examples
+
+| Release | Bump  | Driver                                                                 |
+|---------|-------|------------------------------------------------------------------------|
+| 0.4.145 | MINOR | MCP 2025-11-25 via SDK Streamable HTTP                                 |
+| 0.5.0   | MAJOR | HTTP hardening (default bind `127.0.0.1`, error codes, rate-limit)     |
+| 0.6.0   | MAJOR | Tools/Prompts/Resources contract (`additionalProperties:false`, mirror)|
+| 0.7.0   | MAJOR | RS256/ES256 JWT runtime, OAuth/OIDC discovery, scope enforcement       |
+| 0.8.x   | MINOR | Observability (X-Request-Id, traceparent, logging, metrics, progress)  |
+| 0.9.1   | MINOR | Conditional capabilities, `-32006`/`-32007`, binary `blob`, error sanitization, opt-in completions |
+| 0.10.0  | MINOR | Opt-in `tasks` capability (task-augmented execution), `execution.taskSupport`, in-memory task store |
+
+---
+
+## 9. Deprecation process (§17.2)
+
+Authors declare deprecation in a structured shape (no free-form `[DEPRECATED]` in descriptions):
+
+```typescript
+// tools.ts
+const myTool: Tool = {
+  name: 'old_tool',
+  description: 'Returns the rate.',
+  _meta: {
+    deprecated: { until: '2026-08-28', replacedBy: 'new_tool', note: 'See migration guide' },
+  },
+  // …
+};
+
+// prompts / resources
+const myPrompt: IPromptData = {
+  name: 'old_prompt',
+  description: '…',
+  deprecated: { until: '2026-08-28', replacedBy: 'new_prompt' },
+  // …
+};
+```
+
+The SDK then:
+
+1. mutates `description` on list responses to include
+   `[DEPRECATED until YYYY-MM-DD, use <replacedBy>]`;
+2. logs a `logger.warn` the first time per hour each `(kind, name)` is invoked;
+3. logs a `logger.error` at registration time if `until` is already in the past — the entry
+   should be removed instead of shipped.
+
+**Window**: minimum `2 MINOR releases OR 3 months` from announcement to removal (per §17.2),
+whichever is longer.
+
+---
+
+## 10. Public contract source list
+
+The runtime sources of the contract above are:
+
+- `src/core/_types_/types.ts` — `IToolHandlerParams`, `IPromptData`, `IResourceInfo`,
+  `IDeprecationInfo`, `McpServerData`.
+- `src/core/_types_/config.ts` — `AppConfig` (every documented configuration key).
+- `src/core/errors/BaseMcpError.ts` + `src/core/errors/specific-errors.ts` — error codes.
+- `src/core/mcp/create-mcp-server.ts` — handler contract.
+- `src/core/mcp/task-store.ts` — `ITaskStore` / `InMemoryTaskStore`, task lifecycle (§8.7).
+- `src/core/web/server-http.ts` — HTTP endpoints, headers, response shape.
+- `src/core/web/request-id.ts` — `X-Request-Id` + W3C trace context middleware.
+- `src/core/mcp/mcp-logging.ts` — `logging` capability.
+- `src/core/metrics/metrics.ts` — Prometheus series.
+- `src/core/mcp/deprecation.ts` — deprecation lifecycle.
+
+Anything that lives outside this list (file names, internal helpers, log line formats, etc.) is
+**not** part of the contract and may change without notice.

package/cli-template/README.md

@@ -208,3 +208,40 @@ Generate an admin-capable JWT:
 node scripts/generate-jwt.js -u admin -ttl 30d -p "allow=gen-token"
 ```
 
+## Public Contract
+
+The runtime contract surfaced by this server (transports, HTTP endpoints, JWT claims, tool /
+prompt / resource shape, error mapping, headers, semver and deprecation policy) is documented
+in [FA-MCP-SDK-DOC/11-public-contract.md](FA-MCP-SDK-DOC/11-public-contract.md).
+
+Tools, prompts and resources exposed by this project are listed in the table below — update
+this section whenever you add, rename, or remove an entry.
+
+### Tools
+
+| Name | Description |
+|------|-------------|
+| `<tool_name>` | Short description |
+
+### Prompts
+
+| Name | Description |
+|------|-------------|
+| `agent_brief` | Short agent description (built-in) |
+| `agent_prompt` | Full system prompt (built-in) |
+
+### Resources
+
+| URI | Description |
+|-----|-------------|
+| `project://version` | SDK / project version (built-in) |
+| `use://auth` | Authentication self-description (built-in) |
+| `<service>://agent/brief` | Mirror of `agent_brief` (built-in) |
+| `<service>://agent/prompt` | Mirror of `agent_prompt` (built-in) |
+
+## Versioning policy
+
+This project follows the semver contract documented in
+[FA-MCP-SDK-DOC/11-public-contract.md](FA-MCP-SDK-DOC/11-public-contract.md#8-versioning-policy-171).
+Mark every `MAJOR` change with `[BREAKING]` in `CHANGELOG.md`.
+

package/cli-template/deploy/docker/.env.example

@@ -0,0 +1,10 @@
+# ── Image tag (set by CI deploy job) ───────────────────────
+IMAGE_TAG={{project.name}}:latest
+
+# ── Host port (external port on the server) ────────────────
+HOST_PORT={{port}}
+
+# ── Service identity ──────────────────────────────────────
+SERVICE_NAME={{project.name}}
+SERVICE_INSTANCE=prod
+NODE_ENV=production

package/cli-template/deploy/docker/Dockerfile

@@ -0,0 +1,44 @@
+# ── Stage 1: install + build ──────────────────────────────────────────────────
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Зависимости (кэшируется отдельным слоем)
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --production=false
+
+# Исходники и конфиг сборки
+COPY tsconfig.json ./
+COPY src/ ./src/
+COPY scripts/ ./scripts/
+COPY config/ ./config/
+
+# Backend build (tsc → dist/)
+RUN npm run build
+
+# ── Stage 2: production image ────────────────────────────────────────────────
+FROM node:22-alpine AS production
+
+WORKDIR /app
+
+ARG NODE_ENV=production
+ENV NODE_ENV=${NODE_ENV}
+
+# Только production-зависимости
+COPY package.json yarn.lock ./
+RUN yarn install --production=true && yarn cache clean
+
+# Собранный backend
+COPY --from=builder /app/dist/ ./dist/
+
+# Конфиги (default.yaml, production.yaml, custom-environment-variables.yaml и т.д.)
+COPY --from=builder /app/config/ ./config/
+
+# Внешние конфиги (local.yaml) монтируются через volumes в docker-compose.yml.
+
+EXPOSE {{port}}
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+  CMD wget --spider -q http://localhost:{{port}}/health || exit 1
+
+ENTRYPOINT ["node", "dist/src/start.js"]