Skip to content

Commit 7f44d22

Browse files
CodeWithKyrianCodeWithKyrian
committed
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.
1 parent b1e54f1 commit 7f44d22

File tree

11 files changed

+462
-58
lines changed

11 files changed

+462
-58
lines changed

‎composer.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@
2424
"phpdocumentor/reflection-docblock": "^5.6",
2525
"psr/container": "^2.0",
2626
"psr/event-dispatcher": "^1.0",
27+
"psr/http-factory": "^1.1",
28+
"psr/http-message": "^2.0",
2729
"psr/log": "^1.0 || ^2.0 || ^3.0",
2830
"symfony/finder": "^6.4 || ^7.3",
2931
"symfony/uid": "^6.4 || ^7.3"

‎examples/01-discovery-stdio-calculator/server.php‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,25 @@
1010
* file that was distributed with this source code.
1111
*/
1212

13-
require_once dirname(__DIR__).'/bootstrap.php';
13+
require_once dirname(__DIR__) . '/bootstrap.php';
1414
chdir(__DIR__);
1515

1616
use Mcp\Server;
1717
use Mcp\Server\Transport\StdioTransport;
1818

1919
logger()->info('Starting MCP Stdio Calculator Server...');
2020

21-
Server::make()
22-
->setServerInfo('Stdio Calculator', '1.1.0', 'Basic Calculator over STDIO transport.')
23-
->setContainer(container())
24-
->setLogger(logger())
25-
->setDiscovery(__DIR__, ['.'])
26-
->build()
27-
->connect(new StdioTransport(logger: logger()));
21+
$server = Server::make()
22+
->withServerInfo('Stdio Calculator', '1.1.0', 'Basic Calculator over STDIO transport.')
23+
->withContainer(container())
24+
->withLogger(logger())
25+
->withDiscovery(__DIR__, ['.'])
26+
->build();
27+
28+
$transport = new StdioTransport(logger: logger());
29+
30+
$server->connect($transport);
31+
32+
$transport->listen();
2833

2934
logger()->info('Server listener stopped gracefully.');

‎examples/10-simple-http-transport/.gitignore‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Composer dependencies
2+
/vendor/
3+
4+
# Composer lock file (can be regenerated with composer install)
5+
/composer.lock
6+
7+
# PHP error logs and cache files
8+
*.log
9+
/error_log
10+
/cache/
11+
/tmp/
12+
13+
# macOS system files
14+
.DS_Store
15+
.AppleDouble
16+
.LSOverride
17+
Icon
18+
19+
# Windows system files
20+
Thumbs.db
21+
ehthumbs.db
22+
Desktop.ini
23+
24+
# Linux system files
25+
*~
26+
27+
# IDE and editor files
28+
.vscode/
29+
.idea/
30+
*.swp
31+
*.swo
32+
*~
33+
34+
# Environment files (may contain sensitive data)
35+
.env
36+
.env.local
37+
.env.*.local
38+
39+
# Temporary files
40+
*.tmp
41+
*.temp
42+
43+
# Build and distribution files
44+
/build/
45+
/dist/
46+
47+
# Node modules (if any frontend assets are added later)
48+
/node_modules/
49+
50+
# Test coverage reports
51+
/coverage/
52+
/phpunit.xml
53+
54+
# PHPStan cache
55+
/.phpstan.cache

‎examples/10-simple-http-transport/README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# HTTP MCP Server Example
2+
3+
This example demonstrates how to use the MCP SDK with HTTP transport using the StreamableHttpTransport. It provides a complete HTTP-based MCP server that can handle JSON-RPC requests over HTTP POST.
4+
5+
## Installation
6+
7+
```bash
8+
cd /path/to/your/project/examples/10-simple-http-transport
9+
composer update
10+
```
11+
12+
## Usage
13+
14+
### As HTTP Server
15+
16+
You can use this with any HTTP server or framework that can proxy requests to PHP:
17+
18+
```bash
19+
# Using PHP built-in server (for testing)
20+
php -S localhost:8000
21+
22+
# Or with Apache/Nginx, point your web server to serve this directory
23+
```
24+
25+
### With MCP Inspector
26+
27+
Run with the MCP Inspector for testing:
28+
29+
```bash
30+
npx @modelcontextprotocol/inspector http://localhost:8000
31+
```
32+
33+
## API
34+
35+
The server accepts JSON-RPC 2.0 requests via HTTP POST.
36+
37+
### Available Endpoints
38+
39+
- **Tools**: `current_time`, `calculate`
40+
- **Resources**: `info://server/status`, `config://app/settings`
41+
- **Prompts**: `greet`
42+
43+
### Example Request
44+
45+
```bash
46+
curl -X POST http://localhost:8000 \
47+
-H "Content-Type: application/json" \
48+
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "current_time"}}'
49+
```

‎examples/10-simple-http-transport/composer.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "mcp/http-server-example",
3+
"description": "An example application for HTTP",
4+
"license": "MIT",
5+
"type": "project",
6+
"authors": [
7+
{
8+
"name": "Kyrian Obikwelu",
9+
"email": "[email protected]"
10+
}
11+
],
12+
"require": {
13+
"php": ">=8.1",
14+
"mcp/sdk": "@dev",
15+
"nyholm/psr7": "^1.8",
16+
"nyholm/psr7-server": "^1.1",
17+
"laminas/laminas-httphandlerrunner": "^2.12"
18+
},
19+
"minimum-stability": "stable",
20+
"autoload": {
21+
"psr-4": {
22+
"App\\": "src/"
23+
}
24+
},
25+
"repositories": [
26+
{
27+
"type": "path",
28+
"url": "../../"
29+
}
30+
]
31+
}

‎examples/10-simple-http-transport/index.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
require_once __DIR__ . '/vendor/autoload.php';
4+
5+
use Mcp\Server;
6+
use Mcp\Server\Transport\StreamableHttpTransport;
7+
use Nyholm\Psr7\Factory\Psr17Factory;
8+
use Nyholm\Psr7Server\ServerRequestCreator;
9+
use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
10+
11+
$psr17Factory = new Psr17Factory();
12+
$creator = new ServerRequestCreator($psr17Factory, $psr17Factory, $psr17Factory, $psr17Factory);
13+
14+
$request = $creator->fromGlobals();
15+
16+
$server = Server::make()
17+
->withServerInfo('HTTP MCP Server', '1.0.0')
18+
->withDiscovery(__DIR__, ['src'])
19+
->build();
20+
21+
$transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
22+
23+
$server->connect($transport);
24+
25+
$response = $transport->listen();
26+
27+
(new SapiEmitter())->emit($response);

‎examples/10-simple-http-transport/src/McpElements.php‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<?php
2+
3+
namespace App;
4+
5+
use Mcp\Capability\Attribute\McpPrompt;
6+
use Mcp\Capability\Attribute\McpResource;
7+
use Mcp\Capability\Attribute\McpTool;
8+
9+
class McpElements
10+
{
11+
public function __construct() {}
12+
13+
/**
14+
* Get the current server time
15+
*/
16+
#[McpTool(name: 'current_time')]
17+
public function getCurrentTime(string $format = 'Y-m-d H:i:s'): string
18+
{
19+
try {
20+
return date($format);
21+
} catch (\Exception $e) {
22+
return date('Y-m-d H:i:s'); // fallback
23+
}
24+
}
25+
26+
/**
27+
* Calculate simple math operations
28+
*/
29+
#[McpTool(name: 'calculate')]
30+
public function calculate(float $a, float $b, string $operation): float|string
31+
{
32+
return match (strtolower($operation)) {
33+
'add', '+' => $a + $b,
34+
'subtract', '-' => $a - $b,
35+
'multiply', '*' => $a * $b,
36+
'divide', '/' => $b != 0 ? $a / $b : 'Error: Division by zero',
37+
default => 'Error: Unknown operation. Use: add, subtract, multiply, divide'
38+
};
39+
}
40+
41+
/**
42+
* Server information resource
43+
*/
44+
#[McpResource(
45+
uri: 'info://server/status',
46+
name: 'server_status',
47+
description: 'Current server status and information',
48+
mimeType: 'application/json'
49+
)]
50+
public function getServerStatus(): array
51+
{
52+
return [
53+
'status' => 'running',
54+
'timestamp' => time(),
55+
'version' => '1.0.0',
56+
'transport' => 'HTTP',
57+
'uptime' => time() - $_SERVER['REQUEST_TIME']
58+
];
59+
}
60+
61+
/**
62+
* Configuration resource
63+
*/
64+
#[McpResource(
65+
uri: 'config://app/settings',
66+
name: 'app_config',
67+
description: 'Application configuration settings',
68+
mimeType: 'application/json'
69+
)]
70+
public function getAppConfig(): array
71+
{
72+
return [
73+
'debug' => $_SERVER['DEBUG'] ?? false,
74+
'environment' => $_SERVER['APP_ENV'] ?? 'production',
75+
'timezone' => date_default_timezone_get(),
76+
'locale' => 'en_US'
77+
];
78+
}
79+
80+
/**
81+
* Greeting prompt
82+
*/
83+
#[McpPrompt(
84+
name: 'greet',
85+
description: 'Generate a personalized greeting message'
86+
)]
87+
public function greetPrompt(string $firstName = 'World', string $timeOfDay = 'day'): array
88+
{
89+
$greeting = match (strtolower($timeOfDay)) {
90+
'morning' => 'Good morning',
91+
'afternoon' => 'Good afternoon',
92+
'evening', 'night' => 'Good evening',
93+
default => 'Hello'
94+
};
95+
96+
return [
97+
'role' => 'user',
98+
'content' => "# {$greeting}, {$firstName}!\n\nWelcome to our MCP HTTP Server example. This demonstrates how to use the Model Context Protocol over HTTP transport."
99+
];
100+
}
101+
}

‎src/Server.php‎

Lines changed: 17 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,7 @@ final class Server
2525
public function __construct(
2626
private readonly Handler $jsonRpcHandler,
2727
private readonly LoggerInterface $logger = new NullLogger(),
28-
) {
29-
}
28+
) {}
3029

3130
public static function make(): ServerBuilder
3231
{
@@ -40,33 +39,26 @@ public function connect(TransportInterface $transport): void
4039
'transport' => $transport::class,
4140
]);
4241

43-
while ($transport->isConnected()) {
44-
foreach ($transport->receive() as $message) {
45-
if (null === $message) {
46-
continue;
47-
}
48-
49-
try {
50-
foreach ($this->jsonRpcHandler->process($message) as $response) {
51-
if (null === $response) {
52-
continue;
53-
}
42+
$transport->setMessageHandler(function (string $rawMessage) use ($transport) {
43+
$this->handleMessage($rawMessage, $transport);
44+
});
45+
}
5446

55-
$transport->send($response);
56-
}
57-
} catch (\JsonException $e) {
58-
$this->logger->error('Failed to encode response to JSON.', [
59-
'message' => $message,
60-
'exception' => $e,
61-
]);
47+
private function handleMessage(string $rawMessage, TransportInterface $transport): void
48+
{
49+
try {
50+
foreach ($this->jsonRpcHandler->process($rawMessage) as $response) {
51+
if (null === $response) {
6252
continue;
6353
}
64-
}
6554

66-
usleep(1000);
55+
$transport->send($response);
56+
}
57+
} catch (\JsonException $e) {
58+
$this->logger->error('Failed to encode response to JSON.', [
59+
'message' => $rawMessage,
60+
'exception' => $e,
61+
]);
6762
}
68-
69-
$transport->close();
70-
$this->logger->info('Transport closed');
7163
}
7264
}

0 commit comments

Comments
 (0)