From 70c229737398ba133c4b656f1d76e47b802a1832 Mon Sep 17 00:00:00 2001 From: Roman Pronskiy Date: Thu, 4 Sep 2025 13:03:13 +0200 Subject: [PATCH 1/4] Update README.md Add roadmap Add a basic example Fix default NullLogger() in ServerBuilder --- README.md | 111 +++++++++++++++++++++++++++++++++-- src/Server/ServerBuilder.php | 6 +- 2 files changed, 112 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 06dcb49c..7a5967bb 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ # MCP PHP SDK +The official PHP SDK for the Model Context Protocol. Enables PHP applications, services, and libraries to implement and interact with MCP clients and servers. + > [!IMPORTANT] -> Currently we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and +> Currently, we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and > [PHP-MCP](https://github.com/php-mcp) components. Not all code paths are fully tested, complete or this package > may contain duplicate functionality or dead code. +> > If you want to help us stabilize the SDK, please see the > [issue tracker](https://github.com/modelcontextprotocol/php-sdk/issues). -Low-level SDK implementation of the Model Context Protocol (MCP) in PHP. - -This project is a collaboration between the [PHP Foundation](https://thephp.foundation/) and the +This project is a collaboration between [the PHP Foundation](https://thephp.foundation/) and the [Symfony project](https://symfony.com/). It adopts development practices and standards from the Symfony project, including [Coding Standards](https://symfony.com/doc/current/contributing/code/standards.html) and the [Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html). @@ -17,12 +18,107 @@ including [Coding Standards](https://symfony.com/doc/current/contributing/code/s Until the first major release, this SDK is considered [experimental](https://symfony.com/doc/current/contributing/code/experimental.html). +## 🚧 Roadmap + +Features +- [x] bring back php-mcp examples +- [ ] Glue handler, registry and reference handlers +- [ ] Revive `ServerBuilder` +- [ ] Revive transports + - [ ] Streamable Transport https://github.com/modelcontextprotocol/php-sdk/issues/7 + - [ ] Http/SSE-based Transport https://github.com/modelcontextprotocol/php-sdk/issues/8 +- [ ] Support pagination +- [ ] Support Schema validation +- [ ] Support Multiple Versions of MCP Specification https://github.com/modelcontextprotocol/php-sdk/issues/14 +- [ ] (Re-)Implement missing Notification & Request Handlers https://github.com/modelcontextprotocol/php-sdk/issues/9 + +--- + +Examples working +- [x] 01-discovery-stdio-calculator +- [ ] 02-discovery-http-userprofile +- [x] 03-manual-registration-stdio +- [ ] 04-combined-registration-http +- [ ] 05-stdio-env-variables +- [ ] 06-custom-dependencies-stdio +- [ ] 07-complex-tool-schema-http +- [ ] 08-schema-showcase-streamable +- [ ] 09-standalone-cli + ## Installation ```bash composer require mcp/sdk ``` +## ⚡ Quick Start: Stdio Server with Discovery + +This example demonstrates the most common usage pattern - a `stdio` server using attribute discovery. + +**1. Define Your MCP Elements** + +Create `src/CalculatorElements.php`: + +```php +withServerInfo('Stdio Calculator', '1.1.0', 'Basic Calculator over STDIO transport.') + ->withDiscovery(__DIR__, ['.']) + ->build() + ->connect(new StdioTransport()); +``` + +**3. Configure Your MCP Client** + +Add to your client configuration (e.g., `mcp.json`): + +```json +{ + "mcpServers": { + "php-calculator": { + "command": "php", + "args": ["/absolute/path/to/your/mcp-server.php"] + } + } +} +``` + +**4. Test the Server** + +Your AI assistant can now call: +- `add_numbers` - Add two integers + ## Documentation - [SDK documentation](doc/index.rst) @@ -30,6 +126,10 @@ composer require mcp/sdk - [Model Context Protocol specification](https://spec.modelcontextprotocol.io) - [Officially supported servers](https://github.com/modelcontextprotocol/servers) +## Examples of MCP Tools that use this SDK + +- https://github.com/pronskiy/mcp + ## Contributing We are passionate about supporting contributors of all levels of experience and would love to see you get involved in @@ -37,6 +137,9 @@ the project. See the [contributing guide](CONTRIBUTING.md) to get started before [report issues](https://github.com/modelcontextprotocol/php-sdk/issues) and [send pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls). +## Credits +The starting point for this SDK was [PHP-MCP](https://github.com/php-mcp/server) project, initiated by [Kyrian Obikwelu](https://github.com/CodeWithKyrian). We are grateful for the work done by Kyrian and other contributors to that repository, which created a solid foundation for this SDK. + ## License This project is licensed under the MIT License - see the LICENSE file for details. diff --git a/src/Server/ServerBuilder.php b/src/Server/ServerBuilder.php index 189d14b7..102c1368 100644 --- a/src/Server/ServerBuilder.php +++ b/src/Server/ServerBuilder.php @@ -134,7 +134,7 @@ public function withInstructions(?string $instructions): self /** * Provides a PSR-3 logger instance. Defaults to NullLogger. */ - public function withLogger(LoggerInterface $logger): self + public function withLogger(LoggerInterface $logger = new NullLogger()): self { $this->logger = $logger; @@ -216,6 +216,10 @@ public function withPrompt(callable|array|string $handler, ?string $name = null, */ public function build(): Server { + if (null === $this->logger) { + $this->withLogger(); + } + $container = $this->container ?? new Container(); $registry = new Registry(new ReferenceHandler($container), $this->eventDispatcher, $this->logger); From ff48241c41ad59f7f88eb416167ed578c96431f3 Mon Sep 17 00:00:00 2001 From: Roman Pronskiy Date: Thu, 4 Sep 2025 13:20:02 +0200 Subject: [PATCH 2/4] Update README.md Update intro Add roadmap Add a basic example Fix default NullLogger() in ServerBuilder Add Credits --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7a5967bb..6b8bd15d 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # MCP PHP SDK -The official PHP SDK for the Model Context Protocol. Enables PHP applications, services, and libraries to implement and interact with MCP clients and servers. +The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers in PHP. Maintained by Symfony and The PHP Foundation. > [!IMPORTANT] > Currently, we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and -> [PHP-MCP](https://github.com/php-mcp) components. Not all code paths are fully tested, complete or this package +> [PHP-MCP](https://github.com/php-mcp) components. Not all code paths are fully tested, complete, or this package > may contain duplicate functionality or dead code. > > If you want to help us stabilize the SDK, please see the From 7364da491753b34f26dbb56a63cb0afd7895e7c8 Mon Sep 17 00:00:00 2001 From: Roman Pronskiy Date: Thu, 4 Sep 2025 16:23:21 +0300 Subject: [PATCH 3/4] Update src/Server/ServerBuilder.php Co-authored-by: Christopher Hertel --- src/Server/ServerBuilder.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/Server/ServerBuilder.php b/src/Server/ServerBuilder.php index 102c1368..3d75b27a 100644 --- a/src/Server/ServerBuilder.php +++ b/src/Server/ServerBuilder.php @@ -216,9 +216,7 @@ public function withPrompt(callable|array|string $handler, ?string $name = null, */ public function build(): Server { - if (null === $this->logger) { - $this->withLogger(); - } + $logger = $this->logger ?? new NullLogger(); $container = $this->container ?? new Container(); $registry = new Registry(new ReferenceHandler($container), $this->eventDispatcher, $this->logger); From 634adce3ce10574df10ca4327788a7067d83b672 Mon Sep 17 00:00:00 2001 From: Roman Pronskiy Date: Thu, 4 Sep 2025 15:27:37 +0200 Subject: [PATCH 4/4] Fix code review comments --- README.md | 2 +- src/Server/ServerBuilder.php | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6b8bd15d..a5bcb035 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # MCP PHP SDK -The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers in PHP. Maintained by Symfony and The PHP Foundation. +The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers in PHP. > [!IMPORTANT] > Currently, we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and diff --git a/src/Server/ServerBuilder.php b/src/Server/ServerBuilder.php index 3d75b27a..1f4808ed 100644 --- a/src/Server/ServerBuilder.php +++ b/src/Server/ServerBuilder.php @@ -134,7 +134,7 @@ public function withInstructions(?string $instructions): self /** * Provides a PSR-3 logger instance. Defaults to NullLogger. */ - public function withLogger(LoggerInterface $logger = new NullLogger()): self + public function withLogger(LoggerInterface $logger): self { $this->logger = $logger; @@ -219,18 +219,18 @@ public function build(): Server $logger = $this->logger ?? new NullLogger(); $container = $this->container ?? new Container(); - $registry = new Registry(new ReferenceHandler($container), $this->eventDispatcher, $this->logger); + $registry = new Registry(new ReferenceHandler($container), $this->eventDispatcher, $logger); - $this->registerManualElements($registry, $this->logger); + $this->registerManualElements($registry, $logger); if (null !== $this->discoveryBasePath) { - $discovery = new Discoverer($registry, $this->logger); + $discovery = new Discoverer($registry, $logger); $discovery->discover($this->discoveryBasePath, $this->discoveryScanDirs, $this->discoveryExcludeDirs); } return new Server( - Handler::make($registry, $this->serverInfo, $this->logger), - $this->logger, + Handler::make($registry, $this->serverInfo, $logger), + $logger, ); }