Mcp Bundle Laravel Package

Getting Started

• Install with composer require php-llm/mcp-bundle. This pulls in php-llm/mcp-sdk transitively — the bundle pins the SDK to 0.1.x, so don't try to bump the SDK independently.
• Read the WIP disclaimer first. The 0.1 release notes explicitly add a "work in progress" notice. Treat this as an unstable API: expect breaking changes between minor versions and pin your composer.json constraint ("php-llm/mcp-bundle": "0.1.*") rather than using ^0.1.
• Framework reality check: mcp-bundle is a Symfony bundle — the DI wiring, service tags, and config tree are Symfony's. In a Laravel app you will mostly be using the underlying mcp-sdk classes directly and hand-wiring the server, or waiting for/using a Laravel-specific bridge. Confirm what auto-registration you actually get before designing around it.
• First place to look: the bundle's config (server name, version, capabilities, transport) and the Server/ServerBuilder service. That's the object everything hangs off.
• First use case: define a single tool (one class implementing the SDK's tool interface with a name, schema, and handle() returning a result), register it, and smoke-test over stdio with an MCP client — Claude Desktop or mcp-inspector. Getting one tool round-tripping end-to-end is the fastest way to validate the whole stack.

Implementation Patterns

• One class per tool. Keep tools small, single-purpose, and side-effect-free where possible — LLM clients call them speculatively and often. Return structured, boring JSON; don't return HTML or free-form prose.
• Model resources separately from tools. Tools do things; resources are read-only context the client can attach. Don't cram everything into tools — clients handle resource discovery and caching differently.
• Transport selection is the main architectural decision.
  • stdio for local desktop clients (Claude Desktop, CLI agents). The server is a child process spawned by the client.
  • HTTP/SSE for anything remote, multi-tenant, or behind auth.
• New in 0.1: client transports. The bundle now supports acting as an MCP client, not just a server — i.e. your app can consume another MCP server's tools/resources. This is the headline feature and it's very fresh. Read PR #1 before building on it; expect rough edges and thin docs.
• Config-driven metadata. Server name/version/capabilities are config, not code. Set them once so clients can identify and cache your server correctly.
• Testing: instantiate the server directly, inject a fake/in-memory transport, and assert on serialized tool responses. Don't test through a real subprocess in CI — it's slow and flaky.
• Wrap the server in an Artisan command (e.g. php artisan mcp:serve) so local dev and desktop-client config share one entry point.

Gotchas and Tips

• The 0.1 SDK pin is load-bearing. If any other dependency pulls a newer php-llm/mcp-sdk, Composer will either fail or silently give you a mismatched SDK. Run composer why php-llm/mcp-sdk if you see protocol weirdness after adding packages.
• Never write to stdout in a stdio server. Anything that isn't a protocol message — dump(), echo, a stray dd(), Laravel's debug output, some log drivers — corrupts the stream and the client hangs or disconnects with no useful error. Log to a file or stderr.
• It's a long-running process. Under stdio the server lives for the whole client session. Don't assume per-request lifecycle, don't rely on request() state, and be careful with anything that leaks between calls (static caches, container-bound mutable state). This is the opposite of Laravel's normal request model.
• Symfony/Laravel friction. Service tags, autoconfiguration, and the config tree won't behave like a Laravel service provider. Budget time for manual registration, and don't assume package discovery works.
• Client transports are the newest, least-battle-tested code. Feature landed in PR #1 of a 0.1 WIP package. Have a fallback plan and isolate it behind your own interface so you can swap it out.
• Debugging: use mcp-inspector to drive the server and inspect raw frames. When a client "just disconnects," it's almost always stdout pollution or a schema/serialization mismatch — inspect the wire, don't guess.
• Extension points (custom transports, tool middleware, server builder hooks) are your escape hatch for the SDK pin and framework mismatches. Prefer composing around the bundle over forking it — you'll be upgrading every few weeks at this stage.