* [Server] Add CORS, DNS rebinding and protocol version middleware
Introduce three PSR-15 middleware for `StreamableHttpTransport` exposed
through a public `StreamableHttpTransport::defaultMiddleware()` factory
composed automatically when no middleware is passed.
- `CorsMiddleware`: secure-by-default (no `Access-Control-Allow-Origin`),
configurable allowlist, reflects matching origin with `Vary: Origin`
to protect shared caches.
- `DnsRebindingProtectionMiddleware`: validates `Origin`/`Host` against
a hostname allowlist (localhost-only by default).
- `ProtocolVersionMiddleware`: rejects requests carrying an unsupported
`Mcp-Protocol-Version` header with `400 Bad Request`.
The transport no longer applies CORS via an `instanceof + array_unshift`
post-hook; the middleware parameter is nullable — `null` installs the
secure defaults, `[]` disables them, and users compose by spreading
`StreamableHttpTransport::defaultMiddleware()`. `SESSION_HEADER` and
`PROTOCOL_VERSION_HEADER` are promoted to public constants so middleware
can reuse them.
BC breaks:
- The `corsHeaders` constructor parameter is removed; the `middleware`
parameter shifts one position. Positional callers passing the old
`corsHeaders` argument must switch to named arguments or drop it.
- Default `Access-Control-Allow-Origin` is no longer `*`.
Addresses #260 (DNS rebinding), #277 (CORS extraction) and #306
(protocol version validation).
* [Server] Address review feedback on middleware defaults
- CorsMiddleware: emit Access-Control-Allow-Methods/Headers only on
preflight per CORS spec; tokenize Vary header to avoid substring
false-positives; add allowCredentials flag that emits
Access-Control-Allow-Credentials and throws when combined with
wildcard origin.
- DnsRebindingProtectionMiddleware: return plain-text 403 body
(HTTP-level rejection, not JSON-RPC); use parse_url(..., PHP_URL_HOST)
for origin parsing; drop redundant unbracketed '::1' from default
allowlist.
- ProtocolVersionMiddleware: use Error::forInvalidParams instead of
forInvalidRequest -- JSON-RPC -32602 fits header-value rejection
better.
- JsonRpcErrorResponse::create now accepts a JsonRpc\Error so callers
choose the error code.
- StreamableHttpTransport: emit a warning log when an explicit empty
middleware list is passed, so operators can spot accidental bypass
of the default security stack.
* [Server] Fix CI: switch warning-log tests to PHPUnit mocks
Replace the anonymous AbstractLogger fixture in
StreamableHttpTransportTest with `$this->createMock(LoggerInterface::class)`
so the test does not declare a `log()` signature at all. That sidesteps
both the psr/log v1 LSP incompatibility (untyped parameter) and the
phpstan `missingType.parameter` complaint in one move, and matches how
the rest of the suite (CallToolHandlerTest etc.) fakes loggers.
* Update src/Server/Transport/Http/Middleware/CorsMiddleware.php
Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>
---------
Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>
* 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>
* 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(client): add complete MCP client SDK with STDIO and HTTP transports
Add Client, Builder, ClientProtocol, ClientSession, and transport
implementations for communicating with MCP servers. Supports tools, resources, prompts, and real-time progress/logging notifications.
* refactor(examples): reorganize examples into server/ and client/ folders
* feat: add SamplingRequestHandler for handling server sampling requests
* feat: add setLoggingLevel method to control server logging verbosity
* refactor: make progress token dependent on request ID
* docs: Update server IP in usage instructions and add notes on sampling server requirements.
* feat: add complete() method for completion/complete requests
* refactor: properly parse and type initialize result
* refactor: standardize method names
* fix: revert changes to server related components
* fix: revert changes to server related components
* refactor: Restructure client transports and handlers into dedicated namespaces.
* fix: cs and php-stan errors fixes(partial)
* feat: Refactor request handlers to return `Response` or `Error` objects directly, adding a `SamplingException` and error logging for sampling requests.
* feat: Replace `ClientTransportInterface` with `TransportInterface` and move response result deserialization to client methods.
* refactor: remove redundant timeout check for intialize on transports
The processFiber that executes per tick while fiber is suspended already handles timeouts while waiting
* feat: broaden symfony/http-client dependency to support Symfony 5.4 to 8.0
* Update examples/client/README.md
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* Update examples/client/README.md
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* refactor: remove outgoing message queue from session and simplify transport send method to directly dispatch messages.
* refactor: Replace ClientSession with ClientState for clearer intent on runtime state management
* refactor: rename connectAndInitialize to connect for consistency
* chore: cs fix
* chore: use SamplingCallbackInterface instead of a closure for sampling request handler
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* 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
* fix: standardize error handling across handlers with MCP specification compliance
* Update mcp-elements.md
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* docs: clarify error handling behavior for all element types
* docs: remove unnecessary whitespace in mcp-elements.md
* fix: simplify exception signatures to accept simple messages
* refactor: use specific exceptions in examples for better error handling
* feat: throw exceptions from reference provider instead of returning null
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* feat: make CORS headers configurable in StreamableHttpTransport
* docs: add CORS configuration documentation for HTTP transport
* refactor: streamline request creation and transport initialization in HTTP client example
* feat(server): add bidirectional client communication support
* fix(server): use correct session ID string conversion method
* fix: clean up docblocks for request handler methods in Builder
* fix: merge artifacts
* feat: replace connect/listen flow with run lifecycle
* feat(transport): add phpstan generics for typed transport returns
* refactor: standardize variable naming for MCP server instances in transport handling
* test: remove unnecessary phpstan-ignore annotation in DocBlockTestFixture
* docs: add more about building servers and updating front readme
* Overhaul documentation structure and content
* fix: remove redundant emoji on docs
* Remove composer install --dev hint
* Add linebreak to make it readable in IDE
* rebase after example renaming
---------
Co-authored-by: Kyrian Obikwelu <koshnawaza@gmail.com>
* refactor: integrate cache parameter into setDiscovery() method
- Add cache as 4th parameter to setDiscovery()
- Rename $cache to $discoveryCache for clarity
- Remove separate setCache() method
- Update example to use new API
* docs: update discovery caching documentation to use new API
- Update examples to use cache parameter in setDiscovery() method
- Remove references to separate setCache() method calls
* feat: implement discovery caching with state-based approach
- Add DiscoveryState class to encapsulate discovered MCP capabilities
- Add exportDiscoveryState and importDiscoveryState methods to Registry
- Modify Discoverer to return DiscoveryState instead of void
- Create CachedDiscoverer decorator for caching discovery results
- Add importDiscoveryState method to ReferenceRegistryInterface
- Update ServerBuilder to use caching with withCache() method
- Update tests to work with new state-based approach
- Add example demonstrating cached discovery functionality
- Add PSR-16 SimpleCache and Symfony Cache dependencies
* docs: add comprehensive discovery caching documentation
- Add detailed documentation explaining discovery caching architecture
- Include usage examples for different cache implementations
- Document performance benefits and best practices
- Add troubleshooting guide and migration instructions
- Include complete API reference for all caching components
- Fix PHPStan issues by regenerating baseline
- Apply PHP CS Fixer formatting to all new files
* refactor: address reviewer feedback and clean up discovery caching
- Make DiscoveryState class final
- Cache DiscoveryState objects directly instead of arrays (no serialization needed)
- Rename exportDiscoveryState/importDiscoveryState to getDiscoveryState/setDiscoveryState
- Add getDiscoveryState method to ReferenceRegistryInterface
- Remove TTL parameter from CachedDiscoverer (no expiration by default)
- Remove unused methods from DiscoveryState (toArray, fromArray, merge)
- Simplify ServerBuilder to handle decoration internally
- Make Discoverer.applyDiscoveryState() internal (no longer public API)
- Simplify documentation to focus on user perspective
- Remove unnecessary development comments
- Update all tests to work with new architecture
- All tests pass, PHPStan clean, code formatting applied
* refactor: clean up comments and formatting in server.php example
* refactor: improve code formatting and consistency in discovery classes and example server
* Fix method names in cached discovery example
- Change withServerInfo() to setServerInfo()
- Change withDiscovery() to setDiscovery()
- Change withLogger() to setLogger()
- Fixes PHPStan static analysis errors
* refactor: update method names in ServerBuilder for consistency
- Change withCache() to setCache() in ServerBuilder
- Update example and documentation to reflect method name changes
- Ensure consistency across caching implementation in examples and documentation
* refactor: reorganize examples and fix PHPStan baseline
- Move cached discovery example from examples/10 to examples/09
- Update composer.json autoload-dev namespace mapping
- Fix PHPStan baseline by removing invalid entries for non-existent files
- Update server.php to follow proper example pattern with logging and lifecycle
* fix: correct formatting in server.php
- Remove ToolChain, ResourceChain, PromptChain classes
- Remove Collection/Identifier/Metadata interfaces (only used by old Chains)
- Remove ToolCollectionInterface (unused)
- Delete obsolete examples 09-standalone-cli and 10-simple-http-transport
- Fix STDERR handling in bootstrap.php for web environments
- Clean up CHANGELOG.md
* feat(server): Rework transport architecture and add StreamableHttpTransport
- `Server::connect()` no longer contains a processing loop.
- `TransportInterface` is updated with `setMessageHandler()` and `listen()`.
- `StdioTransport` is updated to implement the new interface.
- A new, minimal `StreamableHttpTransport` is added for stateless HTTP.
* refactor(server): use event-driven message handling
* feat(server): Introduce a formal session management system
* fix: ensure session elements are preserved when building server (regression from #46)
* refactor: consolidate HTTP example to use shared dependencies
* feat(server): Enhance message handling with session support
- Updated `TransportInterface` to use `onMessage` for handling incoming messages with session IDs.
- Refactored `Server`, `Handler`, and transport classes to accommodate session management using `Uuid`.
- Introduced methods for creating sessions with auto-generated and specific UUIDs in `SessionFactory` and `SessionFactoryInterface`.
* feat(server): Integrate session management in message handling
- Added session support to the `Server` and `Handler` classes, allowing for session data to be managed during message processing.
- Updated `TransportInterface` to include session context in the `send` method.
- Refactored various request handlers to utilize session information, ensuring proper session handling for incoming requests.
- Introduced a file-based session store for persistent session data management
* feat: Update session builder method to use set* instead of with*
* feat: Fix test compatibility with new session management architecture
* chore: apply code style fixes
* fix: remove deprecated SSE transport and resolve PHPStan issues
* refactor: Separate Registry concerns following SOLID principles [WIP]
- Extract ReferenceProvider and ReferenceRegistryInterface interfaces
- Create DefaultToolExecutor with ReferenceHandlerInterface
- Remove execution responsibility from Registry class
- Enable custom handler and executor implementations
* refactor: implement SOLID principles with separated execution concerns
* Create DefaultResourceReader, DefaultPromptGetter
* Refactor JsonRpc Handler and RequestHandlers to use dedicated executors
* Update ServerBuilder to support custom executors via dependency injection
* chore: remove extra comments
* feat: introduce DispatchableRegistry for enhanced tool and resource management
* refactor: use proper interfaces
* refactor: implement HandlerInterface for improved abstraction and flexibility
* test: add unit tests for DispatchableRegistry and Registry classes
* refactor: cover with unit tests Resource reader, Prompt getter and Tool executor
* cs fix
* phpstan fix
* test: add unit tests for CallToolHandler, GetPromptHandler, PingHandler, and ReadResourceHandler
* refactor: revert Handler
* chore: remove style guide for tests
* refactor: remove "Default" prefix from classes
* refactor: remove DispatchableRegistry
* refactor: use package specific exception classes
* refactor: remove DispatchableRegistry
* refactor: add logger support to PromptGetter and ResourceReader classes
* Update src/Capability/Prompt/PromptGetter.php
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
* refactor: Use FQN for Resource class to avoid cs-fixer misinterpreting it as `resource`
* refactor: rename ToolExecutor to ToolCaller and related classes for clarity and consistency
* refactor: add missed docblock
* refactor: rename ToolExecutor references to ToolCaller
* refactor: rename ToolCallerTest property and variable references
* cs fix
* ignore some phpstan errors
---------
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
- Fix grammar in doc/index.rst: "There two types" → "There are two types"
- Fix grammar in doc/index.rst: "if non of" → "if none of"
- Fix grammar in phpstan.dist.neon: "This errors" → "These errors"
- Fix grammar in examples/09-standalone-cli/README.md: "test add" → "test by adding"
- Fix sentence structure in examples/README.md for better readability
Signed-off-by: Oskar Stark <oskarstark@googlemail.com>
