Refactor: Decouple Server Core, Enhance API & Introduce v2.0 Architecture #6
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Replaced Server->run() with Server->listen(Transport) for explicit binding. - Separated core Server logic from transport implementations (Stdio/Http). - Introduced ServerBuilder for configuration and ServerProtocolHandler for mediation. - Made attribute discovery an explicit step via Server->discover(). - Refined caching to only cache discovered elements, respecting manual registrations. - Replaced ConfigurationRepository with Configuration VO and Capabilities VO. - Simplified core component dependencies (Processor, Registry, ClientStateManager). - Renamed TransportState to ClientStateManager. - Renamed McpException to McpServerException and added specific exception types. - Updated transport implementations (StdioServerTransport, HttpServerTransport). - Improved default BasicContainer with simple auto-wiring. - Revised documentation (README) and examples to reflect new architecture.
…nents
- ServerBuilder no longer configures discovery paths or runs discovery automatically during build; discovery is now an explicit step via `Server->discover()`.
- `Server::discover()` now accepts path configurations, clears only discovered/cached elements (preserving manual ones), and saves only discovered elements to cache.
- `Registry` distinguishes between manually registered and discovered elements:
- Manual registrations take precedence over discovered/cached elements with the same identifier.
- Caching methods (`loadDiscoveredElementsFromCache`, `saveDiscoveredElementsToCache`, `clearDiscoveredElements`) now operate only on discovered elements.
- `ClientStateManager` constructor defaults to `ArrayCache` if no PSR-16 cache is provided, ensuring basic stateful functionality.
- `ClientStateManager` now stores client-requested log levels.
- `Processor` updated to use `ClientStateManager` for persisting client-requested log levels and relies on `Configuration` VO for server capabilities.
- `JsonRpc\Response` constructor and `fromArray` updated to correctly handle `null` IDs for error responses as per JSON-RPC 2.0 spec, fixing related TypeErrors.
- `StdioServerTransport` constructor now accepts optional input/output stream resources, improving testability and flexibility.
- `HttpServerTransport` POST message handling reverted to synchronous body reading (`getBody()->getContents()`) for reliability with current `react/http` behavior, resolving hangs.
- Corrected `Support\DocBlockParser` and `Support\Discoverer` constructors to directly accept `LoggerInterface` instead of `ContainerInterface`.
- Updated unit tests for `ServerBuilder`, `Server`, `Registry`, `ClientStateManager`, `StdioServerTransport`, `HttpServerTransport`, `ProtocolHandler`, and JSON-RPC classes to reflect architectural changes and improve reliability, including fixes for Mockery state and loop interactions.
- Renamed `Server::getProtocolHandler()` to `Server::getProtocol()` and updated relevant class names (`ProtocolHandler` to `Protocol`).
- Renamed `Server::isLoaded()` in Registry to `discoveryRanOrCached()`.
- Renamed examples and updated their internal scripts and documentation comments to reflect new server API and best practices.
- Added more examples to showcase other use cases of the library
- Enhanced error handling in Processor to provide more informative validation error messages. - Changed server listening address from '0.0.0.0' to '127.0.0.1' in example server scripts for improved clarity and compatibility. - Refined logging messages in HttpServerTransport for consistency and clarity.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR implements a comprehensive architectural refactoring of the package, establishing the foundation for
v2.0.0. The primary goals achieved are:Serverlogic from network/IO viaServerTransportInterface.ServerBuilder, explicit$server->listen(Transport),$server->getProtocol(), and on-demand$server->discover(...).ConfigurationRepositoryInterfacewithConfigurationandModel\CapabilitiesVOs. Simplified component dependencies and improved defaultBasicContainer.ClientStateManager(wasTransportState) now defaults toArrayCache.Registrycaching now applies only to discovered elements, prioritizing manual registrations.StdioServerTransport(custom streams, Windows STDIN/STDOUT fix) andHttpServerTransport(constructor for server params).formatinference fromSchemaGeneratorfor more predictable default schemas.Key Changes:
ServerBuilder,Configuration,Model\Capabilities,ServerTransportInterface,Protocol.Server,Registry,ClientStateManager,Processor, transport implementations.$server->discover().McpServerExceptionas base.SchemaGeneratorno longer infers stringformats.tools/callerror messages for schema validation failures.README.mdand all examples.Breaking Changes:
Yes, this is a significant refactoring with breaking changes to the public API, particularly around server instantiation (
ServerBuilder), running the server (listen), discovery (discover), and transport usage. These changes are necessary for thev2.0.0release and will be detailed in the release notes.Related Issues: