使用说明
MCP工具
一个Laravel包，用于生成和管理与MCP（模型上下文协议）集成的API合同。
[！重要] 此软件包提供必须在项目的MCP服务器中注册的MCP工具。它本身不会创建或运行MCP服务器——您需要 Laravel MCP 在您的项目中配置。
特性
- 自动生成API合同：从您的Laravel路线生成全面的API合同
- MCP工具集成：通过MCP工具列出并描述API路线
- 高级分析：对路由、FormRequests、资源和中间件进行深入分析
- OpenAPI导出：将合约导出为OpenAPI 3.0格式
- 缓存：智能缓存可提高性能
- 验证：对生成的合约进行JSON模式验证
需求
- PHP 8.4+
- Laravel 11.x或12.x
- Laravel MCP ^0.5.1
安装
通过composer安装软件包：
composer require abr4xas/mcp-tools
该包将自动注册其服务提供商。但是，必须在项目的MCP服务器配置中手动注册MCP工具。
用法
生成API合同
从您的Laravel路线生成全面的API合同：
php artisan api:contract:generate
此命令将：
- 扫描所有申请路线
- 提取路线信息（方法、路径、参数）
- 分析控制器方法和FormRequest类
- 生成身份验证要求
- 在以下位置创建JSON文件
storage/api-contracts/api.json
选项：
--incremental：仅更新已修改的路线--log：启用详细日志记录--dry-run：验证而不写入文件--validate-schemas：根据JSON模式验证生成的模式
导出到OpenAPI
php artisan api:export-openapi
清除缓存
php artisan mcp-tools:clear-cache
健康检查
php artisan mcp-tools:health-check
查看指标
php artisan mcp-tools:metrics
管理合同版本
php artisan api:contract:versions
查看日志
php artisan mcp-tools:logs
MCP工具
该软件包提供了MCP工具，必须在Laravel MCP服务器配置中手动注册。
[！重要] 验证注册 通过检查MCP服务器的可用工具列表。
1. list-api-routes
列出所有带有可选筛选的API路由。
论据：
method（可选）：按HTTP方法过滤（GET、POST、PUT、DELETE、PATCH）version（可选）：按API版本筛选（v1、v2等）search（可选）：按路径筛选路线的搜索词limit（可选）：最大结果数（默认值：50，最大值：200）page（可选）：分页页码（默认值：1）
例子：
{
"method": "GET",
"version": "v1",
"search": "users",
"limit": 10,
"page": 1
}
2. describe-api-route
获取特定端点的详细信息。
论据：
path（必需）：API路由路径（例如。，/api/v1/users/{user})method（可选）：HTTP方法（默认为GET）
例子：
{
"path": "/api/v1/users/{user}",
"method": "GET"
}
答复包括：
- 路线描述
- API版本
- 身份验证要求
- 带类型的路径参数
- 请求/响应模式（如果可用）
- 速率限制信息
- 状态代码
- 内容协商
注册MCP工具
此包提供的MCP工具必须在Laravel MCP服务器配置中手动注册。
故障排除
如果您在注册工具时遇到问题：
- 工具未出现：确保正确加载MCP服务器配置文件
- 未找到类错误：运行
composer dump-autoload刷新自动加载器 - 服务提供商未注册：检查一下
Abr4xas\McpTools\McpToolsServiceProvider在你的config/app.php提供者数组（应自动发现）
配置
该包会自动检测并包含在合同中：
- 路线参数和类型
- 身份验证要求（来源于中间件分析）
- 速率限制信息
- 请求验证规则（来自FormRequests）
- 响应模式（来自参考资料）
- 状态代码
- 自定义标头
- 内容协商
- API版本控制
API合同结构
生成的合同位于 storage/api-contracts/api.json 遵循此结构：
{
"/api/v1/users": {
"GET": {
"description": "List all users",
"deprecated": null,
"auth": { "type": "bearer" },
"path_parameters": {},
"request_schema": {
"location": "query",
"properties": {}
},
"response_schema": {
"type": "array",
"items": {}
},
"response_headers": [],
"custom_headers": [],
"rate_limit": null,
"api_version": "v1",
"status_codes": {
"200": "OK",
"401": "Unauthorized"
},
"content_negotiation": []
},
"POST": {
"description": "Create a new user",
"deprecated": null,
"auth": { "type": "bearer" },
"path_parameters": {},
"request_schema": {
"location": "body",
"properties": {
"name": { "type": "string", "required": true },
"email": { "type": "string", "format": "email", "required": true }
}
},
"response_schema": { "type": "object", "properties": {} },
"response_headers": [],
"custom_headers": [],
"rate_limit": null,
"api_version": "v1",
"status_codes": {
"201": "Created",
"422": "Unprocessable Entity"
},
"content_negotiation": []
}
},
"/api/v1/users/{user}": {
"GET": {
"description": "Get user details",
"deprecated": null,
"auth": { "type": "bearer" },
"path_parameters": {
"user": { "type": "integer", "required": true }
},
"request_schema": { "location": "query", "properties": {} },
"response_schema": { "type": "object", "properties": {} },
"response_headers": [],
"custom_headers": [],
"rate_limit": null,
"api_version": "v1",
"status_codes": {
"200": "OK",
"404": "Not Found"
},
"content_negotiation": []
}
}
}
延伸
自定义模式转换器
创建一个变压器实现 SchemaTransformerInterface:
use Abr4xas\McpTools\Interfaces\SchemaTransformerInterface;
class CustomTransformer implements SchemaTransformerInterface
{
public function transform(array $schema): array
{
// Transform schema
return $schema;
}
public function getPriority(): int
{
return 100;
}
}
在您的服务提供商处注册：
$this->app->make(SchemaTransformerRegistry::class)
->register(new CustomTransformer());
测试
运行测试套件：
composer test
运行覆盖率测试：
vendor/bin/pest --coverage
更新日志
请参阅 更新日志 有关最近发生的变化的更多信息。
贡献
请参阅 贡献 了解详情。
安全漏洞
请审阅 我们的安全政策 关于如何报告安全漏洞。
学分
许可证
MIT许可证（MIT）。请参阅 许可证文件 了解更多信息。