Add ToolSchema and StringType

Author: paulbalandan

src/Schema/Tool/ToolSchema/StringType.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus MCP SDK package.
+ *
+ * (c) 2025 John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Mcp\Schema\Tool\ToolSchema;
+
+/**
+ * The `string` type is used for validating strings/texts containing Unicode characters.
+ *
+ * @extends ToolSchema<string, array{
+ *   type: 'string',
+ *   description?: non-empty-string,
+ *   title?: non-empty-string,
+ *   minLength?: int<0, max>,
+ *   maxLength?: int<0, max>,
+ *   pattern?: non-empty-string,
+ *   default?: string
+ * }>
+ */
+final class StringType extends ToolSchema
+{
+    /**
+     * @var null|int<0, max>
+     */
+    private ?int $minLength = null;
+
+    /**
+     * @var null|int<0, max>
+     */
+    private ?int $maxLength = null;
+
+    /**
+     * @var null|non-empty-string
+     */
+    private ?string $pattern = null;
+
+    public function minLength(int $minLength): self
+    {
+        if ($minLength < 0) {
+            throw new \InvalidArgumentException('The minimum length must be a non-negative integer.');
+        }
+
+        $this->minLength = $minLength;
+
+        return $this;
+    }
+
+    public function maxLength(int $maxLength): self
+    {
+        if ($maxLength < 0) {
+            throw new \InvalidArgumentException('The maximum length must be a non-negative integer.');
+        }
+
+        $this->maxLength = $maxLength;
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string $pattern
+     */
+    public function pattern(string $pattern): self
+    {
+        set_error_handler(static function (int $errno, string $errstr): bool {
+            $errstr = str_replace('preg_match(): Compilation failed: ', '', $errstr);
+
+            throw new \InvalidArgumentException(\sprintf('Invalid regex pattern: %s', ucfirst($errstr)), $errno);
+        });
+
+        try {
+            preg_match(\sprintf('/%s/uD', $pattern), '');
+            $this->pattern = $pattern;
+        } finally {
+            restore_error_handler();
+        }
+
+        return $this;
+    }
+
+    #[\Override]
+    public function toArray(): array
+    {
+        if (isset($this->minLength, $this->maxLength) && $this->minLength > $this->maxLength) {
+            throw new \LogicException('The minimum length cannot be greater than the maximum length.');
+        }
+
+        if (isset($this->default, $this->minLength) && \strlen($this->default) < $this->minLength) {
+            throw new \LogicException('The default value length cannot be less than the minimum length.');
+        }
+
+        if (isset($this->default, $this->maxLength) && \strlen($this->default) > $this->maxLength) {
+            throw new \LogicException('The default value length cannot be greater than the maximum length.');
+        }
+
+        return array_filter([
+            'type' => 'string',
+            'description' => $this->description,
+            'title' => $this->title,
+            'minLength' => $this->minLength,
+            'maxLength' => $this->maxLength,
+            'pattern' => $this->pattern,
+            'default' => $this->default,
+        ], static fn(mixed $value): bool => null !== $value);
+    }
+}

src/Schema/Tool/ToolSchema/ToolSchema.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus MCP SDK package.
+ *
+ * (c) 2025 John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Mcp\Schema\Tool\ToolSchema;
+
+use Nexus\Mcp\Schema\Arrayable;
+
+/**
+ * A JSON schema object defining the expected parameters for the tool or the structure of the tool's output
+ * returned in the `structuredContent` field of a `CallToolResult`.
+ *
+ * @template T
+ * @template U of array<string, mixed>
+ *
+ * @implements Arrayable<U>
+ */
+abstract class ToolSchema implements \JsonSerializable, Arrayable
+{
+    /**
+     * @var null|non-empty-string
+     */
+    protected ?string $title = null;
+
+    /**
+     * @var null|non-empty-string
+     */
+    protected ?string $description = null;
+
+    /**
+     * @var null|T
+     */
+    protected mixed $default = null;
+
+    private bool $required = false;
+
+    /**
+     * @param non-empty-string $name
+     */
+    protected function __construct(
+        public readonly string $name,
+    ) {}
+
+    /**
+     * @param non-empty-string $name
+     */
+    public static function fromString(string $name): StringType
+    {
+        return new StringType($name);
+    }
+
+    /**
+     * @param non-empty-string $title
+     */
+    public function title(string $title): static
+    {
+        $this->title = $title;
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string $description
+     */
+    public function description(string $description): static
+    {
+        $this->description = $description;
+
+        return $this;
+    }
+
+    /**
+     * @param T $default
+     */
+    public function default(mixed $default): static
+    {
+        $this->default = $default;
+
+        return $this;
+    }
+
+    public function required(): static
+    {
+        $this->required = true;
+
+        return $this;
+    }
+
+    public function isRequired(): bool
+    {
+        return $this->required;
+    }
+
+    /**
+     * @return template-type<static, Arrayable, 'T'>
+     */
+    #[\Override]
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+}