fa-mcp-sdk 0.4.142 → 0.11.2

package/cli-template/FA-MCP-SDK-DOC/02-2-prompts-and-resources.md

@@ -28,20 +28,47 @@ export const AGENT_PROMPT = `You are a database management assistant.
 Add in `src/prompts/custom-prompts.ts`:
 
 ```typescript
-import { IPromptData, IGetPromptRequest } from 'fa-mcp-sdk';
+import { IPromptData, IGetPromptRequest, IPromptArgument } from 'fa-mcp-sdk';
 
 export const customPrompts: IPromptData[] = [
   { name: 'greeting', description: 'Greeting message', arguments: [],
     content: 'Hello! How can I help?' },
 
-  { name: 'context_prompt', description: 'Context-aware', arguments: [],
-    content: (req: IGetPromptRequest) => `Context: ${JSON.stringify(req.params.arguments)}` },
+  // Standard §10.5 — parameterised prompt. The `arguments[]` array is advertised in
+  // prompts/list; the values arrive as `request.params.arguments` (string map) on
+  // prompts/get. The content function receives them as the second argument.
+  {
+    name: 'context_prompt',
+    description: 'Context-aware prompt with explicit arguments',
+    arguments: [
+      { name: 'topic',    description: 'Subject area to focus on', required: true },
+      { name: 'audience', description: 'Audience level (junior / senior)',     required: false },
+    ] satisfies IPromptArgument[],
+    content: (_req, args) =>
+      `Focus on ${args?.topic ?? 'the codebase'} for a ${args?.audience ?? 'mixed'} audience.`,
+  },
 
   { name: 'admin_only', description: 'Admin instructions', arguments: [],
     content: 'Admin-only content', requireAuth: true },
+
+  // Standard §10.5 (MAY) — optional UI metadata. `title` is a human-facing label (falls back to
+  // `name`); `icons` is an `IIcon[]` (`{ src; mimeType?; sizes? }`, `src` = absolute URL or data: URI).
+  // Both only affect display in the client UI and pass through prompts/list unchanged.
+  {
+    name: 'release_notes',
+    title: 'Release notes',
+    icons: [{ src: 'https://cdn.example.com/notes.png', mimeType: 'image/png', sizes: '48x48' }],
+    description: 'Release change summary',
+    arguments: [],
+    content: 'Summary of changes for the current release.',
+  },
 ];
 ```
 
+> **Compatibility.** The old single-argument signature
+> `(req: IGetPromptRequest) => string` still works — the second `args` parameter is
+> optional. Only update prompts that need access to the values.
+
 Pass to server:
 ```typescript
 const serverData: McpServerData = { ..., customPrompts };
@@ -114,12 +141,21 @@ export const customPrompts = async (ctx: ITransportContext): Promise<IPromptData
 
 ### Standard Resources
 
-| URI | Description |
-|-----|-------------|
-| `project://id` | Service identifier (`appConfig.name`) |
-| `project://name` | Display name (`appConfig.productName`) |
-| `doc://readme` | README.md content |
-| `use://http-headers` | Used HTTP headers (from `usedHttpHeaders`) |
+| URI | MIME | Description |
+|-----|------|-------------|
+| `project://id` | `text/plain` | Service identifier (`appConfig.name`) |
+| `project://name` | `text/plain` | Display name (`appConfig.productName`) |
+| `project://version` | `text/plain` | Server version (`appConfig.version`) — mirror of `GET /health.version` and `serverInfo.version` (standard §4 SHOULD) |
+| `doc://readme` | `text/markdown` | README.md content |
+| `use://http-headers` | `application/json` | Used HTTP headers (from `usedHttpHeaders`) |
+| `use://auth` | `application/json` | Enabled auth schemes / methods / expected JWT claims (standard §11.2 SHOULD) |
+| `<appConfig.name>://agent/brief` | `text/markdown` | Mirror of `agent_brief` prompt (Avatar profile §11.2) |
+| `<appConfig.name>://agent/prompt` | `text/markdown` | Mirror of `agent_prompt` prompt (Avatar profile §11.2) |
+
+> The `<appConfig.name>://agent/*` URIs are built automatically from `appConfig.name`
+> (e.g. `mcp-jira://agent/brief`). If a project's `customResources` list contains a
+> resource with the same URI, the project-supplied entry wins — handy when the service
+> needs to publish a different brief through the resources endpoint than through prompts.
 
 ### Custom Resources
 
@@ -142,6 +178,15 @@ export const customResources: IResourceData[] = [
 
   { uri: 'custom://secrets', name: 'Secrets', description: 'Protected',
     mimeType: 'application/json', content: {}, requireAuth: true },
+
+  // Standard §11.3 (MAY) — optional UI metadata. `title` is a human-facing label; `icons` is an
+  // `IIcon[]` (same shape as prompts). `size` (bytes) is optional: on resources/list the SDK
+  // computes it from the content (UTF-8 byte length for text/objects, buffer length for blobs) when
+  // not set; lazy (function) content omits `size`. An author-supplied `size` is preserved.
+  { uri: 'custom://logo', name: 'logo', title: 'Brand logo', description: 'SVG logo',
+    mimeType: 'image/svg+xml', size: 1234,
+    icons: [{ src: 'https://cdn.example.com/logo.svg', mimeType: 'image/svg+xml' }],
+    content: '<svg …>' },
 ];
 ```
 
@@ -150,6 +195,35 @@ Pass to server:
 const serverData: McpServerData = { ..., customResources };
 ```
 
+### Binary Resources (`blob`)
+
+A resource whose payload is not text (image, PDF, archive, …) declares `content` as
+`IResourceBinaryContent` instead of a string. `resources/read` then returns the bytes as base64
+`contents[0].blob` (with the resource's `mimeType`) and omits `text` — exactly one of `text` /
+`blob` is present per standard §11.4 / §12.2.
+
+```typescript
+import { readFileSync } from 'node:fs';
+import { IResourceData } from 'fa-mcp-sdk';
+
+export const customResources: IResourceData[] = [
+  // Raw bytes — the SDK base64-encodes the Buffer for you:
+  { uri: 'custom://logo.png', name: 'Logo', description: 'Brand logo',
+    mimeType: 'image/png', content: { blob: readFileSync('assets/logo.png') } },
+
+  // Already-base64 string — pass it through with base64: true:
+  { uri: 'custom://icon.png', name: 'Icon', description: 'App icon',
+    mimeType: 'image/png', content: { blob: PNG_BASE64, base64: true } },
+
+  // A function may return binary content too (sync or async):
+  { uri: 'custom://report.pdf', name: 'Report', description: 'Generated PDF',
+    mimeType: 'application/pdf', content: async () => ({ blob: await buildPdf() }) },
+];
+```
+
+`{ blob: string }` is assumed to be base64 unless you set `base64: false` (then the SDK encodes the
+string's raw bytes). Clients decode `contents[0].blob` from base64 to recover the original file.
+
 ### Dynamic Resources (Function)
 
 For dynamic resource lists based on transport type, headers, or user:
@@ -203,3 +277,92 @@ Both prompts and resources support `requireAuth: true`:
 - Requires valid authentication to access
 - Unauthenticated requests get error
 - Works with any configured auth method (JWT, Basic, etc.)
+
+## Optional MAY capabilities — templates & subscribe (standard §11.5)
+
+Disabled by default. Opt-in via `config/default.yaml`:
+
+```yaml
+mcp:
+  resources:
+    subscribeEnabled: false   # MAY §11.5 — turn on only when resources change at runtime
+    templatesEnabled: false   # MAY §11.5 — turn on when you publish customResourceTemplates
+```
+
+### `resources/templates/list`
+
+When `templatesEnabled: true`, register `customResourceTemplates` on `McpServerData`:
+
+```typescript
+import { IResourceTemplateInfo, McpServerData } from 'fa-mcp-sdk';
+
+const customResourceTemplates: IResourceTemplateInfo[] = [
+  {
+    uriTemplate: 'issue://{key}',                         // RFC 6570
+    name: 'jira-issue',
+    title: 'Jira issue by key',
+    description: 'Single Jira issue addressable by ticket key.',
+    mimeType: 'application/json',
+  },
+];
+
+const serverData: McpServerData = { ..., customResourceTemplates };
+```
+
+If you do not register any templates the server still answers `resources/templates/list`
+with an empty array — clients can probe the capability safely.
+
+### `resources/subscribe` + change notifications
+
+When `subscribeEnabled: true`, the server advertises `subscribe` and `listChanged` in its
+`resources` capability. To notify subscribers when content changes call
+`notifyResourceUpdated(server, uri)`:
+
+```typescript
+import { notifyResourceUpdated } from 'fa-mcp-sdk';
+
+// Each HTTP session owns its own Server instance — track the server reference at the
+// point where you have it (e.g. inside a custom-resources content function).
+await notifyResourceUpdated(server, 'project://version');
+```
+
+The helper emits `notifications/resources/updated` only to clients that previously called
+`resources/subscribe` for the given URI on that `Server`.
+
+## Optional MAY capability — argument completion (standard §8.2)
+
+`completion/complete` lets a client ask the server to suggest values for a prompt or resource
+argument (for example, the valid project ids for a `project` argument). Disabled by default; the
+capability is advertised only when **both** the config flag is on **and** a `completionProvider`
+is supplied on `McpServerData` — otherwise `completion/complete` returns `-32601`.
+
+```yaml
+mcp:
+  completions:
+    enabled: true   # MAY §8.2 — also requires a completionProvider (see below)
+```
+
+```typescript
+import { McpServerData } from 'fa-mcp-sdk';
+
+const completionProvider: McpServerData['completionProvider'] = async ({ ref, argument }) => {
+  // ref: { type: 'ref/prompt' | 'ref/resource'; name?; uri? }
+  // argument: { name; value }  — value is what the user has typed so far
+  if (ref.type === 'ref/prompt' && argument.name === 'project') {
+    const all = await listProjectIds();
+    return all.filter((id) => id.startsWith(argument.value));
+  }
+  return [];
+};
+
+const serverData: McpServerData = { ..., completionProvider };
+```
+
+The SDK caps the response at 100 values and sets `completion.hasMore` / `completion.total`
+accordingly.
+
+## Pagination (standard §8.4)
+
+`prompts/list` and `resources/list` use the same cursor-based pagination as `tools/list`:
+opaque base64(offset), stable sort by `name` / `uri`. The page size comes from
+`mcp.pagination.pageSize` (default 100). See [03-configuration → "Pagination"](./03-configuration.md#pagination).

package/cli-template/FA-MCP-SDK-DOC/03-configuration.md

@@ -113,9 +113,46 @@ mcp:
   rateLimit:
     maxRequests: 100
     windowMs: 60000
+    # Standard §14 — 'subject' counts per JWT `sub`/`user` with IP fallback; 'ip' = legacy.
+    scope: subject
+    # Max in-flight tools/call per subject. Excess → -32003 / HTTP 429 + Retry-After.
+    maxConcurrentPerSubject: 16
+  # Hard ceilings enforced by the HTTP transport (standard §14). Concrete servers MAY raise
+  # or lower these per-environment without patching the SDK.
+  limits:
+    # Max accepted JSON / urlencoded request body, bytes. Above the limit:
+    # JSON-RPC code -32005, HTTP 413 Payload Too Large.
+    maxPayloadBytes: 1048576       # 1 MiB
+    # Max serialized tool result, bytes. Above the limit, the SDK truncates the payload
+    # and marks `structuredContent.truncated: true` + appends "…[truncated]" to text content.
+    maxToolResultBytes: 10485760   # 10 MiB
+    # Per-tool execution timeout, milliseconds. Above the limit:
+    # JSON-RPC code -32004, HTTP 504 Gateway Timeout.
+    toolTimeoutMs: 30000           # 30 seconds
   tools:
     answerAs: text   # text | structuredContent
     hideAnnotations: false  # true — strip `annotations` from tool listings
+  # Standard §8.4 — server-side pagination for tools/list, prompts/list, resources/list.
+  pagination:
+    pageSize: 100                # items per page (cursor is opaque base64(offset))
+  # Standard §11.5 — optional MAY resource capabilities. Off by default.
+  resources:
+    subscribeEnabled: false      # advertise `subscribe` + `listChanged`; emit notifications/resources/updated
+    templatesEnabled: false      # advertise + serve resources/templates/list
+  # Standard §8.7 (MAY) — task-augmented execution (long-running / pollable tool calls). Off by
+  # default. When enabled, advertises the `tasks` capability and serves tasks/list|get|result|cancel.
+  # Long-running tools opt in per-tool via `execution.taskSupport`. Default store is in-memory only.
+  tasks:
+    enabled: false               # advertise `tasks` capability and accept the lifecycle methods
+    defaultTtlMs: 3600000        # finished-task retention from creation (clamped to [minTtlMs, maxTtlMs])
+    minTtlMs: 0                  # lower bound a client-requested ttl is clamped to
+    maxTtlMs: 86400000           # hard retention ceiling (24 h)
+    pollIntervalMs: 1000         # suggested client poll interval, surfaced in every task object
+    maxTasks: 1000               # retained tasks cap; oldest finished evicted first
+  # Standard §6 (MAY) — Streamable HTTP SSE resumability via Last-Event-ID. Off by default.
+  sse:
+    resumability: false          # wire in-memory EventStore into the transport for replay on reconnect
+    maxStoredEvents: 1000        # ring-buffer size: recent events retained per process for replay
 
 swagger:
   servers:
@@ -135,10 +172,21 @@ uiColor:
   primary: '#0f65dc'
 
 webServer:
-  host: '0.0.0.0'
+  # Bind address. Default: '127.0.0.1' — loopback only (safer default, standard §6).
+  # Set to '0.0.0.0' explicitly when running inside a container / behind a reverse proxy.
+  host: '127.0.0.1'
   port: {{port}}
-  # array of hosts that CORS skips
-  originHosts: ['localhost', '0.0.0.0']
+  # Array of hosts whose `Origin` header bypasses the CORS guard.
+  # CORS now actively rejects unlisted origins with HTTP 403 + JSON-RPC error.
+  # In production an empty list aborts startup.
+  originHosts: ['localhost']
+  # Express `trust proxy`. Set true | 'loopback' | <number> when behind an HTTPS reverse
+  # proxy so /.well-known/openid-configuration derives `issuer` from X-Forwarded-* headers.
+  trustProxy: false
+  # Standard §7.1 — secrets in URL forbidden. POST /ct with JSON body is the only safe form;
+  # GET /ct?t=<token> is disabled by default. Opt-in via allowQueryToken=true (non-prod only).
+  tokenCheck:
+    allowQueryToken: false
   # Authentication is configured here only when accessing the MCP server
   # Authentication in services that enable tools, resources, and prompts
   # is implemented more deeply. To do this, you need to use the information passed in HTTP headers
@@ -156,17 +204,15 @@ webServer:
     permanentServerTokens: [ ] # Add your server tokens here: ['token1', 'token2']
 
     # ========================================================================
-    # JWT TOKEN — standard signed JWT (HS256)
-    # Tokens issued by this SDK are standard 3-segment JWTs `header.payload.signature`.
-    # The verifier also temporarily accepts pre-migration legacy tokens
-    # (`<expire_ms>.<hex>` AES-256-CTR format) for backward compatibility.
-    # CPU cost: Medium - signature verification + JSON parsing
-    #
-    # To enable this authentication, you need to set auth.enabled = true and set
-    # encryptKey to at least 8 characters (used as the HS256 signing secret).
+    # JWT TOKEN — four operating modes (since SDK 0.7.0)
+    # - legacyAesCtr (default) — HS256 + AES-CTR fallback. 0.6.x parity.
+    # - embedded               — ES256/RS256 with built-in IdP. Dev / demo.
+    # - localKey               — ES256/RS256 verify with public key on disk.
+    # - remoteJwks             — verify against external IdP's JWKS endpoint.
     # ========================================================================
     jwtToken:
-      # HS256 signing secret used to sign/verify tokens for this MCP (minimum 8 chars)
+      mode: legacyAesCtr   # see above
+      # HS256 signing secret used ONLY by legacyAesCtr mode (minimum 8 chars)
       encryptKey: '***'
       # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
       checkMCPName: true
@@ -174,8 +220,22 @@ webServer:
       # the client IP will be checked against the allowed list in the token
       isCheckIP: false
       # Optional JWT `iss` claim. When non-empty, the generator stamps it and the verifier requires it.
+      # legacyAesCtr only — in non-legacy modes use expectedIssuer below.
       issuer: ''
 
+      # -------- Modes embedded / localKey / remoteJwks --------
+      algorithm: ES256             # ES256 | RS256
+      keyStoragePath: './keys'     # embedded: autogenerated keypair (private.pem + public.pem)
+      publicKeyPath: ''            # localKey: PEM public key path
+      privateKeyPath: ''           # localKey: optional — enables local issuance
+      jwksUri: ''                  # remoteJwks: external JWKS endpoint
+      expectedIssuer: ''           # required for embedded/localKey/remoteJwks (standard §7.2)
+      expectedAudience: ''         # defaults to appConfig.name
+      jwksCacheTtl: 600            # JWKS cache, seconds
+      jwksCooldown: 30             # min interval between repeat fetches when kid missing
+      clockSkew: 30                # allowed exp/nbf drift, seconds (max enforced: 60)
+      defaultTtl: 1800             # default TTL for /oauth/token-issued tokens
+
     # ========================================================================
     # Basic Authentication - Base64 encoded username:password
     # CPU cost: Medium - Base64 decoding + string comparison
@@ -387,3 +447,101 @@ db:
         password: <password>
         usedExtensions: []          # e.g. [pgvector]
 ```
+
+
+## Pagination (`mcp.pagination`)
+
+Standard §8.4 — server-side pagination for `tools/list`, `prompts/list`, and
+`resources/list`. The SDK sorts items stably by `name` / `uri`, slices the list, and
+returns `nextCursor` (opaque base64 of the next offset) when more entries follow.
+
+| Key | Default | Notes |
+|-----|---------|-------|
+| `mcp.pagination.pageSize` | `100` | Items per page; lower this for low-context clients (e.g. terminal MCP clients) or raise it for power users. |
+
+Override per environment via `MCP_PAGINATION_PAGE_SIZE`. Invalid cursors return JSON-RPC
+`-32602` with `error.data.field: 'cursor'`.
+
+```bash
+# clients without pagination support still see the first page — fully spec-compliant
+curl -s ... -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# clients that opt in
+curl -s ... -d '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"cursor":"NTA="}}'
+```
+
+## Resource MAY capabilities (`mcp.resources`)
+
+Standard §11.5 — opt-in templates and subscriptions. Defaults keep the server in the
+"static resources only" mode that low-context clients expect.
+
+| Key | Default | Notes |
+|-----|---------|-------|
+| `mcp.resources.subscribeEnabled` | `false` | Advertise `subscribe` + `listChanged` and register `resources/subscribe`. Project code emits change events via `notifyResourceUpdated(server, uri)`. |
+| `mcp.resources.templatesEnabled` | `false` | Advertise + serve `resources/templates/list`. Templates come from `McpServerData.customResourceTemplates`. |
+
+See [02-2-prompts-and-resources → "Optional MAY capabilities"](./02-2-prompts-and-resources.md#optional-may-capabilities-templates--subscribe-standard-115)
+for end-to-end examples.
+
+## SSE stream resumability (`mcp.sse`)
+
+Standard §6 (MAY) — opt-in replay of missed Streamable HTTP SSE events after a reconnect. Off by
+default; when off the transport behaves exactly as before. Only relevant for the HTTP transport.
+
+| Key | Default | Notes |
+|-----|---------|-------|
+| `mcp.sse.resumability` | `false` | When `true`, an in-memory `InMemoryEventStore` is wired into the Streamable HTTP transport. A client reconnecting to `GET /mcp` with a `Last-Event-ID` header replays the events it missed. Env `MCP_SSE_RESUMABILITY`. |
+| `mcp.sse.maxStoredEvents` | `1000` | Ring-buffer size — how many recent events are retained per process for replay. Env `MCP_SSE_MAX_STORED_EVENTS`. |
+
+The store is a per-process ring buffer: it does not survive a restart and is not shared across
+instances. For multi-replica deployments either pin reconnects to the same instance (sticky sessions
+by `Mcp-Session-Id`) or implement a shared `EventStore`. Events evicted past `maxStoredEvents` are not
+replayed — the client simply resumes from the current moment, without error.
+
+## HTTP Transport Hardening (`mcp.limits`)
+
+Standard §14 mandates explicit ceilings on request body, tool result and tool execution time. The
+SDK enforces all three from `mcp.limits` — see the snippet under "config/default.yaml" above.
+
+| Key | Default | What happens above the limit |
+|-----|---------|------------------------------|
+| `mcp.limits.maxPayloadBytes` | 1 MiB | JSON-RPC `-32005` + HTTP **413 Payload Too Large**. The Express `entity.too.large` error is translated automatically — clients never see the default HTML error page. |
+| `mcp.limits.maxToolResultBytes` | 10 MiB | Response is truncated. `structuredContent.truncated: true` is set on structured payloads; `…[truncated]` marker is appended to oversized text content. Standard §12.2. |
+| `mcp.limits.toolTimeoutMs` | 30 000 ms | JSON-RPC `-32004` + HTTP **504 Gateway Timeout** on `/mcp`. The pending tool promise is left running (Node can't synchronously abort user code); your tool SHOULD also self-cancel if it watches the elapsed time. |
+
+Override per-environment in `config/{development,production,local}.yaml` or via env vars
+(`MCP_LIMITS_MAX_PAYLOAD_BYTES`, `MCP_LIMITS_MAX_TOOL_RESULT_BYTES`, `MCP_LIMITS_TOOL_TIMEOUT_MS`).
+
+## Health, Readiness, CORS
+
+| Endpoint / Setting | Behaviour | Standard |
+|--------------------|-----------|----------|
+| `GET /health` | Returns `{ status, version, uptime, details }`. HTTP **503** when `status === 'unhealthy'`, **200** otherwise. | §16.1 |
+| `GET /ready` | No auth. Returns `{ status, checks: { db, cache, jwks } }`. Each check is `'ok' \| 'error' \| 'skipped'` — never leaks credentials or connection strings. HTTP **503** when any check fails, **200** when all green. | §16.2 / §16.3 |
+| `webServer.host` | Default `'127.0.0.1'` (loopback). Containers / k8s pods / public-facing deployments MUST set `'0.0.0.0'` explicitly. | §6 |
+| `webServer.originHosts` | Empty list in production aborts `initMcpServer()`. Unlisted `Origin` headers receive HTTP **403** + JSON-RPC error (no longer silently allowed). | §6 |
+
+## MCP-Specific JSON-RPC Error Codes (Appendix B)
+
+| Code | Class | HTTP | When |
+|------|-------|------|------|
+| `-32002` | `ResourceNotFoundError` | 404 | Session / resource not found (legacy SSE `/messages`, missing JWKS key, etc.) |
+| `-32003` | `RateLimitedError` | 429 | Per-client rate limit exceeded. Response carries the `Retry-After` HTTP header AND `error.data.retryAfter` (seconds). |
+| `-32004` | `TimeoutError` | 504 | Tool execution exceeded `mcp.limits.toolTimeoutMs`. |
+| `-32005` | `PayloadTooLargeError` | 413 | Request body exceeded `mcp.limits.maxPayloadBytes`. |
+
+Import the classes (and the `MCP_ERROR_CODES` map) from the SDK root:
+
+```typescript
+import {
+  PayloadTooLargeError, TimeoutError, RateLimitedError, ResourceNotFoundError,
+  MCP_ERROR_CODES,
+  createJsonRpcErrorResponse,    // accepts (err, requestId?, extraData?)
+  IMcpErrorData,                 // { requestId?, field?, reason?, retryAfter?, [k]: unknown }
+} from 'fa-mcp-sdk';
+```
+
+All four extend `BaseMcpError`. The `createJsonRpcErrorResponse` helper emits the canonical
+`error.data` shape from Appendix B.3 — `{ requestId?, field?, reason?, retryAfter?, … }`.
+Stack traces and internal paths are NEVER included in `error.data` (standard §13.3).
+

package/cli-template/FA-MCP-SDK-DOC/04-authentication.md

@@ -12,16 +12,83 @@ interface AuthResult {
   username?: string;
   isTokenDecrypted?: boolean;
   payload?: any;
+  /**
+   * Standard §7.4 — authenticated but not authorized. Triggers HTTP 403
+   * (NO WWW-Authenticate challenge). Set by custom validators or scope checks.
+   */
+  forbidden?: boolean;
 }
 ```
 
+## JWT Modes (since SDK 0.7.0)
+
+`webServer.auth.jwtToken.mode` selects the JWT engine:
+
+| Mode | Algorithm | Issues tokens | Verifies tokens | Discovery | Use case |
+|------|-----------|---------------|-----------------|-----------|----------|
+| `legacyAesCtr` (default) | HS256 + legacy AES-CTR | yes (HS256) | yes | — | Backward-compatible / 0.6.x parity |
+| `embedded` | ES256 / RS256 | yes (autogen keys) | yes | full OIDC + JWKS + `/oauth/token` | Dev / demo |
+| `localKey` | ES256 / RS256 | when `privateKeyPath` set | yes | OIDC + JWKS | Isolated server with PEM keys |
+| `remoteJwks` | ES256 / RS256 | NO (`501`) | yes (remote JWKS) | protected-resource only | Corporate IdP (Keycloak, Okta, Azure AD, …) |
+
+Pre-flight checks (`init-mcp-server.ts`) reject misconfigured non-legacy modes at start:
+
+- `remoteJwks` without `jwksUri` → throws
+- `localKey` without `publicKeyPath` → throws
+- non-legacy without `expectedIssuer` → throws (standard §7.2)
+- `clockSkew > 60s` → throws (standard Прил. A.1)
+- `production` + `legacyAesCtr` + `auth.enabled=true` → warn (asymmetric required by standard)
+
+```yaml
+# config/local.yaml — corporate IdP
+webServer:
+  trustProxy: true   # behind HTTPS reverse proxy
+  auth:
+    enabled: true
+    jwtToken:
+      mode: remoteJwks
+      jwksUri: 'https://idp.corp/.well-known/jwks.json'
+      expectedIssuer: 'https://idp.corp'
+      expectedAudience: '${SERVICE_NAME}'
+      jwksCacheTtl: 600
+      jwksCooldown: 30
+      clockSkew: 30
+```
+
+Discovery endpoints mounted automatically when `mode != 'legacyAesCtr'`:
+
+- `GET /.well-known/oauth-protected-resource` (any non-legacy)
+- `GET /.well-known/openid-configuration` (`embedded` / `localKey`)
+- `GET /.well-known/jwks.json` (`embedded` / `localKey`)
+- `POST /oauth/token` (`embedded` + `localKey` with private key, `grant_type=password`)
+
+On every 401 the server sets:
+
+```
+WWW-Authenticate: Bearer realm="<appConfig.name>",
+                  resource_metadata="<base>/.well-known/oauth-protected-resource"
+```
+
+If the token was decoded but rejected (expired, bad scope), the header additionally carries
+`error="invalid_token", error_description="…"` per RFC 6750.
+
 ## Token Operations
 
 ```typescript
-import { generateToken } from 'fa-mcp-sdk';
+import { generateToken, checkJwtToken } from 'fa-mcp-sdk';
+
+// Since 0.7.0 — generateToken / checkJwtToken are async (dispatch by jwtToken.mode).
+const token = await generateToken('john_doe', 3600, { role: 'admin' }); // 1 hour
+const r = await checkJwtToken({ token });
+```
+
+Synchronous fallbacks (legacy mode only — never throw on `mode = legacyAesCtr`):
+
+```typescript
+import { generateTokenLegacy, checkJwtTokenLegacy } from 'fa-mcp-sdk';
 
-// Generate JWT (liveTimeSec = seconds until expiry)
-const token = generateToken('john_doe', 3600, { role: 'admin' }); // 1 hour
+const token = generateTokenLegacy('john_doe', 3600, { role: 'admin' });
+const r = checkJwtTokenLegacy({ token });
 ```
 
 ## Test Authentication
@@ -29,8 +96,9 @@ const token = generateToken('john_doe', 3600, { role: 'admin' }); // 1 hour
 ```typescript
 import { getAuthHeadersForTests, McpHttpClient, appConfig } from 'fa-mcp-sdk';
 
-// Auto-generates auth headers based on config (permanent → basic → JWT priority)
-const headers = getAuthHeadersForTests();
+// Since 0.7.0 — getAuthHeadersForTests is async. Uses canLocallyIssueJwt() so JWT-based
+// headers work in every mode that can sign locally (legacy / embedded / localKey).
+const headers = await getAuthHeadersForTests();
 
 // Usage
 const response = await fetch(`http://localhost:${appConfig.webServer.port}/mcp`, {
@@ -41,7 +109,62 @@ const response = await fetch(`http://localhost:${appConfig.webServer.port}/mcp`,
 
 // With test client
 const client = new McpHttpClient('http://localhost:3000');
-const result = await client.callTool('tool', args, getAuthHeadersForTests());
+const result = await client.callTool('tool', args, await getAuthHeadersForTests());
+```
+
+## Scope Enforcement (since SDK 0.7.0)
+
+Standard §7.5 — protect specific tools / prompts / resources with `requiredScopes`. The auth
+middleware checks the token's `scope` claim (space-separated) against the declared list and
+returns HTTP 403 (or JSON-RPC `-32004` for tools) when scopes are missing.
+
+```typescript
+// Resource with required scope
+{
+  uri: 'admin://users',
+  name: 'users',
+  description: 'Admin user list',
+  mimeType: 'application/json',
+  requireAuth: true,
+  requiredScopes: ['mcp:admin'],
+  content: async () => ({ ... }),
+}
+
+// Prompt with required scope
+{
+  name: 'admin_brief',
+  description: 'Privileged brief',
+  arguments: [],
+  content: '…',
+  requiredScopes: ['mcp:admin'],
+}
+
+// Tool with required scope (via _meta — SDK Tool type has no native scope field)
+{
+  name: 'delete_user',
+  description: 'Delete a user account',
+  inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  _meta: { requiredScopes: ['mcp:admin'] },
+}
+```
+
+A token issued via `POST /oauth/token` with `scope=mcp:admin` (or any IdP token carrying that
+scope) passes; everything else hits 403. The full server-side scope map is published via the
+built-in `use://auth` resource — clients can introspect it programmatically.
+
+## Forbidden vs Unauthorized
+
+Custom validators can now signal 403 explicitly via `AuthResult.forbidden`:
+
+```typescript
+const validator: CustomAuthValidator = async (req) => {
+  const token = req.headers['x-api-key'];
+  if (!token) return { success: false, error: 'No API key' };               // → 401
+  if (await tokenIsRevoked(token)) {
+    return { success: false, forbidden: true, error: 'Token revoked' };     // → 403, no challenge
+  }
+  return { success: true, authType: 'custom' };
+};
 ```
 
 ## Admin Panel Authentication
@@ -296,12 +419,31 @@ curl -H "Authorization: Basic $(echo -n 'admin:password' | base64)" http://local
 curl -H "X-API-Key: custom-key" http://localhost:3000/mcp
 ```
 
+## Token Check Endpoint (`/ct`)
+
+Standard §7.1 forbids secrets in URL query strings. Since SDK 0.7.0 `GET /ct?t=<token>` is
+disabled by default and returns HTTP 405. Use `POST /ct` with JSON body instead:
+
+```bash
+curl -X POST http://localhost:3000/ct \
+  -H "Content-Type: application/json" \
+  -d '{"t": "<your-token>"}'
+```
+
+Opt-in for the legacy form (non-production only — flag is ignored when `NODE_ENV=production`):
+
+```yaml
+webServer:
+  tokenCheck:
+    allowQueryToken: true
+```
+
 ## CLI Token Generator
 
 Generate JWT tokens from the command line without starting the server:
 
 ```bash
-node scripts/generate-jwt.js -u <username> -ttl <duration> [-s <service>] [-p <params>]
+node scripts/generate-jwt.js -u <username> -ttl <duration> [-s <service>] [-p <params>] [--key <path>]
 ```
 
 | Option | ENV | Description |
@@ -310,8 +452,16 @@ node scripts/generate-jwt.js -u <username> -ttl <duration> [-s <service>] [-p <p
 | `-ttl` | `JWT_TTL` | Token lifetime: `<N>s` \| `<N>m` \| `<N>d` \| `<N>y` (required) |
 | `-s`, `--service-name` | `JWT_PAYLOAD_SERVICE_NAME` | Service name (optional) |
 | `-p`, `--params` | `JWT_PAYLOAD_PARAMS` | Extra payload `key=value;key=value` (optional) |
+| `--key`, `--private-key` | — | Override private key path (only for embedded / localKey modes) |
+
+Behaviour by `webServer.auth.jwtToken.mode`:
 
-The HS256 signing secret is read from config `webServer.auth.jwtToken.encryptKey` (via `config/local.yaml` or ENV `WS_TOKEN_ENCRYPT_KEY`). Generated tokens are standard 3-segment JWTs.
+| Mode | What the script does |
+|------|----------------------|
+| `legacyAesCtr` | HS256 with `encryptKey` (legacy). |
+| `embedded` | ES256/RS256 with keys from `keyStoragePath/private.pem`. |
+| `localKey` | ES256/RS256 with `privateKeyPath` (must be configured or passed via `--key`). |
+| `remoteJwks` | Exits with error — tokens must be obtained from the external IdP. |
 
 **Examples:**