Laravel MCP Companion

Laravel MCP Companion

原名 Laravel Docs MCP Server

⚠️ 测试版软件 - 此项目正在积极开发中。功能可能会变更，也可能出现不兼容的变更。

Laravel MCP Companion 是一个 Laravel 生态系统文档聚合与导航工具。它集中整理了整个 Laravel 生态系统中的高质量文档，方便通过 AI 助手轻松查找。

对比

功能	Laravel Boost	Context7	Laravel MCP Companion
侧重点	代码生成	通用文档	Laravel 文档
适用场景	活跃开发	任意库	学习与参考
项目感知上下文	✅	❌	❌
Laravel 多版本支持（6.x - 最新版）	❌	❌	✅
Laravel 服务文档（Forge、Vapor、Nova、Envoyer）	❌	❌	✅
学习路径与难度级别	❌	❌	✅
“我需要 X”文档查找器	❌	❌	✅
精选 Laravel 扩展包推荐	❌	❌	✅
离线访问文档	❌	❌	✅
TOON 格式输出（减少 30-60% 的 token）	❌	❌	✅
通用文档（非 Laravel）	❌	✅	❌

编写代码且需要项目感知上下文时，使用 Boost。使用非 Laravel 库时，使用 Context7。学习、研究或需要查阅 Laravel 文档时，使用 Companion。

你将获得：

• 多版本 Laravel 文档（从 6.x 到最新版），支持增强搜索
• 学习路径 - 按主题和技能水平组织的结构化学习顺序
• “我需要 X”查找器 - 描述你的需求，获取相关文档
• 难度筛选 - 内容按初级/中级/高级分类
• 15 个语义类别 - 按主题浏览文档
• 自动发现 Laravel 服务 - Forge、Vapor、Envoyer、Nova（117+ 个章节）
• 社区扩展包文档 - 来自 Spatie、Livewire、Inertia、Filament 的 42,000+ 行内容
• 扩展包集成指南 - 22 个精选扩展包的安装与设置指南
• 跨扩展包兼容性 - 了解哪些扩展包可以良好协作
• 涵盖 Laravel 核心文档、服务、扩展包和学习资源的统一搜索
• 每日更新 - 自动与最新文档同步

安装

已列入官方 MCP Registry， 条目为 io.github.brianirish/laravel-mcp-companion — 支持 Registry 的客户端 可以直接从中安装。手动设置：

Claude Desktop

1. 打开 Claude Desktop Settings

   • 点击 Claude 菜单 → Settings → Developer → Edit Config

2. 添加到配置文件中：

   {
     "mcpServers": {
       "laravel-mcp-companion": {
         "command": "docker",
         "args": ["run", "--rm", "-i", "ghcr.io/brianirish/laravel-mcp-companion:latest"]
       }
     }
   }
   

3. 重启 Claude Desktop 以使更改生效

配置文件位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code

使用 claude mcp add 命令：

# Add with Docker
claude mcp add laravel-mcp-companion -- docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest

# Or add to project-specific config (for team sharing)
claude mcp add laravel-mcp-companion --scope project -- docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest

--scope project 选项会在项目根目录中创建 .mcp.json 文件，该文件可以提交到版本控制系统。

配置选项

这些选项可以与 Docker 命令一起使用。例如：

# Pin to a specific older Laravel version
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --version 11.x

# Force update all documentation
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --force-update

选项	说明	默认值
--version VERSION	Laravel 版本（例如，“11.x”、“12.x”）	最新
--docs-path PATH	文档目录	./docs
--log-level LEVEL	DEBUG、INFO、WARNING、ERROR、CRITICAL	INFO
--update-docs	启动时更新文档	false
--force-update	强制更新文档	false
--transform-mode MODE	工具暴露模式：search、code 或 none（env：TRANSFORM_MODE）	search
--host HOST	HTTP 模式下绑定的接口（env：HOST）	127.0.0.1（Docker 中为 0.0.0.0）
--cors-origin ORIGIN	允许调用 HTTP 传输的浏览器来源，可重复指定（env：CORS_ORIGINS）	无（CORS 关闭）
--allowed-host HOST	HTTP 模式下允许的其他 Host 请求头，可重复指定（env：ALLOWED_HOSTS）	localhost、127.0.0.1、::1
--auth-jwks-uri URI	在 HTTP 模式下启用 bearer token 身份验证的 JWKS 端点（env：AUTH_JWKS_URI）	无（身份验证关闭）
--auth-issuer ISSUER	必需的 token 签发者，需与 --auth-jwks-uri 配合使用（env：AUTH_ISSUER）	无
--auth-audience AUD	必需的 token 受众，需与 --auth-jwks-uri 配合使用（env：AUTH_AUDIENCE）	无
--auth-required-scope SCOPE	每个 token 都必须携带的 scope，可重复指定（env：AUTH_REQUIRED_SCOPES）	无
--rate-limit RPS	HTTP 模式下每秒接受的 MCP 请求数；运维端点不受限制（env：RATE_LIMIT_RPS）	无（不限制）
--rate-limit-burst N	令牌桶突发容量（env：RATE_LIMIT_BURST）	max(10, 2×RPS)

保持文档最新

文档随镜像一起发布，每当文档更新时都会发布新镜像，因此 :latest 包含最近发布的文档快照。但要注意，docker run 会重复使用你已有的副本——拉取镜像后，除非再次拉取，否则你运行的始终是该镜像。可随时刷新：

docker pull ghcr.io/brianirish/laravel-mcp-companion:latest

也可以在 MCP 配置中添加 --pull=always，让每次启动时都检查是否有更新的镜像。这会增加一点启动时间，而且需要网络连接正常，因此默认不开启：

"args": ["run", "--rm", "-i", "--pull=always",
         "ghcr.io/brianirish/laravel-mcp-companion:latest"]

你不必自己跟踪版本。服务会告知助手当前提供的 Laravel 版本对应的文档有多旧，因此，如果你询问的内容比该快照更新，它会说明这一点，并建议刷新，而不是根据过时的页面作答。你也可以直接询问——“你的 Laravel 文档有多新？”

如果不想拉取新镜像，也可以原地更新：--update-docs 会在启动时获取所选 Laravel 版本的最新文档。Forge、Vapor、Nova、Envoyer 和社区软件包的文档则会单独刷新，助手可以调用 update_external_laravel_docs 工具来完成。

使用 --rm 时，容器退出后下载的文档会被丢弃，因此每次启动都会重新下载。命名卷可以保留文档，但请注意其中的取舍：

docker run --rm -i -v laravel-mcp-docs:/app/docs \
  ghcr.io/brianirish/laravel-mcp-companion:latest --update-docs

卷会覆盖镜像中的文档。 填充内容后，它会屏蔽 /app/docs，因此拉取较新镜像也不会更新服务读取的内容——此时卷会成为唯一可信来源，而 --update-docs 则成为刷新文档的方式。如果你想显式控制更新，请使用卷；如果希望由镜像负责更新，则直接使用 docker pull。

转换模式

默认情况下，服务不再列出所有工具，而是提供精简的搜索优先界面，以减少 AI 客户端的上下文窗口占用：

• search（默认）——提供 search_tools（对工具目录进行 BM25 相关性搜索）和 call_tool（调用任意底层工具的代理）。search_laravel_docs 仍会固定显示，并可直接调用。
• code（实验性）——提供 Code Mode 元工具（tags、search、get_schema、execute），让客户端发现工具，并通过沙盒化 Python 编排这些工具。需要 fastmcp[code-mode] 附加组件（已包含在 requirements.txt 中）。避免通过 HTTP 向公众开放此模式——execute 是代码执行端点。
• none——回到 0.9 之前的行为：直接列出所有工具。如果你的 MCP 客户端不擅长处理合成搜索工具，可使用此模式。

# Restore the old flat tool listing
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --transform-mode none

HTTP 传输安全

默认关闭身份验证。 任何能够访问 HTTP 端口的人都可以调用所有工具，因此应将网络暴露视为授予对整个文档树的完全访问权限，或者启用 bearer-token 身份验证：

# Validate tokens issued by a real OAuth 2.1 authorization server
python laravel_mcp_companion.py --transport http \
  --auth-jwks-uri https://auth.example/.well-known/jwks.json \
  --auth-issuer https://auth.example \
  --auth-audience laravel-mcp-companion

# Development only: fixed tokens from the environment (never a CLI flag,
# so secrets stay out of process listings)
AUTH_STATIC_TOKENS="my-token:my-client" python laravel_mcp_companion.py --transport http

该服务是一个资源服务器：它验证令牌，但绝不会签发令牌。使用 --auth-jwks-uri 时，颁发者和受众是必填项——接受任意颁发者签发的令牌，或为其他服务签发的令牌，只是在做身份验证的表面功夫。未经身份验证的请求会收到带有 WWW-Authenticate 标头的 401（RFC 9728），配置错误会在启动时而非请求时导致失败。身份验证仅适用于 HTTP 传输；stdio 的访问控制由进程边界决定。

默认设置较为保守：

• 在 Docker 外绑定到 127.0.0.1。 在容器内绑定到 0.0.0.0，此时访问控制由容器边界和显式的 -p 端口发布承担。
• 已启用 Host 和 Origin 验证，可阻止 DNS 重绑定攻击和利用受害者浏览器发起的本地攻击。
• 默认禁用 CORS，除非传入 --cors-origin。不接受通配符来源；绝不允许跨来源凭据。

默认情况下，只有 localhost、127.0.0.1 和 ::1 会被接受为 Host 值。如果绑定到非环回接口，必须添加客户端实际使用的主机名，否则所有请求都会被拒绝并返回 421：

python laravel_mcp_companion.py --transport http \
  --host 0.0.0.0 \
  --allowed-host mcp.internal.example \
  --cors-origin https://app.example

带有无法识别的 Host 的请求会收到 421；来自未列出的 Origin 的请求会收到 403。在命令行传入 --allowed-host 或 --cors-origin 会替换对应的环境变量，而不是在其基础上添加值。如果要将其暴露给 localhost 以外的网络，请在前面放置一个进行身份验证的反向代理。完全避免通过 HTTP 使用 --transform-mode code——execute 是一个代码执行端点。

速率限制（HTTP 模式）

默认关闭。--rate-limit 20 将 MCP 请求——工具调用、搜索及协议接口——限制为每秒 20 次，并使用一个全局令牌桶：这是总吞吐量上限，而非客户端公平限流（没有身份验证时，无法可靠地确定用于限流的客户端身份）。运维端点（/healthz、/metrics、/.well-known/...）有意不受限制：对负载均衡器的健康检查进行限流会导致健康实例被标记为不可用，而这些处理程序只是简单的读取操作。该限制会统计每个 MCP 请求，包括初始化握手，因此默认突发值保持为 max(10, 2×RPS)；如果降低该值，请确保突发上限明显高于客户端握手所需的请求数。被限流的请求会收到明确的 MCP 错误，令牌桶补满后即可再次成功。

运维端点（HTTP 模式）

• GET /healthz — 存活状态／就绪状态 JSON，始终公开（负载均衡器无法进行 OAuth）。ok 和 degraded 都返回 200——degraded 表示文档副本已过期，应拉取更新的镜像；503 表示没有可读取的文档，不应将流量路由到此处。
• GET /metrics — Prometheus 文本格式：各工具调用计数器、延迟直方图、请求数、运行时间和文档时效。未配置身份验证的部署中公开；只要配置了身份验证，就需要有效的 bearer token。

功能（v0.13.0）

文档聚合

• 多版本 Laravel 文档 - 涵盖从 6.x 到最新版本的所有版本
• 自动发现引擎 - 可在 Forge、Vapor、Nova、Envoyer 中查找新文档
• 社区软件包文档 - 来自 Spatie、Livewire、Inertia、Filament 的 42,000+ 行内容
• 每日更新 - 自动同步最新文档

学习与探索

• 学习路径 - 为任意 Laravel 主题提供结构化学习序列，并以交互方式呈现：无需指定路径，直接提问，服务端会询问你想要哪条精选路径（共 10 条）
• 难度级别 - 按初级、中级或高级筛选
• 15 个类别 - 按身份验证、数据库、测试等类别浏览
• “我需要 X”查找器 - 使用自然语言发现文档
• 相关资源 - 自动查找相关文档

搜索与导航

• 按相关性排序的章节搜索 - 使用自然语言提问（“如何重试失败的队列任务”），即可获取按相关性排序的相关章节，每条结果都附有摘要、锚点和来源标签
• 章节级读取 - 只获取所需章节。整个文档文件可能超过 30,000 个 token；而一个章节通常只有几百个 token，因此回答会为你的实际代码留出空间
• 用例映射 - 描述你的需求，即可获取相关软件包
• 软件包集成指南 - 提供 22 个精选软件包的安装和设置指南
• 跨软件包兼容性 - 提供软件包组合的文档
• 统一搜索 - 一次搜索即可覆盖所有语料库：核心版本、服务、获取的软件包文档和学习资源，并可使用 sources 筛选器缩小范围

MCP 2025-11-25 功能

• 支持任务的更新 - 文档更新以 MCP 任务运行：提交任务、轮询状态并获取结果，而不是让连接保持数分钟
• 结构化输出 - 表格工具会返回带有实际模式的 structuredContent，并同时提供 TOON 文本
• 交互式征询 - 在适用时提供交互式选项；不具备该功能的客户端则使用纯文本列表作为后备
• 已列入注册表 - 可从官方 MCP 注册表安装，并提供 server.json 元数据、HTTP 模式下的 .well-known 发现，以及发布标签触发的自动发布

生产运维（HTTP 模式）

• 运行状况与指标 - 为负载均衡器提供 GET /healthz，并通过 Prometheus GET /metrics 提供各工具计数器、延迟直方图和文档年龄
• OAuth 2.1 资源服务 - 可选的 Bearer 令牌验证（JWKS 或静态开发令牌）；配置错误会导致启动失败，服务中断时则默认拒绝访问
• 速率限制 - 可选地在 MCP 接口范围内启用令牌桶限流，并默认采用适配握手流程的突发容量
• 默认加固 - 绑定到环回地址，验证 Host/Origin，不使用通配符 CORS，并对搜索、列表和读取统一执行路径包含检查

质量

• 81% 的产品覆盖率，CI 门槛为 80%；针对真实 stdio 和 HTTP 传输进行端到端测试，并提供仅报告的延迟基准测试——在 100ms 的 v1.0.0 目标下，预热后的搜索 p95 延迟为数毫秒

即将推出

• v1.0.0：首个稳定版本——冻结 API、制定破坏性变更政策，并承诺提供 LTS

有关路线图的详细信息，请参阅 ROADMAP.md。

TOON 格式输出

Laravel MCP Companion 使用 TOON (Token-Oriented Object Notation) 进行结构化输出，与 JSON/Markdown 相比可节省 30-60% 的 token。

输出示例

搜索软件包或列出文档时，你会获得高效的结构化数据：

context: "authentication for SPA"
count: 2
packages[2]{id,name,description,categories,install}:
  laravel/sanctum,Laravel Sanctum,"Featherweight authentication for SPAs",[authentication,spa],"composer require laravel/sanctum"
  laravel/passport,Laravel Passport,"Full OAuth2 implementation",[authentication,api],"composer require laravel/passport"

与等效的 JSON 相比（token 数量近乎翻倍）：

{"context":"authentication for SPA","count":2,"packages":[{"id":"laravel/sanctum","name":"Laravel Sanctum",...}]}

为什么使用 TOON？

• Token 效率高：大模型可原生理解 TOON，无需解析开销
• 结构化数据：提供数组、对象和元数据，避免 JSON 的冗长格式
• 适合 AI：专为大模型上下文窗口设计

自动发现与更新频率

此应用具有一套智能自动发现系统，可自动查找并索引 Laravel 文档。每天，它都会：

• 自动发现 Laravel 各项服务（Forge、Vapor、Nova、Envoyer）中的新文档章节
• 获取所有 6.x 及更高版本的最新 Laravel 核心文档
• 获取社区软件包文档（Spatie、Livewire、Inertia、Filament）
• 自动适配文档网站的结构变化
• 在发现更新时自动生成新的补丁版本

开发

先决条件

• Python 3.12+
• Node.js 18+（用于 MCP Inspector）

设置

git clone https://github.com/brianirish/laravel-mcp-companion
cd laravel-mcp-companion
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt

运行测试

# All tests with coverage
pytest --cov --cov-report=html

# Unit tests only
pytest tests/unit/

# Integration tests only
pytest tests/integration/

# Protocol compliance tests
pytest tests/protocol/ -m protocol

使用 MCP Inspector 手动测试

MCP Inspector 提供了用于测试 MCP 服务的可视化界面。

# Launch Inspector (opens browser at http://localhost:6274)
npx @modelcontextprotocol/inspector python laravel_mcp_companion.py

# With specific version
npx @modelcontextprotocol/inspector python laravel_mcp_companion.py --version 11.x

使用 Inspector 进行以下操作：

• 工具选项卡：使用自动生成的输入表单测试所有工具
• 资源选项卡：浏览 laravel:// 和 laravel-external:// 资源
• 提示词选项卡：测试提示词模板

代码质量

ruff check --fix .     # Linting
mypy --ignore-missing-imports .  # Type checking
black .                # Formatting

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

致谢

• 感谢 Laravel 提供出色的文档
• 感谢 Laravel 软件包作者为生态系统作出的贡献