Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 124 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,32 @@

## ⚠️ Version Information & Breaking Changes

### v1.3.0 Changes (Current)
### v1.4.0 Changes (Latest) 🚀

Version 1.4.0 introduces powerful automatic tool and resource generation from Swagger/OpenAPI specifications:

**New Features:**
- **Swagger/OpenAPI Tool & Resource Generator**: Automatically generate MCP tools or resources from any Swagger/OpenAPI specification
- Supports both OpenAPI 3.x and Swagger 2.0 formats
- **Choose generation type**: Generate as Tools (for actions) or Resources (for read-only data)
- Interactive endpoint selection with grouping options
- Automatic authentication logic generation (API Key, Bearer Token, OAuth2)
- Smart naming for readable class names (handles hash-based operationIds)
- Built-in API testing before generation
- Complete Laravel HTTP client integration with retry logic

**Example Usage:**
```bash
# Generate tools from OP.GG API
php artisan make:swagger-mcp-tool https://api.op.gg/lol/swagger.json

# With options
php artisan make:swagger-mcp-tool ./api-spec.json --test-api --group-by=tag --prefix=MyApi
```

This feature dramatically reduces the time needed to integrate external APIs into your MCP server!

### v1.3.0 Changes

Version 1.3.0 introduces improvements to the `ToolInterface` for better communication control:

Expand Down Expand Up @@ -310,6 +335,104 @@ This command:
- Creates a properly structured tool class in `app/MCP/Tools`
- Offers to automatically register the tool in your configuration

#### Generate Tools from Swagger/OpenAPI Specifications (v1.4.0+)

Automatically generate MCP tools from any Swagger/OpenAPI specification with a single command:

```bash
# From URL
php artisan make:swagger-mcp-tool https://api.example.com/swagger.json

# From local file
php artisan make:swagger-mcp-tool ./specs/openapi.json

# With options
php artisan make:swagger-mcp-tool https://api.example.com/swagger.json \
--test-api \
--group-by=tag \
--prefix=MyApi
```

**Real-world Example with OP.GG API:**

```bash
➜ php artisan make:swagger-mcp-tool https://api.op.gg/lol/swagger.json

🚀 Swagger/OpenAPI to MCP Generator
=========================================
📄 Loading spec from: https://api.op.gg/lol/swagger.json
✅ Spec loaded successfully!
+-----------------+-------------------------+
| Property | Value |
+-----------------+-------------------------+
| Title | OP.GG Api Documentation |
| Version | openapi-3.0.0 |
| Base URL | https://api.op.gg |
| Total Endpoints | 6 |
| Tags | Riot |
| Security | |
+-----------------+-------------------------+

🎯 What would you like to generate from this API?

Tools: For operations that perform actions (create, update, delete, compute)
Resources: For read-only data endpoints that provide information

Generate as:
[0] Tools (for actions)
> 1
[1] Resources (for read-only data)
> 1

✓ Will generate as MCP Resources

Would you like to modify the base URL? Current: https://api.op.gg (yes/no) [no]:
> no

📋 Select endpoints to generate resources for:
Note: Only GET endpoints can be converted to resources
Include tag: Riot (6 endpoints)? (yes/no) [yes]:
> yes

Selected 6 endpoints.
🛠️ Generating MCP resources...
Note: operationId '5784a7dfd226e1621b0e6ee8c4f39407' looks like a hash, will use path-based naming
Generating: LolRegionRankingsGameTypeResource
✅ Generated: LolRegionRankingsGameTypeResource
Generating: LolRegionServerStatsResource
✅ Generated: LolRegionServerStatsResource
...

📦 Generated 6 MCP resources:
- LolRegionRankingsGameTypeResource
- LolRegionServerStatsResource
- LolMetaChampionsResource
...

✅ MCP resources generated successfully!
```

**Key Features:**
- **Automatic API parsing**: Supports OpenAPI 3.x and Swagger 2.0 specifications
- **Dual generation modes**:
- **Tools**: For operations that perform actions (POST, PUT, DELETE, etc.)
- **Resources**: For read-only GET endpoints that provide data
- **Smart naming**: Converts paths like `/lol/{region}/server-stats` to `LolRegionServerStatsTool` or `LolRegionServerStatsResource`
- **Hash detection**: Automatically detects MD5-like operationIds and uses path-based naming instead
- **Interactive mode**: Select which endpoints to convert
- **API testing**: Test API connectivity before generating
- **Authentication support**: Automatically generates authentication logic for API Key, Bearer Token, and OAuth2
- **Smart grouping**: Group endpoints by tags or path prefixes
- **Code generation**: Creates ready-to-use classes with Laravel HTTP client integration

The generated tools include:
- Proper input validation based on API parameters
- Authentication headers configuration
- Error handling for API responses with JsonRpcErrorException
- Request retry logic (3 retries with 100ms delay)
- Query parameter, path parameter, and request body handling
- Laravel HTTP client with timeout configuration

You can also manually create and register tools in `config/mcp-server.php`:

```php
Expand Down
Loading