- Add a shields.io badge row to the README header (version, CI, PHP
version, license, conformance scores, protocol/spec) to match the
other official MCP SDKs.
- Expand "PHP Libraries Using the MCP SDK" into a curated, alphabetically
sorted list of downstream projects.
- Add tests/Conformance/bin/score.php, a Symfony Console command that
turns a conformance run's --output-dir into a shields.io endpoint JSON.
- Extend the weekly conformance workflow to score each run and publish
the client/server pass-rate to the orphan `badges` branch that the
README badges read.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
#301 added the `title` field to the `Resource`/`ResourceTemplate` schema
classes and the `McpResource`/`McpResourceTemplate` attributes, but the
manual registration methods on `Builder` were never updated — so manual
registration could not set a resource title, unlike tools and prompts.
Add a `$title` parameter between `$name` and `$description` (matching
`addTool()`/`addPrompt()`) and propagate it through `ArrayLoader` when
constructing the `Resource`/`ResourceTemplate` objects.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The MCP specification (2025-11-25) defines an optional title field for
Resource and ResourceTemplate as a human-readable display label, distinct
from name (a short identifier). Tool and Prompt already implement this
field; Resource and ResourceTemplate were missing it.
Changes:
- Add title parameter to Resource and ResourceTemplate constructors
- Add title to fromArray(), jsonSerialize(), and PHPStan type arrays
- Add title to McpResource and McpResourceTemplate attributes
- Pass title through Discoverer when constructing schema objects
- Add tests for deserialization, serialization, and null omission
Fixes#296
Drop the isManual flag from ElementReference and the discovery-state methods
from RegistryInterface. The Registry becomes a flat last-write-wins map;
DiscoveryLoader owns its own owned-set bookkeeping so re-running discovery
only removes elements it itself contributed. Adds ChainLoader for explicit
composition. Manual-over-discovered precedence is preserved via loader
ordering, not a flag on the reference.
Make session GC probability configurable via gcProbability and gcDivisor
parameters, mirroring PHP's session.gc_probability/session.gc_divisor.
Exposed through both SessionManager constructor and Builder::setSession().
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: allow URIs without double slash in Resource and ResourceTemplate (RFC 3986)
The URI regex required "://" after the scheme, rejecting valid URIs
like urn:isbn:123, mailto:user@example.com, config:key, and data:
URIs. RFC 3986 only requires ":" after the scheme; the "//" is part
of the authority component which is optional.
Changed both Resource.URI_PATTERN and ResourceTemplate.URI_TEMPLATE_PATTERN
to require ":" instead of "://".
Adds data-provider tests for URIs without double slash in both classes.
Fixes#293
* Reword unit tests
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* Add optional namePatterns capability to discovery so that the default scan for `*.php` files can be overridden.
* add default to namePatterns docs
* add an error check if we manage to pass in an empty list of patterns
* add unit tests (and a static entry to classmap for composer.json so it autoloads from a non .php file for the test)
* run php-cs-fixer
* change how default namePatterns are set and make sure all the annotations are correct
* Fix bad whitespace
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* switch to a const default instead of nullable with a check in the function to convert null to a default
* make sure we handle empty arrays
* formatting fixes
* Apply suggestion from @chr-hertel
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* Add changelog entry
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* feat(schema): add top-level title to Tool
Mirror PR #278's Prompt change for Tool:
- Add optional ?string $title to Mcp\Schema\Tool between $name
and $inputSchema. fromArray() now reads $data['title'];
jsonSerialize() emits 'title' right after 'name'. The
@phpstan-type ToolData gains title?: string.
- Add ?string $title to the #[McpTool] attribute between $name
and $description.
- Note ToolAnnotations::$title as deprecated-for-display in
favor of Tool::$title per MCP spec 2025-06-18 (PHPDoc only,
field retained for BC).
Phase 1 of plan 01--tool-title-spec-compliance. Later phases
update Discoverer, Builder::addTool(), ArrayLoader, and the
conformance fixture to match the new signature.
* feat(server): thread title through discovery
- Discoverer::processMethod() now propagates McpTool::$title
into every discovered Tool via named arguments.
- Builder::addTool() accepts ?string $title between $name and
$description. [BC Break] positional callers passing the old
$description as 3rd positional argument must switch to named
arguments, matching the precedent set for addPrompt() in
0.5.0.
- tests/Conformance/server.php migrated to named-argument form
for every addTool() call.
Phase 2 of plan 01--tool-title-spec-compliance.
* feat(loader): forward title in ArrayLoader
ArrayLoader now reads 'title' from each tool config entry and
passes it into the Tool constructor, completing the wiring
from Builder::addTool() through array-driven registration.
The $tools @param array-shape typedef gains title: ?string
between name and description.
Phase 3 of plan 01--tool-title-spec-compliance.
* test(schema): cover Tool.title end-to-end
- New tests/Unit/Schema/ToolTest.php: constructor round-trip,
jsonSerialize key-order when title set vs null, fromArray
tolerance.
- New tests/Unit/Capability/Discovery/DiscovererToolTitleTest
plus a TitleFixture class verifying McpTool(title: ...)
propagates through discovery into the registered Tool.
- New tests/Unit/Capability/Registry/Loader/ArrayLoader...
test verifying array-driven title propagation.
- Extend McpToolTest for title named-arg and default-null.
- Extend BuilderTest with addTool(title: 't') propagation.
- Update tests/Unit/.../RegistryTest, CallToolHandlerTest,
ListToolsHandlerTest and examples/.../server.php
new Tool(...) call sites to pass title (named args) so
they match the new constructor signature.
- CHANGELOG 0.6.0 section: feature bullet + [BC Break]
note for addTool() signature, mirroring 0.5.0 Prompt
entries.
- docs/server-builder.md: addTool() row and prose now
list title? between name and description.
Phase 4 of plan 01--tool-title-spec-compliance. All 730
phpunit tests pass; remaining phpstan warnings are
pre-existing and unrelated to Tool.title.
* refactor(schema): make Tool.title non-BC-breaking
Move `title` to the end of the Tool, Builder::addTool, and McpTool
attribute constructors with a default of null. This preserves
positional-argument compatibility and removes the need for
`title: null` boilerplate at call sites. JSON serialization order
(name, title, inputSchema, ...) is unchanged.
Also tighten the new tests: parameterize ToolTest with data
providers, fold the Discoverer title fixture into the existing
DiscoverableToolHandler, and drop the reflection-heavy Builder
test that overlapped with ArrayLoaderToolTitleTest.
* fix: move title after name
---------
Co-authored-by: DDEV User <nobody@example.com>
* style: apply php-cs-fixer to test files
Addresses drift flagged by the default PHP-CS-Fixer config — mostly
adds missing `: void` return types on pre-existing test methods.
No behavioural changes.
* fix: resolve phpstan errors surfaced by qa
- Drop the obsolete `Method ::test*() has no return type specified`
ignore rule — every test method now declares a return type, so
the pattern never matches and phpstan reports it as unmatched.
- Remove `?? []` from two reads of `CallToolRequest::$arguments`;
the property is typed `array` (non-nullable), so the coalesce is
a no-op that phpstan flags.
---------
Co-authored-by: DDEV User <nobody@example.com>
The MCP 2025-11-25 specification defines an optional `title` property on
Prompt for human-readable display in UI contexts, distinct from the
programmatic `name` identifier. This was missing from the SDK.
BC Break: Builder::addPrompt() signature changed — $title parameter added
between $name and $description. Callers using positional arguments for
$description must switch to named arguments.
Closes#276
* feat: relax OIDC discovery policy and add Dynamic Client Registration middleware (RFC 7591)
- Add LenientOidcDiscoveryMetadataPolicy for providers that omit
code_challenge_methods_supported (e.g. FusionAuth, Microsoft Entra ID)
- Keep StrictOidcDiscoveryMetadataPolicy RFC-aligned
- Add ClientRegistrationMiddleware handling POST /register and enriching
/.well-known/oauth-authorization-server with registration_endpoint
- Update Microsoft example to use built-in LenientOidcDiscoveryMetadataPolicy
* fix: move metadata policy note under server.php in Files section
Address review comment: the LenientOidcDiscoveryMetadataPolicy bullet
was a behavioral note, not a file entry. Inline it into the server.php
description to keep the Files list consistent.
* fix: address Copilot review comments on ClientRegistrationMiddleware
- Decode JSON with assoc=true for registrar data so nested objects
are associative arrays, not stdClass instances
- Add Cache-Control: no-store to all error responses (400), not just
the success response (201)
- Rewind response body stream before returning unmodified response
when metadata is not valid JSON, preventing empty body on read
* fix: harden ClientRegistrationMiddleware and improve test coverage
- Revert spurious .gitignore trailing newline
- Use JSON_THROW_ON_ERROR consistently in enrichAuthServerMetadata()
- Add comment clarifying the second json_decode in handleRegistration()
- Assert Cache-Control: no-store on registrar exception error response
- Add test for non-object JSON body in metadata enrichment path
- Extract createPlainTextHandler helper for non-JSON response tests
* fix: reject JSON array bodies in metadata enrichment
Treat JSON list arrays (e.g. [] or ["..."]) as invalid metadata in
enrichAuthServerMetadata() to prevent corrupting the response shape
by adding registration_endpoint to a non-object.
* fix: add RFC 7591 error codes, Content-Type validation, and docblock safety warning
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add setReferenceHandler to Builder
Allow consumers to provide a custom ReferenceHandlerInterface
implementation (e.g. a security-aware decorator) instead of
always using the default ReferenceHandler.
* test: add BuilderTest for setReferenceHandler
- Fluent API returns builder instance
- build() succeeds with and without custom handler
- Integration test verifies custom handler intercepts tool calls
* style: fix codestyle in BuilderTest
* style: use imports instead of inline FQCNs in BuilderTest
* docs: add changelog entry for setReferenceHandler
* Add Middleware handlers to StreamableHttpTransport
* OAuth Implementation based on middleware
* OAuth Implementation based on middleware
* Add Middleware handlers to StreamableHttpTransport
* OAuth Implementation based on middleware
* OAuth Implementation based on middleware
Signed-off-by: Volodymyr Panivko <sveneld300@gmail.com>
* Address PR review feedback for OAuth middleware
* Apply php-cs-fixer to satisfy QA
* Use Mcp exception classes in OAuth middleware
* Refactor OAuth HTTP stack and add Microsoft example policies
* Fix QA PHPStan findings in OAuth examples and auth middleware
* Require OIDC discovery in JWKS provider and refine OAuth proxy behavior
* Remove local development docker artifacts from VCS
* Revert .gitignore changes for local docker files
* Fix body retrieval in OAuthRequestMetaMiddleware for proper string conversion
Signed-off-by: Volodymyr Panivko <sveneld300@gmail.com>
* Address OAuth PR review feedback and align example configs
* Fix QA style issues and add authorization docs
* Fix PHPStan typing issues in OAuth middleware
* Remove duplicate Middleware namespace, consolidate under Http\Middleware
Remove old Mcp\Server\Transport\Middleware\ classes that were duplicated
in Mcp\Server\Transport\Http\Middleware\ and Http\OAuth\. Update docs
to reference the correct namespaces.
* Address PR review: replace Throwable catch with specific exceptions, add JSON_THROW_ON_ERROR
- JwtTokenValidator: replace catch(\Throwable) with explicit
\InvalidArgumentException|\UnexpectedValueException|\DomainException,
letting RuntimeException from JwksProvider propagate as infrastructure errors
- OAuthProxyMiddleware: add \JSON_THROW_ON_ERROR to json_encode for metadata response
- Update tests to expect RuntimeException for JWKS infrastructure failures
---------
Signed-off-by: Volodymyr Panivko <sveneld300@gmail.com>
Co-authored-by: Volodymyr Panivko <volodymyr.panivko@togethernetworks.com>
- Add ElicitAction enum (accept/decline/cancel)
- Add schema definitions for elicitation fields (string, number, boolean, enum)
- Add ElicitationSchema wrapper for requestedSchema
- Add ElicitRequest and ElicitResult for elicitation/create method
- Update ClientCapabilities to support elicitation capability
- Add elicit() method to ClientGateway
- Store client capabilities in session during initialization
- Add comprehensive unit tests
- Add elicitation example server with book_restaurant, confirm_action, and collect_feedback tools
Split formatting logic from Reference classes into dedicated formatter classes:
- ToolResultFormatter: Formats tool execution results into Content items
- PromptResultFormatter: Formats prompt results into PromptMessage items
- ResourceResultFormatter: Formats resource results into ResourceContents items
This refactor:
- Eliminates 122 lines of code duplication between ResourceReference and
ResourceTemplateReference (identical formatting logic)
- Improves code organization by separating formatting concerns from
capability reference management
- Makes formatters independently testable and reusable
- Reduces Reference classes by ~450 lines while maintaining all functionality
Changes:
- Create src/Capability/Formatter/* with three formatter classes
- Update Reference classes to delegate to formatters instead of inline logic
- Add comprehensive test coverage for all formatter classes
- All existing tests pass; no behavioral changes
* Remove `getSummary` method and update descriptions in snapshots and code
* Add changelog entry
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
