Skip to content

Commit 8985be6

Browse files
pronskiychr-hertel
pronskiy
and
chr-hertel
authored
Add roadmap to readme (#20)
* Update README.md Add roadmap Add a basic example Fix default NullLogger() in ServerBuilder * Update README.md Update intro Add roadmap Add a basic example Fix default NullLogger() in ServerBuilder Add Credits * Update src/Server/ServerBuilder.php Co-authored-by: Christopher Hertel <[email protected]> * Fix code review comments --------- Co-authored-by: Christopher Hertel <[email protected]>
1 parent 4812b56 commit 8985be6

File tree

2 files changed

+115
-10
lines changed

2 files changed

+115
-10
lines changed

‎README.md‎

Lines changed: 108 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,145 @@
11
# MCP PHP SDK
22

3+
The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers in PHP.
4+
35
> [!IMPORTANT]
4-
> Currently we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and
5-
> [PHP-MCP](https://github.com/php-mcp) components. Not all code paths are fully tested, complete or this package
6+
> Currently, we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and
7+
> [PHP-MCP](https://github.com/php-mcp) components. Not all code paths are fully tested, complete, or this package
68
> may contain duplicate functionality or dead code.
9+
>
710
> If you want to help us stabilize the SDK, please see the
811
> [issue tracker](https://github.com/modelcontextprotocol/php-sdk/issues).
912
10-
Low-level SDK implementation of the Model Context Protocol (MCP) in PHP.
11-
12-
This project is a collaboration between the [PHP Foundation](https://thephp.foundation/) and the
13+
This project is a collaboration between [the PHP Foundation](https://thephp.foundation/) and the
1314
[Symfony project](https://symfony.com/). It adopts development practices and standards from the Symfony project,
1415
including [Coding Standards](https://symfony.com/doc/current/contributing/code/standards.html) and the
1516
[Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html).
1617

1718
Until the first major release, this SDK is considered
1819
[experimental](https://symfony.com/doc/current/contributing/code/experimental.html).
1920

21+
## 🚧 Roadmap
22+
23+
Features
24+
- [x] bring back php-mcp examples
25+
- [ ] Glue handler, registry and reference handlers
26+
- [ ] Revive `ServerBuilder`
27+
- [ ] Revive transports
28+
- [ ] Streamable Transport https://github.com/modelcontextprotocol/php-sdk/issues/7
29+
- [ ] Http/SSE-based Transport https://github.com/modelcontextprotocol/php-sdk/issues/8
30+
- [ ] Support pagination
31+
- [ ] Support Schema validation
32+
- [ ] Support Multiple Versions of MCP Specification https://github.com/modelcontextprotocol/php-sdk/issues/14
33+
- [ ] (Re-)Implement missing Notification & Request Handlers https://github.com/modelcontextprotocol/php-sdk/issues/9
34+
35+
---
36+
37+
Examples working
38+
- [x] 01-discovery-stdio-calculator
39+
- [ ] 02-discovery-http-userprofile
40+
- [x] 03-manual-registration-stdio
41+
- [ ] 04-combined-registration-http
42+
- [ ] 05-stdio-env-variables
43+
- [ ] 06-custom-dependencies-stdio
44+
- [ ] 07-complex-tool-schema-http
45+
- [ ] 08-schema-showcase-streamable
46+
- [ ] 09-standalone-cli
47+
2048
## Installation
2149

2250
```bash
2351
composer require mcp/sdk
2452
```
2553

54+
## ⚡ Quick Start: Stdio Server with Discovery
55+
56+
This example demonstrates the most common usage pattern - a `stdio` server using attribute discovery.
57+
58+
**1. Define Your MCP Elements**
59+
60+
Create `src/CalculatorElements.php`:
61+
62+
```php
63+
<?php
64+
65+
namespace App;
66+
67+
use PhpMcp\Server\Attributes\McpTool;
68+
use PhpMcp\Server\Attributes\Schema;
69+
70+
class CalculatorElements
71+
{
72+
#[McpTool(name: 'add_numbers')]
73+
public function add(int $a, int $b): int
74+
{
75+
return $a + $b;
76+
}
77+
}
78+
```
79+
80+
**2. Create the Server Script**
81+
82+
Create `mcp-server.php`:
83+
84+
```php
85+
#!/usr/bin/env php
86+
<?php
87+
88+
declare(strict_types=1);
89+
90+
require_once __DIR__ . '/vendor/autoload.php';
91+
92+
use Mcp\Server;
93+
use Mcp\Server\Transport\StdioTransport;
94+
95+
Server::make()
96+
->withServerInfo('Stdio Calculator', '1.1.0', 'Basic Calculator over STDIO transport.')
97+
->withDiscovery(__DIR__, ['.'])
98+
->build()
99+
->connect(new StdioTransport());
100+
```
101+
102+
**3. Configure Your MCP Client**
103+
104+
Add to your client configuration (e.g., `mcp.json`):
105+
106+
```json
107+
{
108+
"mcpServers": {
109+
"php-calculator": {
110+
"command": "php",
111+
"args": ["/absolute/path/to/your/mcp-server.php"]
112+
}
113+
}
114+
}
115+
```
116+
117+
**4. Test the Server**
118+
119+
Your AI assistant can now call:
120+
- `add_numbers` - Add two integers
121+
26122
## Documentation
27123

28124
- [SDK documentation](doc/index.rst)
29125
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
30126
- [Model Context Protocol specification](https://spec.modelcontextprotocol.io)
31127
- [Officially supported servers](https://github.com/modelcontextprotocol/servers)
32128

129+
## Examples of MCP Tools that use this SDK
130+
131+
- https://github.com/pronskiy/mcp
132+
33133
## Contributing
34134

35135
We are passionate about supporting contributors of all levels of experience and would love to see you get involved in
36136
the project. See the [contributing guide](CONTRIBUTING.md) to get started before you
37137
[report issues](https://github.com/modelcontextprotocol/php-sdk/issues) and
38138
[send pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls).
39139

140+
## Credits
141+
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.
142+
40143
## License
41144

42145
This project is licensed under the MIT License - see the LICENSE file for details.

‎src/Server/ServerBuilder.php‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -216,19 +216,21 @@ public function withPrompt(callable|array|string $handler, ?string $name = null,
216216
*/
217217
public function build(): Server
218218
{
219+
$logger = $this->logger ?? new NullLogger();
220+
219221
$container = $this->container ?? new Container();
220-
$registry = new Registry(new ReferenceHandler($container), $this->eventDispatcher, $this->logger);
222+
$registry = new Registry(new ReferenceHandler($container), $this->eventDispatcher, $logger);
221223

222-
$this->registerManualElements($registry, $this->logger);
224+
$this->registerManualElements($registry, $logger);
223225

224226
if (null !== $this->discoveryBasePath) {
225-
$discovery = new Discoverer($registry, $this->logger);
227+
$discovery = new Discoverer($registry, $logger);
226228
$discovery->discover($this->discoveryBasePath, $this->discoveryScanDirs, $this->discoveryExcludeDirs);
227229
}
228230

229231
return new Server(
230-
Handler::make($registry, $this->serverInfo, $this->logger),
231-
$this->logger,
232+
Handler::make($registry, $this->serverInfo, $logger),
233+
$logger,
232234
);
233235
}
234236

0 commit comments

Comments
 (0)