Laravel MCP API文件
通过工具和资源向Laravel MCP展示您的应用程序的OpenAPI规范，以便AI使用规范的API合同（无需猜测端点或有效负载）。
需求
- PHP 8.4+
- Laravel 11或12
- 拉瓦尔/mcp ^0.5.7
安装
composer require dhur-gham/laravel-mcp-api-docs发布配置（可选；默认值即用）：
php artisan vendor:publish --tag="laravel-mcp-api-docs-config"配置
发布后，编辑 config/mcp-api-docs.php:
| 关键字 | 环境 | 描述 |
|---|---|---|
enabled | MCP_API_DOCS_ENABLED | 启用/禁用MCP API文档服务器（默认值： true). |
path | MCP_API_DOCS_PATH | MCP服务器的Web路由路径（默认值： /mcp/api-docs). |
middleware | MCP_API_DOCS_MIDDLEWARE | 逗号分隔的中间件，例如。 auth:sanctum. |
policy_ability | MCP_API_DOCS_POLICY_ABILITY | 门能力（例如。 useMcpApiDocs)认证后需要；策略必须允许用户。省略或为空以跳过。 |
openapi.file | MCP_API_DOCS_OPENAPI_FILE | 本地OpenAPI JSON文件的绝对路径。 |
openapi.url | MCP_API_DOCS_OPENAPI_URL | 从中获取OpenAPI JSON的URL。 |
docs_folder | MCP_API_DOCS_DOCS_FOLDER | 功能文档文件夹的路径（例如。 DocsForMcp)；每个 .md file=一个特征。省略或空=文档工具未注册。 |
如果两者都没有 openapi.file 也不 openapi.url 已设置，包将查找 openapi.json 在 public/，项目根， storage/app/，以及 storage/app/api-docs/.
政策（可选）
要要求Laravel策略允许经过身份验证的用户（而不仅仅是有效的令牌），请设置 policy_ability （例如。 MCP_API_DOCS_POLICY_ABILITY=useMcpApiDocs).然后在策略中定义能力并注册：
// app/Policies/UserPolicy.php
public function useMcpApiDocs(User $user): bool
{
return $user->hasPermission('use_mcp'); // your logic
}// app/Providers/AuthServiceProvider.php
protected $policies = [
User::class => UserPolicy::class,
];中间件顺序：第一 auth:sanctum （令牌→ 用户），然后 can:useMcpApiDocs （政策检查）。
MCP行为
用于AI代理实现的只读API信息（没有真正的HTTP请求）。
- 工具
- list_tags() –列出标签及其端点（方法、路径、操作ID、摘要）。 - search_endpoints(query) –按关键字（路径、摘要、操作ID、标签）发现端点。 - get_endpoint(method, path) –一个端点的完整请求/响应模式。 - get_endpoints(tag) 或 get_endpoints(paths: [{method, path}, ...]) –最多25个端点的批量模式（通过标签或显式列表）。 - list_docs() –列出DocsForMcp文件夹中的功能文档名称（当 docs_folder 已设置）。退货 name （文件名无 .md)以及 summary （第一个标题）。 - get_doc(name) –按名称返回功能文档的标记内容。
- 资源
- api://openapi/catalog –服务器+所有操作（方法、路径、摘要、操作ID、标签）的平面列表，用于快速扫描。 - api://openapi –完整的OpenAPI规范。
在AI IDE中的使用（光标等）
将IDE的MCP配置指向应用程序的MCP路由。随着 认证：sanctum 以及个人访问令牌：
光标 –在中添加服务器 ~/.cursor/mcp.json （或项目 .cursor/mcp.json):
{
"mcpServers": {
"your-app-api-docs": {
"transport": "streamable-http",
"url": "http://127.0.0.1:8000/mcp/api-docs",
"headers": {
"Authorization": "Bearer YOUR_SANCTUM_TOKEN"
}
}
}
}替换 YOUR_SANCTUM_TOKEN 使用Laravel Sanctum个人访问令牌（例如来自 users → 创建令牌）。如果不是本地的，请使用您的真实应用程序URL（例如。 https://api.example.com/mcp/api-docs).服务器名称(your-app-api-docs)这只是一个标签。
许可证
MIT。