Download the PHP package padosoft/askmydocs-mcp-pack without Composer

padosoft/askmydocs-mcp-pack

Framework-agnostic Model Context Protocol plumbing for Laravel. Contracts, multi-turn tool-calling orchestrator, stdio + HTTP transports, audit trail, RBAC hooks. Powers AskMyDocs and reusable in any Laravel AI app.

🚀 AI vibe-coding pack included

Every Padosoft package ships a .claude/ folder with curated skills, rules, and commands so Claude Code, Cursor, Copilot, and any other LLM agent can drive the package productively from day one. The pack documents the extension points the framework guarantees as stable (contracts, events, config keys) and the ones that are intentionally private — so AI agents stop guessing and start composing.

Table of contents

1. Why this package?
2. Features at a glance
3. Screenshots — Admin Web Panel
4. Comparison vs alternatives
5. Installation
6. Quick start (3 minutes)
7. Architecture
8. Core concepts
9. Configuration reference
10. Recipes
11. Extension points
12. Testing
13. Compatibility matrix
14. Roadmap
15. Changelog
16. License

Why this package?

MCP is the open standard Anthropic released in November 2024 for LLM ⇆ tool wire-format interoperability. Within months it was adopted by Cursor, Claude Desktop, VS Code, Cline, Continue, Sourcegraph Cody, OpenAI's Realtime API, and a long tail of editor extensions and agentic frameworks.

What MCP gives you:

• A JSON-RPC 2.0 contract for initialize, tools/list, tools/call, resources/*, prompts/*.
• Transport choice — stdio (child process) for desktop tools and HTTP/SSE for cloud gateways.
• A growing public catalog of servers (filesystem, GitHub, Slack, Postgres, Notion, Sentry, …) you can plug into any client.

What MCP does not give you (and what this pack adds):

• A multi-turn tool-calling loop that drives the model → tools → model → tools cycle with budget caps and audit trail.
• RBAC / tenant gates in front of every tool invocation.
• An opinionated audit table with SHA-256 input/output hashes, duration, status, and error excerpts — the kind of trail an EU AI-Act audit will ask for.
• Provider-agnostic integration: the orchestrator does NOT bind the OpenAI / Anthropic / Gemini SDK. You implement a 30-line McpHostBridgeContract against your existing chat manager, and the pack handles the rest.

That is exactly the shape AskMyDocs needed for v7.0. We extracted it so the next Laravel AI app does not have to reinvent it.

Features at a glance

Screenshots — Admin Web Panel

The companion SPA (padosoft/askmydocs-mcp-pack-admin, post-v7.0 cycle) consumes the v1.4 admin REST routes shipped here. Light + dark themes ship out of the box; every action is keyboard-reachable and audit-logged.

Dashboard

The landing surface — fleet health, breaker open-count, recent audit volume per server, and at-a-glance latency percentiles.

Servers + per-server detail + tools + circuit breakers

Servers list filters by tenant + transport + status. Drill in for the handshake-cached tool catalog, the most recent audit slice, and the breaker state for every (server, tool) pair — read from CircuitBreaker::peekState() so the dashboard NEVER consumes the half-open probe slot just by polling.

Audit + audit detail + per-server audit

Paginated audit query over the configurable mcp-pack.audit_model, tenant-scoped by default. Filters: server_id, tool_name, status, date range. Click a row for the SHA-256 input/output hashes + redacted error excerpt + duration.

Prompts + API playground + Settings

Prompt catalog (JSON-RPC prompts/list / prompts/get), an embedded API playground for verifying the routes against the host's auth middleware, and a settings surface mirroring the mcp-pack.* config block.

Comparison vs alternatives

laravel/mcp is excellent for exposing Laravel as an MCP server — this pack and laravel/mcp are complementary, not competing. Use both together: laravel/mcp to expose your KB as a server, and this pack to consume other MCP servers from inside your chat flow.

Installation

Publish config + migrations (optional — both load automatically):

Service provider is auto-discovered via composer.json::extra.laravel.providers.

Quick start (3 minutes)

1. Implement the host bridge

This is the one piece you must write — about 30 lines of glue against your existing chat provider:

2. Bind it in AppServiceProvider

3. Register at least one MCP server

In-memory (config-driven):

Or back it with your own Eloquent model — see Recipes.

4. Drive a chat turn

Behind the scenes the orchestrator:

1. Looks up enabled servers for tenant acme.
2. Handshakes each one (cached for 5 min).
3. Filters tools through your McpToolAuthorizerContract.
4. Hands the catalog to your MyHostBridge::chat().
5. If the model asks for a tool: invokes it through tools/call, appends the result, and loops back.
6. Audits every call into mcp_tool_call_audit.

5. Sanity-check

Architecture

Five contracts, three transports, one orchestrator. The blast-radius of swapping any one of them is bounded by the contract.

Core concepts

McpServerContract

A single MCP endpoint your host can talk to. Carries:

• id() — stable identifier scoped per tenant.
• transport() — stdio or http.
• tenantId() — null = platform-global; a string = scoped to that tenant.
• transportConfig() — {command, args, cwd, env} for stdio; {endpoint, headers, timeout_ms} for http.
• allowedTools() — empty array = "all tools the server advertises"; otherwise a per-server allow-list.

Default implementation: InMemoryMcpServer. Production: subclass it on top of your Eloquent model.

McpServerRegistryContract

Per-tenant catalog of McpServerContract entries. The orchestrator always asks forTenant($id) — never a global all(). Cross-tenant leakage is structurally impossible.

Default implementation: InMemoryMcpServerRegistry. Production: back it with your own McpServer Eloquent model.

McpHostBridgeContract

The 30-line wrapper around your existing chat manager (OpenAI, Anthropic, OpenRouter, Gemini, …). The pack does NOT bind any AI SDK — this is what keeps it provider-agnostic.

McpToolAuthorizerContract

RBAC gate. Called BEFORE the tool appears in the model's catalog, so denied tools never even reach the prompt token budget.

Default implementation: NullMcpToolAuthorizer (allows everything — fine for prototypes, MUST be replaced in production).

McpToolContract

The unit of work. Most consumers don't implement this directly — RemoteMcpTool is built from the upstream server's tools/list response and used by the orchestrator. You implement it only if you need to expose an in-process tool with no upstream MCP server (uncommon).

Configuration reference

config/mcp-pack.php:

Recipes

Recipe 1 — back the registry with an Eloquent model

Recipe 2 — Spatie-permission-backed authorizer

Recipe 3 — Claude Desktop / Cursor MCP server over stdio

Recipe 4 — remote MCP gateway over HTTPS

Recipe 5 — coexist with a host-owned audit table

If your host already owns a mcp_tool_call_audit table that pre-dates this pack, the package migration is a no-op (Schema::hasTable('mcp_tool_call_audit') guards both up() and down()). To keep the host's operator-forensics columns (raw redacted payload, user-FK, error blob, …) AND satisfy the package contract, ship ONE additive host migration and one model subclass:

Now every package ToolInvoker::audit() row fills BOTH schemas; legacy host writes continue to work; the host's existing admin UI and operator-forensics queries keep rendering the same way they always did.

Recipe 6 — fail fast under upstream outage (v1.3.0)

Drop in the circuit breaker + retry budget so a flaky MCP server doesn't pin every worker on a long timeout:

ToolInvoker automatically routes through the mediator when either knob is enabled; consumers don't change a line of code. The breaker state is per (server_id, tool_name); the budget is per (tenant_id, server_id) so cross-tenant isolation (R30) holds even under load.

Extension points

Testing

The pack ships its own PHPUnit + Orchestra Testbench setup. To run its tests:

To test your own host using the pack's stubs:

End-to-end Playwright coverage in AskMyDocs exercises:

• chat UI with MCP tools enabled → tool-call summary card renders
• admin SPA /admin/mcp-servers → server CRUD + ping action
• audit log shows tool calls with status, duration, server name

Compatibility matrix

Roadmap

The v1.1 → v1.4 cycle ships before the AskMyDocs host adopts the package. Consumers willing to ride v1.0 today are welcome to do so — the public API surface is stable and won't break before v2 — but AskMyDocs's own host integration is intentionally deferred to land over the complete v1.4 feature set (orchestrator + transports + server-side + circuit breaker + admin REST routes) in a single integration cycle rather than four partial passes. See lopadova/AskMyDocs roadmap for the host-side milestones (v7.0/W2 → W6).

Changelog

v1.0.0 — planned

• Initial release extracted from AskMyDocs v6.x.
• McpToolContract, McpServerContract, McpServerRegistryContract, McpToolAuthorizerContract, McpHostBridgeContract.
• HttpJsonRpcTransport + StdioJsonRpcTransport.
• McpToolCallingService multi-turn loop with budget cap.
• McpHandshakeService with cached handshakes.
• ToolInvoker with SHA-256 audit trail.
• mcp_tool_call_audit migration.
• mcp-pack:ping Artisan diagnostic.
• NullMcpHostBridge + NullMcpToolAuthorizer + InMemoryMcpServerRegistry defaults.

License

MIT © Padosoft. See LICENSE.