@frontmcp/protocol 1.5.7 → 1.6.1

package/README.md

@@ -0,0 +1,71 @@
+# @frontmcp/protocol
+
+The single boundary between FrontMCP and the upstream
+[`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk).
+
+[![NPM](https://img.shields.io/npm/v/@frontmcp/protocol.svg)](https://www.npmjs.com/package/@frontmcp/protocol)
+
+> **Internal package.** It is published so the other `@frontmcp/*` packages can
+> resolve it — you should not import it from application code. Import MCP types
+> from [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk) instead,
+> and use `McpClient` from `@frontmcp/testing` for a raw client in tests.
+
+## Why it exists
+
+`libs/protocol/src/types.ts` is the **only** file in the whole monorepo that
+transitively imports `@modelcontextprotocol/sdk`. Everything else — SDK,
+adapters, plugins, auth, tests — imports from `@frontmcp/protocol`.
+
+That indirection means swapping, pinning, or dropping the upstream package is a
+one-file change instead of a repo-wide refactor. The
+[`@nx/dependency-checks`](https://nx.dev) lint rule enforces it: adding a direct
+upstream import anywhere else fails the build.
+
+✅ Route through the boundary:
+
+<!-- prettier-ignore -->
+```ts
+import { CallToolRequestSchema, McpError, type Tool } from '@frontmcp/protocol';
+```
+
+❌ Never import the upstream package directly — that locks every call site to it:
+
+<!-- prettier-ignore -->
+```ts
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+```
+
+If a type you need is not reachable from `@frontmcp/protocol`, re-export it from
+`libs/protocol/src/types.ts` rather than reaching around the boundary.
+
+## What it exports
+
+| Area                | Contents                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| Protocol types      | Requests, results, notifications, schemas, `McpError`, capabilities                      |
+| Protocol 2026-07-28 | Types the upstream SDK does not ship yet — see below                                     |
+| Server              | `McpServer`, `StreamableHTTPServerTransport`, `WebStandardStreamableHTTPServerTransport` |
+| Client              | `Client`, `StreamableHTTPClientTransport`, `SSEClientTransport`                          |
+| Transports          | stdio (Node + browser), in-memory                                                        |
+| Auth types          | `AuthInfo` and friends                                                                   |
+
+Node and browser/worker variants are selected automatically through package
+[subpath imports](https://nodejs.org/api/packages.html#subpath-imports), so the
+same import works in every runtime FrontMCP targets.
+
+## Protocol 2026-07-28
+
+The upstream SDK tops out at `2025-11-25`. Revision `2026-07-28` is therefore
+defined here — `MCP_20260728_META`, `MCP_20260728_ERROR_CODES`, `CacheableResult`,
+`DiscoverResult`, `InputRequiredResult`, `SubscriptionFilter`, and the rest.
+
+Everything is **additive**: the 2025-and-earlier types are untouched, because a
+FrontMCP server serves both eras on the same endpoint. When upstream catches up,
+`types-20260728.ts` is the only file that has to change.
+
+See the [protocol versions guide](https://docs.agentfront.dev/frontmcp/fundamentals/protocol-versions)
+for what the revision changed and how FrontMCP selects one per request.
+
+## License
+
+Apache-2.0

package/esm/index.mjs

@@ -23,13 +23,22 @@ __export(index_exports, {
   HttpServerResponse: () => HttpServerResponse,
   InMemoryTransport: () => InMemoryTransport,
   IncomingMessage: () => IncomingMessage,
+  MCP_20260728_ADDED_METHODS: () => MCP_20260728_ADDED_METHODS,
+  MCP_20260728_ERROR_CODES: () => MCP_20260728_ERROR_CODES,
+  MCP_20260728_META: () => MCP_20260728_META,
+  MCP_20260728_REMOVED_METHODS: () => MCP_20260728_REMOVED_METHODS,
+  MCP_20260728_RETIRED_ERROR_CODES: () => MCP_20260728_RETIRED_ERROR_CODES,
   McpServer: () => Server,
+  PROTOCOL_2026_07_28: () => PROTOCOL_2026_07_28,
   SSEClientTransport: () => SSEClientTransport,
+  SUBSCRIPTIONS_ACKNOWLEDGED_METHOD: () => SUBSCRIPTIONS_ACKNOWLEDGED_METHOD,
   StdioClientTransport: () => StdioClientTransport,
   StdioServerTransport: () => StdioServerTransport,
   StreamableHTTPClientTransport: () => StreamableHTTPClientTransport,
   StreamableHTTPServerTransport: () => StreamableHTTPServerTransport,
-  WebStandardStreamableHTTPServerTransport: () => WebStandardStreamableHTTPServerTransport
+  WebStandardStreamableHTTPServerTransport: () => WebStandardStreamableHTTPServerTransport,
+  isProtocol20260728: () => isProtocol20260728,
+  readDeclaredProtocolVersion: () => readDeclaredProtocolVersion
 });
 
 // libs/protocol/src/types.ts
@@ -40,6 +49,53 @@ import * as types_star from "@modelcontextprotocol/sdk/types.js";
 // libs/protocol/src/index.ts
 __reExport(index_exports, types_exports);
 
+// libs/protocol/src/types-20260728.ts
+var PROTOCOL_2026_07_28 = "2026-07-28";
+var MCP_20260728_META = {
+  /** Request: protocol version; MUST match the `MCP-Protocol-Version` header. */
+  protocolVersion: "io.modelcontextprotocol/protocolVersion",
+  /** Request: self-reported client identity. */
+  clientInfo: "io.modelcontextprotocol/clientInfo",
+  /** Request: capabilities for THIS request only — never inferred from prior ones. */
+  clientCapabilities: "io.modelcontextprotocol/clientCapabilities",
+  /** Request: opt-in log level; absent means "send me no `notifications/message`". */
+  logLevel: "io.modelcontextprotocol/logLevel",
+  /** Result: self-reported server identity. */
+  serverInfo: "io.modelcontextprotocol/serverInfo",
+  /** Notification/result: id of the `subscriptions/listen` stream it belongs to. */
+  subscriptionId: "io.modelcontextprotocol/subscriptionId"
+};
+var MCP_20260728_ERROR_CODES = {
+  /** Headers disagree with the body, or a required header is missing/malformed. */
+  headerMismatch: -32020,
+  /** The request needs a client capability that was not declared. */
+  missingRequiredClientCapability: -32021,
+  /** The requested protocol version is not supported by this server. */
+  unsupportedProtocolVersion: -32022
+};
+var MCP_20260728_RETIRED_ERROR_CODES = [-32002, -32042];
+var MCP_20260728_REMOVED_METHODS = [
+  "initialize",
+  "notifications/initialized",
+  "ping",
+  "logging/setLevel",
+  "notifications/roots/list_changed",
+  "resources/subscribe",
+  "resources/unsubscribe",
+  "tasks/list",
+  "tasks/result"
+];
+var MCP_20260728_ADDED_METHODS = ["server/discover", "subscriptions/listen"];
+var SUBSCRIPTIONS_ACKNOWLEDGED_METHOD = "notifications/subscriptions/acknowledged";
+function isProtocol20260728(version) {
+  return version === PROTOCOL_2026_07_28;
+}
+function readDeclaredProtocolVersion(body) {
+  const params = body?.params;
+  const declared = params?._meta?.[MCP_20260728_META.protocolVersion];
+  return typeof declared === "string" ? declared : void 0;
+}
+
 // libs/protocol/src/client.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -66,13 +122,22 @@ export {
   HttpServerResponse,
   InMemoryTransport,
   IncomingMessage,
+  MCP_20260728_ADDED_METHODS,
+  MCP_20260728_ERROR_CODES,
+  MCP_20260728_META,
+  MCP_20260728_REMOVED_METHODS,
+  MCP_20260728_RETIRED_ERROR_CODES,
   Server as McpServer,
+  PROTOCOL_2026_07_28,
   SSEClientTransport,
+  SUBSCRIPTIONS_ACKNOWLEDGED_METHOD,
   StdioClientTransport,
   StdioServerTransport,
   StreamableHTTPClientTransport,
   StreamableHTTPServerTransport,
-  WebStandardStreamableHTTPServerTransport
+  WebStandardStreamableHTTPServerTransport,
+  isProtocol20260728,
+  readDeclaredProtocolVersion
 };
 
 export * from "@modelcontextprotocol/sdk/types.js";

package/index.d.ts

@@ -7,6 +7,7 @@
  * For raw MCP Client in tests, use McpClient from @frontmcp/testing.
  */
 export * from './types';
+export * from './types-20260728';
 export * from './auth-types';
 export * from './shared';
 export * from './client';

package/index.js

@@ -25,13 +25,22 @@ __export(index_exports, {
   HttpServerResponse: () => import_server_types.HttpServerResponse,
   InMemoryTransport: () => import_inMemory.InMemoryTransport,
   IncomingMessage: () => import_server_types.IncomingMessage,
+  MCP_20260728_ADDED_METHODS: () => MCP_20260728_ADDED_METHODS,
+  MCP_20260728_ERROR_CODES: () => MCP_20260728_ERROR_CODES,
+  MCP_20260728_META: () => MCP_20260728_META,
+  MCP_20260728_REMOVED_METHODS: () => MCP_20260728_REMOVED_METHODS,
+  MCP_20260728_RETIRED_ERROR_CODES: () => MCP_20260728_RETIRED_ERROR_CODES,
   McpServer: () => import_mcp_server.Server,
+  PROTOCOL_2026_07_28: () => PROTOCOL_2026_07_28,
   SSEClientTransport: () => import_sse.SSEClientTransport,
+  SUBSCRIPTIONS_ACKNOWLEDGED_METHOD: () => SUBSCRIPTIONS_ACKNOWLEDGED_METHOD,
   StdioClientTransport: () => import_stdio.StdioClientTransport,
   StdioServerTransport: () => import_stdio2.StdioServerTransport,
   StreamableHTTPClientTransport: () => import_streamableHttp.StreamableHTTPClientTransport,
   StreamableHTTPServerTransport: () => import_mcp_streamable_http.StreamableHTTPServerTransport,
-  WebStandardStreamableHTTPServerTransport: () => import_mcp_streamable_http.WebStandardStreamableHTTPServerTransport
+  WebStandardStreamableHTTPServerTransport: () => import_mcp_streamable_http.WebStandardStreamableHTTPServerTransport,
+  isProtocol20260728: () => isProtocol20260728,
+  readDeclaredProtocolVersion: () => readDeclaredProtocolVersion
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -42,6 +51,53 @@ __reExport(types_exports, require("@modelcontextprotocol/sdk/types.js"));
 // libs/protocol/src/index.ts
 __reExport(index_exports, types_exports, module.exports);
 
+// libs/protocol/src/types-20260728.ts
+var PROTOCOL_2026_07_28 = "2026-07-28";
+var MCP_20260728_META = {
+  /** Request: protocol version; MUST match the `MCP-Protocol-Version` header. */
+  protocolVersion: "io.modelcontextprotocol/protocolVersion",
+  /** Request: self-reported client identity. */
+  clientInfo: "io.modelcontextprotocol/clientInfo",
+  /** Request: capabilities for THIS request only — never inferred from prior ones. */
+  clientCapabilities: "io.modelcontextprotocol/clientCapabilities",
+  /** Request: opt-in log level; absent means "send me no `notifications/message`". */
+  logLevel: "io.modelcontextprotocol/logLevel",
+  /** Result: self-reported server identity. */
+  serverInfo: "io.modelcontextprotocol/serverInfo",
+  /** Notification/result: id of the `subscriptions/listen` stream it belongs to. */
+  subscriptionId: "io.modelcontextprotocol/subscriptionId"
+};
+var MCP_20260728_ERROR_CODES = {
+  /** Headers disagree with the body, or a required header is missing/malformed. */
+  headerMismatch: -32020,
+  /** The request needs a client capability that was not declared. */
+  missingRequiredClientCapability: -32021,
+  /** The requested protocol version is not supported by this server. */
+  unsupportedProtocolVersion: -32022
+};
+var MCP_20260728_RETIRED_ERROR_CODES = [-32002, -32042];
+var MCP_20260728_REMOVED_METHODS = [
+  "initialize",
+  "notifications/initialized",
+  "ping",
+  "logging/setLevel",
+  "notifications/roots/list_changed",
+  "resources/subscribe",
+  "resources/unsubscribe",
+  "tasks/list",
+  "tasks/result"
+];
+var MCP_20260728_ADDED_METHODS = ["server/discover", "subscriptions/listen"];
+var SUBSCRIPTIONS_ACKNOWLEDGED_METHOD = "notifications/subscriptions/acknowledged";
+function isProtocol20260728(version) {
+  return version === PROTOCOL_2026_07_28;
+}
+function readDeclaredProtocolVersion(body) {
+  const params = body?.params;
+  const declared = params?._meta?.[MCP_20260728_META.protocolVersion];
+  return typeof declared === "string" ? declared : void 0;
+}
+
 // libs/protocol/src/client.ts
 var import_client = require("@modelcontextprotocol/sdk/client/index.js");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
@@ -66,11 +122,20 @@ var import_server_types = require("#server-types");
   HttpServerResponse,
   InMemoryTransport,
   IncomingMessage,
+  MCP_20260728_ADDED_METHODS,
+  MCP_20260728_ERROR_CODES,
+  MCP_20260728_META,
+  MCP_20260728_REMOVED_METHODS,
+  MCP_20260728_RETIRED_ERROR_CODES,
   McpServer,
+  PROTOCOL_2026_07_28,
   SSEClientTransport,
+  SUBSCRIPTIONS_ACKNOWLEDGED_METHOD,
   StdioClientTransport,
   StdioServerTransport,
   StreamableHTTPClientTransport,
   StreamableHTTPServerTransport,
-  WebStandardStreamableHTTPServerTransport
+  WebStandardStreamableHTTPServerTransport,
+  isProtocol20260728,
+  readDeclaredProtocolVersion
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/protocol",
-  "version": "1.5.7",
+  "version": "1.6.1",
   "description": "Centralized MCP protocol types, server, and client re-exports for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",

package/types-20260728.d.ts

@@ -0,0 +1,197 @@
+/**
+ * MCP protocol revision **2026-07-28**.
+ *
+ * The upstream `@modelcontextprotocol/sdk` (1.30.0 at time of writing) only
+ * ships schemas up to `2025-11-25`, so this revision is defined here — inside
+ * the single boundary module that owns protocol types — rather than reached for
+ * from every call site. When upstream catches up, this file is the only place
+ * that has to change.
+ *
+ * Everything here is ADDITIVE. The 2025-and-earlier types re-exported from
+ * `./types` are untouched, because a server must keep serving both eras.
+ *
+ * @see https://modelcontextprotocol.io/specification/2026-07-28/changelog
+ */
+import type { Implementation, LoggingLevel, RequestId } from './types';
+/** The protocol revision this module implements. */
+export declare const PROTOCOL_2026_07_28: "2026-07-28";
+export type Protocol20260728Version = typeof PROTOCOL_2026_07_28;
+/**
+ * Reserved `_meta` keys introduced by 2026-07-28.
+ *
+ * Statelessness means the handshake's payload now rides on every request, so
+ * these keys carry what `initialize` used to negotiate once.
+ */
+export declare const MCP_20260728_META: {
+    /** Request: protocol version; MUST match the `MCP-Protocol-Version` header. */
+    readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
+    /** Request: self-reported client identity. */
+    readonly clientInfo: "io.modelcontextprotocol/clientInfo";
+    /** Request: capabilities for THIS request only — never inferred from prior ones. */
+    readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
+    /** Request: opt-in log level; absent means "send me no `notifications/message`". */
+    readonly logLevel: "io.modelcontextprotocol/logLevel";
+    /** Result: self-reported server identity. */
+    readonly serverInfo: "io.modelcontextprotocol/serverInfo";
+    /** Notification/result: id of the `subscriptions/listen` stream it belongs to. */
+    readonly subscriptionId: "io.modelcontextprotocol/subscriptionId";
+};
+/**
+ * JSON-RPC error codes allocated to the MCP specification.
+ *
+ * 2026-07-28 partitions the server-error range: `-32000`…`-32019` stays
+ * implementation-defined, `-32020`…`-32099` is reserved for the spec. The three
+ * codes below were renumbered into that block from their draft values.
+ */
+export declare const MCP_20260728_ERROR_CODES: {
+    /** Headers disagree with the body, or a required header is missing/malformed. */
+    readonly headerMismatch: -32020;
+    /** The request needs a client capability that was not declared. */
+    readonly missingRequiredClientCapability: -32021;
+    /** The requested protocol version is not supported by this server. */
+    readonly unsupportedProtocolVersion: -32022;
+};
+/**
+ * Codes retired by this revision. Kept as documentation so they are never
+ * reallocated: `-32002` was resource-not-found (now `-32602`) and `-32042` was
+ * URL-elicitation-required (2025-11-25 only).
+ */
+export declare const MCP_20260728_RETIRED_ERROR_CODES: readonly [-32002, -32042];
+/** Methods this revision removed from the core protocol. */
+export declare const MCP_20260728_REMOVED_METHODS: readonly ["initialize", "notifications/initialized", "ping", "logging/setLevel", "notifications/roots/list_changed", "resources/subscribe", "resources/unsubscribe", "tasks/list", "tasks/result"];
+/** Methods this revision introduced. */
+export declare const MCP_20260728_ADDED_METHODS: readonly ["server/discover", "subscriptions/listen"];
+/**
+ * Discriminates a final result from an interim one.
+ *
+ * Left open (`| string`) exactly as the spec does, so a future result type does
+ * not become a parse error.
+ */
+export type ResultType = 'complete' | 'input_required' | (string & {});
+export interface RequestMeta20260728 {
+    progressToken?: string | number;
+    [MCP_20260728_META.protocolVersion]: string;
+    [MCP_20260728_META.clientInfo]?: Implementation;
+    [MCP_20260728_META.clientCapabilities]: ClientCapabilities20260728;
+    [MCP_20260728_META.logLevel]?: LoggingLevel;
+    [key: string]: unknown;
+}
+export interface ResultMeta20260728 {
+    [MCP_20260728_META.serverInfo]?: Implementation;
+    [key: string]: unknown;
+}
+export interface NotificationMeta20260728 {
+    [MCP_20260728_META.subscriptionId]?: RequestId;
+    [key: string]: unknown;
+}
+export interface Result20260728 {
+    _meta?: ResultMeta20260728;
+    resultType: ResultType;
+    [key: string]: unknown;
+}
+/**
+ * A result carrying client-side caching hints.
+ *
+ * REQUIRED on `tools/list`, `prompts/list`, `resources/list`,
+ * `resources/templates/list`, `resources/read`, and `server/discover`.
+ */
+export interface CacheableResult extends Result20260728 {
+    /** Freshness hint in milliseconds; `0` means "always revalidate". */
+    ttlMs: number;
+    /** `public` = safe to share across authorization contexts; `private` = not. */
+    cacheScope: 'public' | 'private';
+}
+export interface ClientCapabilities20260728 {
+    experimental?: Record<string, Record<string, unknown>>;
+    /** @deprecated Deprecated in 2026-07-28 (SEP-2577). */
+    roots?: Record<string, unknown>;
+    /** @deprecated Deprecated in 2026-07-28 (SEP-2577). */
+    sampling?: {
+        context?: Record<string, unknown>;
+        tools?: Record<string, unknown>;
+    };
+    elicitation?: {
+        form?: Record<string, unknown>;
+        url?: Record<string, unknown>;
+    };
+    /** Optional MCP extensions; keys are prefixed identifiers. */
+    extensions?: Record<string, Record<string, unknown>>;
+}
+export interface ServerCapabilities20260728 {
+    experimental?: Record<string, Record<string, unknown>>;
+    /** @deprecated Deprecated in 2026-07-28 (SEP-2577). */
+    logging?: Record<string, unknown>;
+    completions?: Record<string, unknown>;
+    prompts?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        subscribe?: boolean;
+        listChanged?: boolean;
+    };
+    tools?: {
+        listChanged?: boolean;
+    };
+    /** Optional MCP extensions; keys are prefixed identifiers. */
+    extensions?: Record<string, Record<string, unknown>>;
+}
+export interface DiscoverResult extends CacheableResult {
+    /** Versions the client may choose from for subsequent requests. */
+    supportedVersions: string[];
+    capabilities: ServerCapabilities20260728;
+    instructions?: string;
+}
+/**
+ * The notification types a client opts in to. Every type is opt-in: the server
+ * MUST NOT push a type the client did not ask for.
+ */
+export interface SubscriptionFilter {
+    toolsListChanged?: boolean;
+    promptsListChanged?: boolean;
+    resourcesListChanged?: boolean;
+    /** Replaces the removed `resources/subscribe` RPC. */
+    resourceSubscriptions?: string[];
+}
+export interface SubscriptionsListenParams {
+    notifications: SubscriptionFilter;
+    _meta: RequestMeta20260728;
+}
+export interface SubscriptionsAcknowledgedParams {
+    /** The subset of requested types the server actually agreed to honor. */
+    notifications: SubscriptionFilter;
+    _meta?: NotificationMeta20260728;
+}
+export declare const SUBSCRIPTIONS_ACKNOWLEDGED_METHOD: "notifications/subscriptions/acknowledged";
+/**
+ * A server-initiated request embedded in a result rather than sent on the wire.
+ *
+ * 2026-07-28 removed the server→client request direction, so sampling,
+ * elicitation, and roots all travel this way.
+ */
+export interface InputRequest {
+    method: 'elicitation/create' | 'sampling/createMessage' | 'roots/list' | (string & {});
+    params?: Record<string, unknown>;
+}
+export type InputRequests = Record<string, InputRequest>;
+export type InputResponses = Record<string, Record<string, unknown>>;
+/**
+ * The interim result that asks the client for more input.
+ *
+ * At least one of `inputRequests` / `requestState` MUST be present. The client
+ * retries the ORIGINAL request with `inputResponses` and the echoed
+ * `requestState`; it must treat `requestState` as opaque.
+ */
+export interface InputRequiredResult extends Result20260728 {
+    resultType: 'input_required';
+    inputRequests?: InputRequests;
+    requestState?: string;
+}
+/** Params any client request may carry when resuming an MRTR exchange. */
+export interface InputResponseParams {
+    inputResponses?: InputResponses;
+    requestState?: string;
+}
+/** True when `version` is the 2026-07-28 revision. */
+export declare function isProtocol20260728(version: unknown): version is Protocol20260728Version;
+/** Reads the protocol version a request declares in its `_meta`, if any. */
+export declare function readDeclaredProtocolVersion(body: unknown): string | undefined;