refactor: standardise tool responses with ToolResult DTO #17

New issue

Open

opened 2026-02-21 01:02:57 +00:00 by Clotho · 0 comments

Clotho commented

2026-02-21 01:02:57 +00:00

Member

Summary

MCP tools return Response::text(json_encode($results)) with inconsistently structured data. Different tools return different shapes, making client-side handling unreliable.

Problem

No consistent envelope for tool responses
Error responses vary per tool
Metadata (row count, truncation warnings, timing) included inconsistently
Difficult to add cross-cutting response enrichment

Proposed Solution

Create a ToolResult DTO:

class ToolResult
{
    public function __construct(
        public readonly mixed $data,
        public readonly ?ToolResultMeta $meta = null,
        public readonly ?string $error = null,
    ) {}
}

class ToolResultMeta
{
    public function __construct(
        public readonly ?int $rowCount = null,
        public readonly bool $truncated = false,
        public readonly ?float $durationMs = null,
        public readonly ?string $tier = null,
    ) {}
}

Files

src/Mcp/DTO/ToolResult.php (new)
src/Mcp/DTO/ToolResultMeta.php (new)
All tool files in src/Mcp/Tools/

Notes

Also noted in TODO.md. Estimated effort: 3-4 hours.

## Summary MCP tools return `Response::text(json_encode($results))` with inconsistently structured data. Different tools return different shapes, making client-side handling unreliable. ## Problem - No consistent envelope for tool responses - Error responses vary per tool - Metadata (row count, truncation warnings, timing) included inconsistently - Difficult to add cross-cutting response enrichment ## Proposed Solution Create a `ToolResult` DTO: ```php class ToolResult { public function __construct( public readonly mixed $data, public readonly ?ToolResultMeta $meta = null, public readonly ?string $error = null, ) {} } class ToolResultMeta { public function __construct( public readonly ?int $rowCount = null, public readonly bool $truncated = false, public readonly ?float $durationMs = null, public readonly ?string $tier = null, ) {} } ``` ## Files - `src/Mcp/DTO/ToolResult.php` (new) - `src/Mcp/DTO/ToolResultMeta.php` (new) - All tool files in `src/Mcp/Tools/` ## Notes Also noted in TODO.md. Estimated effort: 3-4 hours.