Mcp Laravel Package

Getting Started

• composer require aureuserp/mcp inside your AureusERP application (this is an ERP-domain package, not a generic MCP server — it expects the AureusERP/Laravel app context). Confirm the service provider is auto-discovered, or add it to bootstrap/providers.php if you have discovery disabled.
• Publish and read the config first: php artisan vendor:publish --tag=... (check the provider's publishes() for the exact tag). The config file is the fastest way to learn which server transports, tool groups, and plugin hooks exist.
• Read in this order: config file → service provider boot()/register() → the tool/resource registry → the plugin-installation check that gates activation (this is the path v1.0.3 changed).
• First use case: install exactly one plugin, point an MCP client (Claude Desktop, MCP Inspector, or your own stdio client) at the server, and confirm that plugin's tools show up in tools/list. Do this before writing any tool code — it proves install → activation → discovery works end-to-end in your environment.
• Do the second thing next: call one read tool (list/fetch an ERP entity) from the client. Reads are the low-risk way to validate schema generation, auth context, and response shape before you touch anything that writes.

Implementation Patterns

• Treat plugin installation as the deployment unit, not the tool. Install the plugin, then let the package activate its tools. Write your runbook as "install plugin → clear config cache → restart the MCP server process → verify tools/list", not "enable tool X".
• Model your tools after business actions, not Eloquent models. A tool named create_purchase_order with a small, explicit input schema is far more usable by an AI client than create_model with a polymorphic payload. The package advertises "discoverable schemas for reliable AI client use" — that only pays off if your schemas are narrow and typed.
• Split read and write tools deliberately. Let discovery expose read tools broadly; gate write tools behind plugin installation (and, ideally, behind a separate plugin or config flag) so enabling a plugin doesn't silently give a client the ability to mutate ERP data.
• Put stable reference data in resources, not tools. Enumerations, statuses, tax codes, UOM lists, and schema descriptions are resources — they get injected into context and don't need a round trip. Reserve tools for actions.
• Extend via the package's handlers. The package advertises "extensible handlers for custom actions and data sources" — register custom handlers there rather than patching the provider. Keeps you upgradeable across a package that is at v1.0.3 and still moving.
• Testing pattern: in setUp(), install the required plugin (or call the package's installer/activation API), then assert tools/list contains the expected tool and that a call returns a valid payload. Any test written before v1.0.3 that assumes tools are always available must be updated to arrange installation first.
• Client-side dev loop: use MCP Inspector or a small scripted client in a test, not a full AI assistant, while iterating. Restart the server process after every code change — MCP servers are long-lived and won't hot-reload your tool registrations.
• Multi-plugin products: document the plugin→tool-group mapping in your repo. Operators need to know which plugin must be installed before a tool appears, otherwise every "tool missing" ticket starts with a wasted debugging cycle.

Gotchas and Tips

• v1.0.3 is a behavior change, not just a bug fix. Tool activation now requires plugin installation. If tools vanish after upgrading, check installation state before you read a line of tool code.
• Debug in this order: (1) is the plugin actually installed? (2) is config cached (php artisan config:clear)? (3) provider boot order — does the activation check run after whatever store holds installation state is available? (4) is the MCP server process stale? Provider registration order is almost never the real problem.
• Boot-order trap: if installation state lives in the database, the activation check must not run before the DB is reachable (migrations, artisan commands on a fresh DB, queue workers starting early). Installed plugins can look absent purely from timing.
• Config cache in deploy pipelines. A plugin can be installed while the app still sees stale activation state. Clear config as part of the install/uninstall step, not as an afterthought.
• Long-running processes cache everything. Stdio/SSE MCP servers started before a deploy will serve the old tool list. Restart them on deploy and after any plugin install/uninstall.
• Auth context is the sharp edge. MCP calls don't arrive with a normal user session. Decide explicitly whose permissions a tool call runs under, and enforce authorization in the handler — don't rely on the HTTP middleware stack you'd normally have. Log which principal executed which write.
• Schema changes invalidate client caches. Many MCP clients cache tools/list. After changing a tool's schema, refresh discovery on the client side or you'll debug a bug that no longer exists.
• Don't hand-roll activation shortcuts. Bypassing the installation check to make a tool appear in dev reintroduces exactly the bug v1.0.3 fixed, and it will diverge in production.
• Version pinning: at v1.0.3 with a small user base, pin the exact version and read every release note — patch releases have already altered activation semantics once. Add one smoke test (install plugin → assert tool active) as your cheapest regression guard.
• Verify uninstall behavior yourself. The sources don't say whether removing a plugin deactivates already-active tools or leaves orphaned activation records. Test it in staging and write down the answer before an operator discovers it for you.