Breaking Changes, Improve Documentation

[JordanDalton]

First, thank you again for creating this package. I'm a huge fan of what you've produced, even tweeted about it back in April and have built over 13 MCP servers with it. On that day you had just 6 stars. Then you went to around 60 or 80 almost overnight. Exciting times!

I noticed that v1.1.0 introduced a breaking change, particularly with the Tool Interface:

Here's v.1.0

<?php

namespace OPGG\LaravelMcpServer\Services\ToolService;

interface ToolInterface
{
    public function getName(): string;

    public function getDescription(): string;

    public function getInputSchema(): array;

    public function getAnnotations(): array;

    public function execute(array $arguments): mixed;
}

Here's v.1.1.0

<?php

namespace OPGG\LaravelMcpServer\Services\ToolService;

use OPGG\LaravelMcpServer\Enums\ProcessMessageType;

interface ToolInterface
{
    public function messageType(): ProcessMessageType;

    public function name(): string;

    public function description(): string;

    public function inputSchema(): array;

    public function annotations(): array;

    public function execute(array $arguments): mixed;
}

Typically, if you're introducing breaking changes you should go with a new version number, but what's most important is having some sort of documentation which mentions this. Fortunately, my test suite caught this when I went to test your new http stream support (very excited for this btw).

Please update your readme to mention about what the tools can do, e.g. annotations. Create a list of examples. Also, go over all existing documentation.

Once you do this you're going to 5x your adoption rate.

[jskorlol]

Thank you for using the package.

I sincerely apologize for not clearly documenting the changes made to support StreamableHttp.
Additionally, I believe the package was released with an incorrect version setting, which was my mistake.
I will carefully review the documentation again and revise it accordingly.

Thank you once again for using the package, and I will do my best to implement the remaining features provided by the existing protocol as soon as possible.

[kargnas]

@JordanDalton Thanks for all the support and feedback! 🙏 Really cool that you built 13 MCP servers with this package - that's exactly who we made this for. Your tweet in April was part of that growth!

You're totally right about the breaking changes in v1.1.0. Sorry for not making this clear enough at first. I just fixed this properly in the README now #18:

Breaking Changes Documentation

• Clear comparison between v1.0.x and v1.1.0
• Step-by-step migration guide with examples
• Auto migration tool: php artisan mcp:migrate-tools

Better Tool Documentation

I added a lot more docs:

• Complete ToolInterface breakdown with explanations
• MCP annotations following official spec (title, readOnlyHint, destructiveHint, etc.)
• Input schema best practices with JSON Schema examples
• Real examples and patterns

New Stuff You'll Like

• Auto migration tool for the old classes
• Better tool stub template with examples

The migration tool should handle most work for your existing tools.

Thanks for pushing us to improve the docs - you're right that clear migration is important for adoption. The package is much more enterprise-ready now because of feedback like yours.