Repository navigation
Releases
v5.0.0
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_jsondefaults to'compact'. Since 0.10 the SDK itself encodes
array/object tool results without indentation, socompactis the SDK's
own output andprettyis now the package's:CompactToolResultFormatter
(@internal) becameToolResultTextFormatterand mirrors the SDK's
CallToolHandleragain (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'scompactToolResultsdefaults totrue; it gained the
optionalpreviousRequestStateKeys,bindRequestStateandfiberContext
arguments.- A result decorator that builds a new
CallToolResultmust pass
StructuredContent::Absentfor a result without structured content: since
0.10 an explicitnullis sent as"structuredContent": null. Testing\McpTesterspeaksProtocolVersion::latestHandshake()by default
(the SDK'sMessageInterface::PROTOCOL_VERSIONis the stateless 2026-07-28
since 0.9) and addresseshttp://localhost/mcp: the SDK now refuses a
request without an allowedHost.- 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.bindis on by default: arequestStateminted 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\BearerTokenMiddlewareover the SDK's
AuthorizationMiddleware. Route[BearerTokenMiddleware, McpAction]and
serve the SDK'sProtectedResourceMetadataHandlerat
/.well-known/oauth-protected-resource/<path>; configured by the new
oauthparams 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_idor
subjectbecomes the client id, so session ownership, visibility, the
budget and the result cache work unchanged. A token without that claim gets
401invalid_token.psr/cacheis now required. request_state.previous_keys: keys that still verify arequestStatebut
no longer sign one — the signing key rotates without failing calls in
flight.request_state.bind(defaulttrue): a state is tied to its originating
request (the SDK'sOriginatingRequestBinder: method, tool, argument
digest, OAuth principal) and to the resolved client id, which the SDK binder
does not know behindSharedSecretMiddleware; a state replayed by another
client or for other arguments does not verify.notifications.bus'psr6': the SDK'sPsr6NotificationBusover the
container'sCacheItemPoolInterface;mcp:doctorrequires the pool then.- A container binding of
Mcp\Server\Fiber\FiberContextInterfaceis
autowired intoMcpServerFactoryand handed toBuilder::setFiberContext()
(e.g. the OpenTelemetry context inside handler fibers).
Fixed
ArgumentMaskermasks 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.GuardedRegistryforwards the SDK's newpublishesListChanges().
Internal
- Mutation testing (
composer mutation) now counts code that no test is
attributed to (--with-uncovered; Infection runs theUnitsuite only).
Overall MSI 82% -> 98% against the unchangedminMsiof 97. New tests
coverOperationRequestBuilder,OperationResponseDecoder,RequestEra,
the session-ownership edge cases ofMcpAction,McpTesterpagination
against a misbehaving peer,McpDoctorfailure 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
- Stateless SSE streams (
subscriptions/listen) are sent frame by frame
under PHP-FPM (#74).mcp/sdk0.8.1 writes each frame withflush()only,
which leaves it in PHP'soutput_bufferingbuffer (4096 in both shipped
php.ini files), so the client got the whole stream when it closed — a
notification arrived up tosubscription_lifetimelate.McpActionnow
wraps atext/event-streambody inOutputBufferReleasingStream
(@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 themcp/sdkpin includes it.
v4.1.0
- Tool-result decorators (#71):
Interceptor\ToolResultDecoratorInterface
gets the formattedCallToolResultof every successfultools/callafter
the whole interceptor chain and returns it with added content (a
ResourceLinkper item, an image) — no re-implementation of result
formatting or of the per-revisionstructuredContentrule. Configured by
the newresult_decoratorsparams key (a class not implementing the
interface fails the build) orMcpServerFactory::create(resultDecorators:).
Decorators run on cache hits too, never see aninput_requiredask or a
ToolCallException, and their output is not counted by
limits.tool_result_bytes. Inprettymode the package builds the result
the way the SDK does, only when a decorator is configured; without one
nothing changes.
v4.0.1
clientInfo()keeps the name of a client that sends noversion(an
Implementationwith an empty version); 4.0.0 returnednull, while 3.x
getClientInfo()still exposed the name (#69).- Docs: 3.x is not maintained as a separate line (the
3.xbranch announced
in 4.0.0 was dropped); fixes land in 4.x.llms.txtnamed the old
mcp/sdkpin.
v4.0.0
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, defaulttrue;
McpServerFactory(modernEra:)).header_validation(defaulttrue)
rejects stateless requests whose standard headers contradict the body. initializenegotiates the revision (SDK 0.8) instead of always answering
2025-11-25;protocol_versionpins a handshake revision only —2026-07-28
there fails at config load.Interceptor\SessionBudgetInterceptoris now
Interceptor\ToolCallBudgetInterceptor, andsession.budgetis
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,PromptGetContextandResourceReadContextreplace
getClientInfo(): arraywithclientInfo(): ?Mcp\Schema\Implementation,
readinginitialize(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 (newnotifications.bus:''|psr16|memory;
notifications.subscription_lifetime), reaching every stateless
subscriptions/listenstream whose filter names the URI from any process,
and still notifies a subscribed calling handshake session.- A tool hidden by
ToolVisibilityInterfaceanswers 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 incompletion/complete
answers-32602too: it answered-32002, which SDK 0.8 no longer uses for
a missing ref, so the code told hidden from missing. Testing\McpTesterthrowsTesting\McpErrorException(a
RuntimeException, same message) carryingerrorCode,errorMessageand
errorData.
Added
- Multi round-trip calls on the stateless era: a handler's
elicit()ends the
request withinput_requiredand 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_policyparams (McpServerFactory(cachePolicy:)): SEP-2549 caching
hints on stateless answers, validated at config load;publicon a list or
read a visibility filter makes per caller fails the build.Testing\McpTestertakes a protocol revision (fifth argument;
ProtocolVersion::V2026_07_28speaks the stateless era with the SDK's own
client envelope and headers) andClientCapabilities(sixth).mcp:doctor: aprotocol_erascheck (shared stateless budget under a single
secret, missing bus or request-state key, too-short key); the stateless
budget and thepsr16bus require a PSR-16 cache.
Fixed
allowed_hostsno longer addsProtocolVersionMiddlewareto the transport
stack, which rejected every stateless request.result_json: compacttakesstructuredContentfrom the SDK's extraction
for the request's revision: a list is no longer sent asstructuredContent
to pre-2026-07-28 clients (strict clients rejected the whole call).CachingToolCallInterceptornever stores aninput_requiredask and never
serves a later round of a multi round-trip call.
v3.1.1
executor: psr15fills 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
- The OpenAPI bridge supports array-typed query parameters (#58): a
type: arrayparameter inin: querywith scalar items is advertised as an
array argument (items,enum,minItems,maxItemspreserved) 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: newopenapi.array_query_style
(repeat|brackets|comma, empty = per parameter from its declared
explode) andopenapi.array_query_params
(operationId => parameter => style);OpenApiBridgeFactory::create()takes
arrayQueryStyleandarrayQueryParams. Arrays outside a query parameter,
object or nested-array items,styleother thanformand
allowReserved: truestill 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
- Fixed the
psr15executor still requiring a PSR-18ClientInterface(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 aNotFoundException— contradicting the mode's
no-network-I/O contract whilemcp:doctorreported the handler as
available. Both services are now resolved only forhttpexecution or a
URLspec_path;OpenApiBridgeFactory::create()acceptsnullfor them
inpsr15mode (a URL spec still needs the client and rejectsnullwith
an explicit message).
v3.0.0
-
Intentional compatibility boundary:
OpenApiServerConfigurator::__construct()
now accepts the executor as the newOpenApi\OperationExecutorInterface
(HTTP or in-process) instead of the concreteHttpOperationExecutor. Every
previously valid construction keeps working unchanged — the old class
implements the interface — but widening an@apiconstructor parameter is
a major under SemVer, so the boundary is declared here deliberately rather
than suppressed. No manual upgrade steps: seeUPGRADE.md. -
mcp:serve,mcp:listandmcp:doctorare registered through the
package'syiisoft/yii-consoleparams, so the commands appear in
./yii listright aftercomposer requirewith no application-side
configuration. An application's own commands map merges recursively and
wins on a name conflict; applications not usingyiisoft/configcan still
list the three classes manually. -
New
result_jsonserver 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) whilestructuredContentkeeps being produced for array
results. Interceptors, the tool-result cache and
limits.tool_result_byteskeep 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(aPsr\Http\Server\RequestHandlerInterfaceFQCN)
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
ExecutionIdentityto request attributes on the nested request, and
optionalopenapi.in_process_scope(OpenApi\InProcessScopeInterface)
getsenter()/leave()calls around the nestedhandle()—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_errorsand dry-run previews are identical to
HTTP mode; request assembly and response decoding live in shared
OperationRequestBuilder/OperationResponseDecoderso the two
transports cannot drift.mcp:doctorrequires the PSR-17 server-request
factory and the configured handler instead of the PSR-18 client in this
mode.
v2.3.0
-
OpenApi\Exception\InvalidToolArgumentExceptionis thrown by every guard on
a bridged call's arguments, andBridgedToolHandlernow converts only it and
OperationFailedExceptioninto a caller-visible tool error. The previous
InvalidArgumentExceptioncatch 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
OpenApiServerConfiguratorfrom 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.SpecIndexand
HttpOperationExecutorstay@internal: Psalm's@internalis
namespace-scoped, so the factory constructs them while a consumer never
references one.McpServerComponentResolvernow 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 upstreamoperationId— undertool_namesthose 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 reportsoperationId: it documents the upstream
request rather than the call the client made. -
Those messages now reach the client at all.
BridgedToolHandlerrethrows
OperationFailedExceptionand the argumentInvalidArgumentExceptions as
the SDK'sToolCallException, which is the only exception type
CallToolHandlerturns into a tool-error envelope carrying the message;
everything else became a genericError while executing toolwith the text
dropped — which also madeopaque_errorsindistinguishable from its own
opposite. -
openapi.multi_segment_path_paramsopts 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'sgroup/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\DeclarativeToolVisibilityand
Interceptor\SessionBudgetInterceptor(model-based, over generated
call/re-initialize sequences).Utf8Testalready 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\zanchor 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 & Mutationjob 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/infectionmoved from^0.33to^0.35
(single major, soPrefer lowestactually exercises the lower bound). -
Internal only:
release.ymlcaught up with the monorepo template. It now
refuses to publish a Release for a tag that is not an ancestor ofmaster
or whose matrix build did not pass (build.ymlnever 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_OUTPUTheredoc that a matching line could truncate, and creates the
release with--verify-tagsoghcannot invent a missing tag from the
default branch. -
Internal only: the codebase is
rectorclean 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.