Skip to content

Releases

v5.0.0

Choose a tag to compare

@github-actions github-actions released this 11 Nov 09:40
ffc8cb5

Moves to mcp/sdk ~0.10.0: 0.8.x is affected by
GHSA-f4rf-6ghj-mhr6
(the SDK's OAuth middleware endpoints bypassed request body limits), and 0.9
and 0.10 are breaking minors (#81). Composer's security blocking already
refuses to install 0.8.x, so 4.x no longer installs without ignoring the
advisory. Upgrade steps: UPGRADE.md.

Breaking

  • Requires mcp/sdk ~0.10.0. The SDK moved its classes, so applications
    update their imports: Mcp\Server → Mcp\Server\Server,
    Mcp\Capability\* → Mcp\Server\Capability\* (#[McpTool],
    #[McpResource], …), Mcp\Exception\* → Mcp\Server\Exception\*
    (ToolCallException, PromptGetException, ResourceReadException, …),
    Mcp\Server\Stateless\RequestMeta → Mcp\Schema\RequestMeta.
  • result_json defaults to 'compact'. Since 0.10 the SDK itself encodes
    array/object tool results without indentation, so compact is the SDK's
    own output and pretty is now the package's: CompactToolResultFormatter
    (@internal) became ToolResultTextFormatter and mirrors the SDK's
    CallToolHandler again (a null or scalar structured value is carried as its
    JSON text, SEP-2106). Set 'result_json' => 'pretty' to keep the 4.x text.
  • McpServerFactory's compactToolResults defaults to true; it gained the
    optional previousRequestStateKeys, bindRequestState and fiberContext
    arguments.
  • A result decorator that builds a new CallToolResult must pass
    StructuredContent::Absent for a result without structured content: since
    0.10 an explicit null is sent as "structuredContent": null.
  • Testing\McpTester speaks ProtocolVersion::latestHandshake() by default
    (the SDK's MessageInterface::PROTOCOL_VERSION is the stateless 2026-07-28
    since 0.9) and addresses http://localhost/mcp: the SDK now refuses a
    request without an allowed Host.
  • The resolved client id is handed to the SDK as the session principal
    (StreamableHttpTransport::PRINCIPAL_ATTRIBUTE); the SDK answers 404 to a
    session opened before the upgrade, once.
  • request_state.bind is on by default: a requestState minted before the
    upgrade does not verify (a multi round-trip call in flight restarts).
  • Psalm 7 (vimeo/psalm ^7.0, dev only).

Added

  • OAuth 2.1 resource server: OAuth\BearerTokenMiddleware over the SDK's
    AuthorizationMiddleware. Route [BearerTokenMiddleware, McpAction] and
    serve the SDK's ProtectedResourceMetadataHandler at
    /.well-known/oauth-protected-resource/<path>; configured by the new
    oauth params block (resource, authorization servers, issuer, audience,
    algorithms, token type, leeway, scope claim, scopes per request / method /
    tool with a hierarchy, identity, own validator, PSR-6 cache). JWT tokens are
    validated through the issuer's discovery document and JWKS
    (firebase/php-jwt, suggested); the token's principal, client_id or
    subject becomes the client id, so session ownership, visibility, the
    budget and the result cache work unchanged. A token without that claim gets
    401 invalid_token. psr/cache is now required.
  • request_state.previous_keys: keys that still verify a requestState but
    no longer sign one — the signing key rotates without failing calls in
    flight.
  • request_state.bind (default true): a state is tied to its originating
    request (the SDK's OriginatingRequestBinder: method, tool, argument
    digest, OAuth principal) and to the resolved client id, which the SDK binder
    does not know behind SharedSecretMiddleware; a state replayed by another
    client or for other arguments does not verify.
  • notifications.bus 'psr6': the SDK's Psr6NotificationBus over the
    container's CacheItemPoolInterface; mcp:doctor requires the pool then.
  • A container binding of Mcp\Server\Fiber\FiberContextInterface is
    autowired into McpServerFactory and handed to Builder::setFiberContext()
    (e.g. the OpenTelemetry context inside handler fibers).

Fixed

  • ArgumentMasker masks inside \stdClass: SDK 0.10 keeps nested JSON
    objects of tool arguments as objects, and a secret one level down an object
    would have reached a log unmasked. The result-cache key orders object keys
    too, so {"a":1,"b":2} and {"b":2,"a":1} share an entry.
  • GuardedRegistry forwards the SDK's new publishesListChanges().

Internal

  • Mutation testing (composer mutation) now counts code that no test is
    attributed to (--with-uncovered; Infection runs the Unit suite only).
    Overall MSI 82% -> 98% against the unchanged minMsi of 97. New tests
    cover OperationRequestBuilder, OperationResponseDecoder, RequestEra,
    the session-ownership edge cases of McpAction, McpTester pagination
    against a misbehaving peer, McpDoctor failure paths and the bounded
    stream readers; #[Covers] was added where tests already ran the code.
    Two behaviour-neutral source edits: signatures with defaults are laid out
    one parameter per line, and the dry-run flag and the cache-key digest are
    read into a local variable.

v4.1.1

Choose a tag to compare

@github-actions github-actions released this 10 Oct 09:56
b0c1437
  • Stateless SSE streams (subscriptions/listen) are sent frame by frame
    under PHP-FPM (#74). mcp/sdk 0.8.1 writes each frame with flush() only,
    which leaves it in PHP's output_buffering buffer (4096 in both shipped
    php.ini files), so the client got the whole stream when it closed — a
    notification arrived up to subscription_lifetime late. McpAction now
    wraps a text/event-stream body in OutputBufferReleasingStream
    (@internal), which ends PHP's output buffers before the SDK writes.
    Fixed upstream in modelcontextprotocol/php-sdk#520 (not released yet); the
    wrapper goes once the mcp/sdk pin includes it.

v4.1.0

Choose a tag to compare

@github-actions github-actions released this 09 Oct 10:40
2853001
  • Tool-result decorators (#71): Interceptor\ToolResultDecoratorInterface
    gets the formatted CallToolResult of every successful tools/call after
    the whole interceptor chain and returns it with added content (a
    ResourceLink per item, an image) — no re-implementation of result
    formatting or of the per-revision structuredContent rule. Configured by
    the new result_decorators params key (a class not implementing the
    interface fails the build) or McpServerFactory::create(resultDecorators:).
    Decorators run on cache hits too, never see an input_required ask or a
    ToolCallException, and their output is not counted by
    limits.tool_result_bytes. In pretty mode the package builds the result
    the way the SDK does, only when a decorator is configured; without one
    nothing changes.

v4.0.1

Choose a tag to compare

@github-actions github-actions released this 08 Oct 20:40
f58c7e6
  • clientInfo() keeps the name of a client that sends no version (an
    Implementation with an empty version); 4.0.0 returned null, while 3.x
    getClientInfo() still exposed the name (#69).
  • Docs: 3.x is not maintained as a separate line (the 3.x branch announced
    in 4.0.0 was dropped); fixes land in 4.x. llms.txt named the old
    mcp/sdk pin.

v4.0.0

Choose a tag to compare

@github-actions github-actions released this 08 Oct 19:53
dfd1ab1

Serves the MCP revision 2026-07-28 — the stateless era — next to the
handshake era on one endpoint. Upgrade steps: UPGRADE.md. The 3.x line
stays on mcp/sdk ~0.7.0.

Breaking

  • Requires mcp/sdk ~0.8.1.
  • The stateless era is served by default (modern_era, default true;
    McpServerFactory(modernEra:)). header_validation (default true)
    rejects stateless requests whose standard headers contradict the body.
  • initialize negotiates the revision (SDK 0.8) instead of always answering
    2025-11-25; protocol_version pins a handshake revision only — 2026-07-28
    there fails at config load.
  • Interceptor\SessionBudgetInterceptor is now
    Interceptor\ToolCallBudgetInterceptor, and session.budget is
    tool_call_budget.calls (+ .window); the old key fails the build. On the
    stateless era — which hands every request a throwaway session, so a session
    counter never ran out — the budget counts per client id over a fixed window
    in the container's PSR-16 cache (required then; anonymous callers share one
    budget; a cache outage rejects the call).
  • ToolCallContext, PromptGetContext and ResourceReadContext replace
    getClientInfo(): array with clientInfo(): ?Mcp\Schema\Implementation,
    reading initialize (handshake) or the request's _meta (stateless) — on
    the stateless era the old method returned [] silently.
  • Resource\ResourceUpdateNotifier::notify() is
    notify(string $uri, ?RequestContext $context = null): void: it publishes to
    the notification bus (new notifications.bus: '' | psr16 | memory;
    notifications.subscription_lifetime), reaching every stateless
    subscriptions/listen stream whose filter names the URI from any process,
    and still notifies a subscribed calling handshake session.
  • A tool hidden by ToolVisibilityInterface answers the same JSON-RPC error as
    a missing one (-32602, Tool not found: "…"), checked before argument
    validation — it was a tool-error result, and an invalid call revealed the
    hidden schema. A hidden prompt or resource ref in completion/complete
    answers -32602 too: it answered -32002, which SDK 0.8 no longer uses for
    a missing ref, so the code told hidden from missing.
  • Testing\McpTester throws Testing\McpErrorException (a
    RuntimeException, same message) carrying errorCode, errorMessage and
    errorData.

Added

  • Multi round-trip calls on the stateless era: a handler's elicit() ends the
    request with input_required and runs again on the retry;
    request_state.key/ttl (McpServerFactory(requestStateKey:, requestStateTtl:)) sign the state carrying earlier answers. Every round
    counts against the tool-call budget.
  • Interceptor contexts carry ?RequestContext $requestContext: an interceptor
    can ask the user before the call (getClientGateway()->elicit(),
    OpenAPI-bridged tools included) and read the caller's W3C trace context.
  • Interceptor contexts expose isStateless(): on the stateless era the
    session is a per-request throwaway, so its id must not be logged as a
    session and nothing kept there survives.
  • cache_policy params (McpServerFactory(cachePolicy:)): SEP-2549 caching
    hints on stateless answers, validated at config load; public on a list or
    read a visibility filter makes per caller fails the build.
  • Testing\McpTester takes a protocol revision (fifth argument;
    ProtocolVersion::V2026_07_28 speaks the stateless era with the SDK's own
    client envelope and headers) and ClientCapabilities (sixth).
  • mcp:doctor: a protocol_eras check (shared stateless budget under a single
    secret, missing bus or request-state key, too-short key); the stateless
    budget and the psr16 bus require a PSR-16 cache.

Fixed

  • allowed_hosts no longer adds ProtocolVersionMiddleware to the transport
    stack, which rejected every stateless request.
  • result_json: compact takes structuredContent from the SDK's extraction
    for the request's revision: a list is no longer sent as structuredContent
    to pre-2026-07-28 clients (strict clients rejected the whole call).
  • CachingToolCallInterceptor never stores an input_required ask and never
    serves a later round of a multi round-trip call.

v3.1.1

Choose a tag to compare

@github-actions github-actions released this 07 Oct 16:10
148c87e
  • executor: psr15 fills the nested request's query params from its URL
    (getQueryParams()); the PSR-17 factory only set the URI, so applications
    reading arguments from the parsed query (every Yii/Symfony/Laravel action)
    saw none of the tool's query arguments, and array parameters in particular
    never arrived.

v3.1.0

Choose a tag to compare

@github-actions github-actions released this 07 Oct 15:54
764e250
  • The OpenAPI bridge supports array-typed query parameters (#58): a
    type: array parameter in in: query with scalar items is advertised as an
    array argument (items, enum, minItems, maxItems preserved) and
    re-validated by the executor before the request is built, so a direct caller
    cannot bypass the SDK's schema check. Both executors share the logic
    (OperationRequestBuilder). Wire format: new openapi.array_query_style
    (repeat | brackets | comma, empty = per parameter from its declared
    explode) and openapi.array_query_params
    (operationId => parameter => style); OpenApiBridgeFactory::create() takes
    arrayQueryStyle and arrayQueryParams. Arrays outside a query parameter,
    object or nested-array items, style other than form and
    allowReserved: true still fail the server build. An unknown style fails the
    build too. Previously any array query parameter failed with "must use a scalar
    schema". Backward compatible: nothing changes for operations without
    array parameters.

v3.0.1

Choose a tag to compare

@github-actions github-actions released this 07 Oct 15:29
b851539
  • Fixed the psr15 executor still requiring a PSR-18 ClientInterface (and
    the outbound PSR-17 request factory) in the container: the component
    resolver resolved both unconditionally, so a psr15-only application failed
    the server build with a NotFoundException — contradicting the mode's
    no-network-I/O contract while mcp:doctor reported the handler as
    available. Both services are now resolved only for http execution or a
    URL spec_path; OpenApiBridgeFactory::create() accepts null for them
    in psr15 mode (a URL spec still needs the client and rejects null with
    an explicit message).

v3.0.0

Choose a tag to compare

@github-actions github-actions released this 07 Oct 14:00
b1639ae
  • Intentional compatibility boundary: OpenApiServerConfigurator::__construct()
    now accepts the executor as the new OpenApi\OperationExecutorInterface
    (HTTP or in-process) instead of the concrete HttpOperationExecutor. Every
    previously valid construction keeps working unchanged — the old class
    implements the interface — but widening an @api constructor parameter is
    a major under SemVer, so the boundary is declared here deliberately rather
    than suppressed. No manual upgrade steps: see UPGRADE.md.

  • mcp:serve, mcp:list and mcp:doctor are registered through the
    package's yiisoft/yii-console params, so the commands appear in
    ./yii list right after composer require with no application-side
    configuration. An application's own commands map merges recursively and
    wins on a name conflict; applications not using yiisoft/config can still
    list the three classes manually.

  • New result_json server param ('pretty' default, 'compact' opt-in):
    array/object tool results are encoded into the text content without
    indentation (JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE, ~3x fewer
    context tokens) while structuredContent keeps being produced for array
    results. Interceptors, the tool-result cache and
    limits.tool_result_bytes keep seeing the raw handler result — the
    conversion happens after the interceptor chain, right before the SDK's own
    formatter would run. Anything but 'pretty'/'compact' fails at config
    load.

  • The OpenAPI bridge gained an in-process executor for bridging the
    application's own API: openapi.executor => 'psr15' with
    openapi.handler (a Psr\Http\Server\RequestHandlerInterface FQCN)
    builds the same request the HTTP executor would send — method, URI,
    headers, delegated headers, JSON body — and calls the handler in-process:
    no network I/O, one FPM worker instead of two under php-fpm. Optional
    openapi.request_attributes
    (OpenApi\ExecutionRequestAttributesInterface) maps the resolved
    ExecutionIdentity to request attributes on the nested request, and
    optional openapi.in_process_scope (OpenApi\InProcessScopeInterface)
    gets enter()/leave() calls around the nested handle() — leave()
    runs even when the nested call throws — so the application can reset the
    request-scoped state the outer MCP request left behind. Response size
    cap, error mapping, opaque_errors and dry-run previews are identical to
    HTTP mode; request assembly and response decoding live in shared
    OperationRequestBuilder/OperationResponseDecoder so the two
    transports cannot drift. mcp:doctor requires the PSR-17 server-request
    factory and the configured handler instead of the PSR-18 client in this
    mode.

v2.3.0

Choose a tag to compare

@github-actions github-actions released this 08 Sep 07:40
b389285
  • OpenApi\Exception\InvalidToolArgumentException is thrown by every guard on
    a bridged call's arguments, and BridgedToolHandler now converts only it and
    OperationFailedException into a caller-visible tool error. The previous
    InvalidArgumentException catch was wide enough to include the PSR-17/PSR-18
    stack's own failures — an unparseable request URI, a delegated header name
    that is not RFC 7230 compatible — whose messages quote the base URL or the
    offending header; those reached the MCP client as if the agent's own
    arguments were at fault. They now stay behind the SDK's generic internal
    error.

  • OpenApi\OpenApiBridgeFactory::create() builds a configured
    OpenApiServerConfigurator from a spec (file path, http(s) URL or decoded
    document), a base URL, PSR-18/PSR-17 services and the operation allow-list —
    so the bridge is usable without a Yii3 application. SpecIndex and
    HttpOperationExecutor stay @internal: Psalm's @internal is
    namespace-scoped, so the factory constructs them while a consumer never
    references one. McpServerComponentResolver now calls the same factory, so
    the config-plugin path and a standalone server assemble the bridge
    identically.

  • Bridged tool failures now name the tool the client actually called instead
    of the upstream operationId — under tool_names those differ, and the
    rename is precisely what hid the operationId from the agent. Applies to HTTP
    failures, the response-cap refusal and every argument guard. The dry-run
    preview payload still reports operationId: it documents the upstream
    request rather than the call the client made.

  • Those messages now reach the client at all. BridgedToolHandler rethrows
    OperationFailedException and the argument InvalidArgumentExceptions as
    the SDK's ToolCallException, which is the only exception type
    CallToolHandler turns into a tool-error envelope carrying the message;
    everything else became a generic Error while executing tool with the text
    dropped — which also made opaque_errors indistinguishable from its own
    opposite.

  • openapi.multi_segment_path_params opts a named path parameter into
    values carrying that many "/"-separated segments, for upstreams that
    identify a resource by a nested path and accept it percent-encoded
    (GitLab's group/project → group%2Fproject, which the bridge previously
    could not call at all). Empty by default: with no parameter opted in,
    path-argument validation is unchanged. The opt-in allows the separator and
    nothing else — .., a backslash, an empty value and a bare . stay
    rejected, every segment must match [A-Za-z0-9_][A-Za-z0-9_.-]*, and the
    limit must be an integer from 1 to 20 — a string, float or out-of-range
    value fails at server build time rather than being coerced. Neither the charset nor that ceiling is
    configurable: a multi-segment value no longer pins the request to the
    allow-listed route, and the segment cap is what bounds it.

  • Internal only: property-based tests via rasuvaeff/property-testing-testo
    for the six classes whose contracts are invariants rather than fixed cases —
    Utf8::cut(), OpenApi\ToolNameValidator, OpenApi\JsonPointerResolver,
    Interceptor\ArgumentMasker, Visibility\DeclarativeToolVisibility and
    Interceptor\SessionBudgetInterceptor (model-based, over generated
    call/re-initialize sequences). Utf8Test already asserted these invariants
    over five hardcoded strings; the generators supply the input space it was
    missing. The tool-name property is stated as charset plus length rather than
    by re-running the class's own pattern, so it fails if the \z anchor ever
    becomes $ and a trailing newline starts being accepted. CI gains
    ext-mbstring (required by property-testing) and a cached property
    regression corpus, so a falsified property replays its counterexample on the
    next run. No production code and no public API changed.

  • Internal only: the Coverage & Mutation job now has its own narrow change
    filter (src tests composer.json testo.php infection.json5) instead of
    sharing the broad one — a docs, examples/ or workflow edit no longer pays
    a full mutation run. infection/infection moved from ^0.33 to ^0.35
    (single major, so Prefer lowest actually exercises the lower bound).

  • Internal only: release.yml caught up with the monorepo template. It now
    refuses to publish a Release for a tag that is not an ancestor of master
    or whose matrix build did not pass (build.yml never runs on a tag push, so
    nothing checked this before), matches the changelog section as text rather
    than as a regex, passes the notes through a file instead of a
    GITHUB_OUTPUT heredoc that a matching line could truncate, and creates the
    release with --verify-tag so gh cannot invent a missing tag from the
    default branch.

  • Internal only: the codebase is rector clean again — ToolCallException
    now carries the original exception's code, and two test call sites lost a
    redundant null named argument and gained a named literal.