Skip to content

Commit c8c85f5

Browse files
kargnaskargnas
authored
docs: extract tool migration guide (#86)
1 parent 6ba7454 commit c8c85f5

File tree

2 files changed

+115
-146
lines changed

2 files changed

+115
-146
lines changed

‎README.md‎

Lines changed: 1 addition & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -43,152 +43,7 @@ Version 1.5.0 focuses on structured tool output, richer prompt support, and impr
4343

4444
### Breaking Changes in v1.1.0 (May 2025)
4545

46-
Version 1.1.0 introduced a significant and breaking change to the `ToolInterface`. If you are upgrading from v1.0.x, you **must** update your tool implementations to conform to the new interface.
47-
48-
**Key Changes in `ToolInterface`:**
49-
50-
The `OPGG\LaravelMcpServer\Services\ToolService\ToolInterface` has been updated as follows:
51-
52-
1. **New Method Added:**
53-
54-
- `messageType(): ProcessMessageType`
55-
- This method is crucial for the new HTTP stream support and determines the type of message being processed.
56-
57-
2. **Method Renames:**
58-
- `getName()` is now `name()`
59-
- `getDescription()` is now `description()`
60-
- `getInputSchema()` is now `inputSchema()`
61-
- `getAnnotations()` is now `annotations()`
62-
63-
**How to Update Your Tools:**
64-
65-
### Automated Tool Migration for v1.1.0
66-
67-
To assist with the transition to the new `ToolInterface` introduced in v1.1.0, we've included an Artisan command that can help automate the refactoring of your existing tools:
68-
69-
```bash
70-
php artisan mcp:migrate-tools {path?}
71-
```
72-
73-
**What it does:**
74-
75-
This command will scan PHP files in the specified directory (defaults to `app/MCP/Tools/`) and attempt to:
76-
77-
1. **Identify old tools:** It looks for classes implementing the `ToolInterface` with the old method signatures.
78-
2. **Create Backups:** Before making any changes, it will create a backup of your original tool file with a `.backup` extension (e.g., `YourTool.php.backup`). If a backup file already exists, the original file will be skipped to prevent accidental data loss.
79-
3. **Refactor the Tool:**
80-
- Rename methods:
81-
- `getName()` to `name()`
82-
- `getDescription()` to `description()`
83-
- `getInputSchema()` to `inputSchema()`
84-
- `getAnnotations()` to `annotations()`
85-
- Add the new `messageType()` method, which will default to returning `ProcessMessageType::SSE`.
86-
- Ensure the `use OPGG\LaravelMcpServer\Enums\ProcessMessageType;` statement is present.
87-
88-
**Usage:**
89-
90-
After updating the `opgginc/laravel-mcp-server` package to v1.1.0 or later, if you have existing tools written for v1.0.x, it is highly recommended to run this command:
91-
92-
```bash
93-
php artisan mcp:migrate-tools
94-
```
95-
96-
If your tools are located in a directory other than `app/MCP/Tools/`, you can specify the path:
97-
98-
```bash
99-
php artisan mcp:migrate-tools path/to/your/tools
100-
```
101-
102-
The command will output its progress, indicating which files are being processed, backed up, and migrated. Always review the changes made by the tool. While it aims to be accurate, complex or unusually formatted tool files might require manual adjustments.
103-
104-
This tool should significantly ease the migration process and help you adapt to the new interface structure quickly.
105-
106-
### Manual Migration
107-
108-
If you prefer to migrate your tools manually, here's a comparison to help you adapt your existing tools:
109-
110-
**v1.0.x `ToolInterface`:**
111-
112-
```php
113-
<?php
114-
115-
namespace OPGG\LaravelMcpServer\Services\ToolService;
116-
117-
interface ToolInterface
118-
{
119-
public function getName(): string;
120-
public function getDescription(): string;
121-
public function getInputSchema(): array;
122-
public function getAnnotations(): array;
123-
public function execute(array $arguments): mixed;
124-
}
125-
```
126-
127-
**v1.1.0 `ToolInterface` (New):**
128-
129-
```php
130-
<?php
131-
132-
namespace OPGG\LaravelMcpServer\Services\ToolService;
133-
134-
use OPGG\LaravelMcpServer\Enums\ProcessMessageType;
135-
136-
interface ToolInterface
137-
{
138-
public function messageType(): ProcessMessageType; // New method
139-
public function name(): string; // Renamed
140-
public function description(): string; // Renamed
141-
public function inputSchema(): array; // Renamed
142-
public function annotations(): array; // Renamed
143-
public function execute(array $arguments): mixed; // No change
144-
}
145-
```
146-
147-
**Example of an updated tool:**
148-
149-
If your v1.0.x tool looked like this:
150-
151-
```php
152-
use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;
153-
154-
class MyOldTool implements ToolInterface
155-
{
156-
public function getName(): string { return 'MyOldTool'; }
157-
public function getDescription(): string { return 'This is my old tool.'; }
158-
public function getInputSchema(): array { return []; }
159-
public function getAnnotations(): array { return []; }
160-
public function execute(array $arguments): mixed { /* ... */ }
161-
}
162-
```
163-
164-
You need to update it for v1.1.0 as follows:
165-
166-
```php
167-
use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;
168-
use OPGG\LaravelMcpServer\Enums\ProcessMessageType; // Import the enum
169-
170-
class MyNewTool implements ToolInterface
171-
{
172-
/**
173-
* @deprecated since v1.3.0, use isStreaming() instead. Will be removed in v2.0.0
174-
*/
175-
public function messageType(): ProcessMessageType
176-
{
177-
return ProcessMessageType::HTTP;
178-
}
179-
180-
public function isStreaming(): bool
181-
{
182-
return false; // Most tools should return false
183-
}
184-
185-
public function name(): string { return 'MyNewTool'; }
186-
public function description(): string { return 'This is my new tool.'; }
187-
public function inputSchema(): array { return []; }
188-
public function annotations(): array { return []; }
189-
public function execute(array $arguments): mixed { /* ... */ }
190-
}
191-
```
46+
Version 1.1.0 introduced a breaking change to the `ToolInterface`. Upgrading from v1.0.x requires refactoring every tool implementation. Refer to the [ToolInterface Migration Guide](docs/migrations/v1.1.0-tool-interface-migration.md) for automated and manual upgrade instructions.
19247

19348
## Overview of Laravel MCP Server
19449

‎docs/migrations/v1.1.0-tool-interface-migration.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# ToolInterface Migration Guide (v1.1.0)
2+
3+
Version 1.1.0 of `opgginc/laravel-mcp-server` introduced a breaking change to `OPGG\\LaravelMcpServer\\Services\\ToolService\\ToolInterface`. If you are upgrading from v1.0.x you **must** update every tool implementation to match the new interface contract.
4+
5+
## Summary of Interface Changes
6+
7+
The interface now requires a new method and renames several existing methods:
8+
9+
1. **New method**
10+
- `messageType(): ProcessMessageType`
11+
- Required to support the HTTP stream transport by indicating the process message type.
12+
2. **Method renames**
13+
- `getName()` → `name()`
14+
- `getDescription()` → `description()`
15+
- `getInputSchema()` → `inputSchema()`
16+
- `getAnnotations()` → `annotations()`
17+
18+
## Automated Migration Command
19+
20+
Use the bundled Artisan command to migrate existing tools automatically:
21+
22+
```bash
23+
php artisan mcp:migrate-tools {path?}
24+
```
25+
26+
### What the Command Does
27+
28+
1. **Identifies old tool implementations** that still use the v1.0.x method signatures.
29+
2. **Creates a backup** of each tool file (`YourTool.php.backup`) before modifying it. Files that already contain a backup are skipped to prevent accidental overwrites.
30+
3. **Refactors the tool class** by renaming the affected methods, inserting `messageType()`, and ensuring the `ProcessMessageType` enum import exists. The generated `messageType()` method defaults to `ProcessMessageType::SSE`.
31+
32+
### Usage Tips
33+
34+
- Run the command immediately after upgrading the package:
35+
```bash
36+
php artisan mcp:migrate-tools
37+
```
38+
- Supply a different directory when your tools are not stored in the default `app/MCP/Tools/` path:
39+
```bash
40+
php artisan mcp:migrate-tools path/to/your/tools
41+
```
42+
- Review the diff after running the command—complex files may still require manual tweaks.
43+
44+
## Manual Migration Reference
45+
46+
The following snippets compare the old and new interface definitions and show how to update an implementation manually.
47+
48+
### v1.0.x `ToolInterface`
49+
50+
```php
51+
<?php
52+
53+
namespace OPGG\LaravelMcpServer\Services\ToolService;
54+
55+
interface ToolInterface
56+
{
57+
public function getName(): string;
58+
public function getDescription(): string;
59+
public function getInputSchema(): array;
60+
public function getAnnotations(): array;
61+
public function execute(array $arguments): mixed;
62+
}
63+
```
64+
65+
### v1.1.0 `ToolInterface`
66+
67+
```php
68+
<?php
69+
70+
namespace OPGG\LaravelMcpServer\Services\ToolService;
71+
72+
use OPGG\LaravelMcpServer\Enums\ProcessMessageType;
73+
74+
interface ToolInterface
75+
{
76+
public function messageType(): ProcessMessageType;
77+
public function name(): string;
78+
public function description(): string;
79+
public function inputSchema(): array;
80+
public function annotations(): array;
81+
public function execute(array $arguments): mixed;
82+
}
83+
```
84+
85+
### Example Implementation After Migration
86+
87+
```php
88+
use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;
89+
use OPGG\LaravelMcpServer\Enums\ProcessMessageType;
90+
91+
class MyTool implements ToolInterface
92+
{
93+
/**
94+
* @deprecated since v1.3.0, use isStreaming() instead. Will be removed in v2.0.0
95+
*/
96+
public function messageType(): ProcessMessageType
97+
{
98+
return ProcessMessageType::HTTP;
99+
}
100+
101+
public function isStreaming(): bool
102+
{
103+
return false;
104+
}
105+
106+
public function name(): string { return 'MyTool'; }
107+
public function description(): string { return 'This is my tool.'; }
108+
public function inputSchema(): array { return []; }
109+
public function annotations(): array { return []; }
110+
public function execute(array $arguments): mixed { /* ... */ }
111+
}
112+
```
113+
114+
With these changes your tools comply with the updated interface and remain compatible with future releases.

0 commit comments

Comments
 (0)