puff / mcp-server

dev-main 2026-09-29 13:54 UTC

Requires

• php: ^8.2
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• puff/application: dev-main
• puff/console: dev-main
• puff/di: dev-main
• puff/http: dev-main
• puff/http-server: dev-main
• puff/pipeline: dev-main

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.0
• puff/config: dev-main

MIT

• php
• json-rpc
• mcp
• fiber
• puff
• model-context-protocol

Published on Packagist.org on 2026-09-29 13:55 UTC

README

puff/mcp-server exposes registered Puff services as a stateless Model Context Protocol server. It reuses puff/http-server for Streamable HTTP and puff/console for local stdio; it does not create a second socket server or store protocol sessions.

Install

composer require puff/mcp-server

Add an MCP listener to config/server.php when remote HTTP access is required:

return [
    [
        'type' => 'mcp',
        'addr' => '0.0.0.0:8120',
        'path' => '/mcp',
        'name' => 'My MCP Server', // Optional.
        'version' => '1.0.0', // Optional.
        'pipeline' => [
            // App\Pipeline\Auth::class,
        ],
    ],
];

Use an explicit authentication Pipeline before binding beyond loopback.

Tool

namespace App\Mcp;

use Puff\Mcp\Context;
use Puff\Mcp\Contract\Tool;

final class Clock implements Tool
{
    public static function name(): string
    {
        return 'clock';
    }

    public function description(): string
    {
        return 'Returns the current UTC time.';
    }

    public function schema(): array
    {
        return ['type' => 'object', 'properties' => []];
    }

    public function handle(array $arguments, Context $context): array
    {
        return ['content' => [['type' => 'text', 'text' => gmdate(DATE_ATOM)]]];
    }
}

Register it explicitly in an application provider:

use App\Mcp\Clock;
use Puff\Di\ServiceProvider;
use Puff\Mcp\Registry\Tools;

final class McpProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->make(Tools::class)->add(Clock::class);
    }
}

Add McpProvider::class to extra.puff.providers in the application composer.json.

Transports

./puff run
./puff mcp stdio

The HTTP endpoint accepts POST JSON requests at the configured path and requires:

Content-Type: application/json
MCP-Protocol-Version: 2026-07-28

The stdio transport uses one JSON-RPC message per input line and writes protocol responses only to standard output.

Scope

Implemented core methods are server/discover, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.

This component deliberately excludes legacy SSE, protocol sessions, background tasks, server-initiated messages, OAuth and automatic directory scanning. Use Puff Pipeline for authentication and Puff Job for asynchronous work.