MCP Tools

The package includes 14 Model Context Protocol tools for full blog management via AI agents.

Post Tools

Category Tools

Setup

Install laravel/mcp (a suggestion, not a hard requirement), then turn the feature on:

'features' => [
    'mcp' => true,
],

'mcp' => [
    'path' => '/mcp/blog',
    'guard' => null,                    // null uses the default guard
    'middleware' => ['auth:sanctum'],
],

That registers BlogServer — all 14 tools — at the configured path. Nothing is exposed until you opt in, and enabling the flag without laravel/mcp installed simply yields no route rather than an error.

Enabling mcp also registers the signed /blog/preview/{post} route — used by GeneratePreviewUrlTool and Post::getUrl() — even when features.public_routes is off, so an agent can preview a draft or scheduled post in a browser before the public blog launches. The rest of the public routes stay dark.

Prefer to route it yourself? Leave the flag off and register the shipped server:

use Relaticle\Ink\Mcp\BlogServer;

Mcp::web('/mcp/blog', BlogServer::class)->middleware('auth:sanctum');

Authorization

Tools authorize through your application's Gate. Register a policy for Relaticle\Ink\Models\Post and Relaticle\Ink\Models\Category:

Gate::policy(Post::class, PostPolicy::class);
Gate::policy(Category::class, CategoryPolicy::class);

With no policy registered the Gate denies and every tool returns This action is unauthorized. — the tools fail closed.

Each tool maps to one Gate ability and one Sanctum token ability. The two are separate axes: the Gate decides what an identity may do, the token ability what a credential may do, so a token can be scoped more narrowly than the person holding it.

Instance-target tools resolve the record before authorizing, so a denial never doubles as an existence check.

Callers on another guard

If your staff authenticate on a guard other than the default — a separate admin model, for instance — point ink.mcp.guard at it. BlogTool resolves the caller from that guard.

Author attribution

CreatePostTool writes author_id, which is NOT NULL. By default the caller is used when it is already an ink.author_model instance. When it is not, supply the mapping in a service provider's boot():

use Relaticle\Ink\Ink;

Ink::resolveAuthorUsing(fn (SystemAdministrator $admin): ?User =>
    User::firstWhere('email', $admin->email));

Register it in a provider, never in config — a closure in a config file breaks config:cache. If no author resolves, the tool reports the misconfiguration instead of guessing.

Images

MCP's tools/call arguments are plain JSON — there is no binary channel for tool inputs — so UploadImageTool accepts either a fetchable url or base64-encoded data (exactly one of the two). The image type is detected by sniffing the actual bytes, never trusted from a filename or extension; only jpeg, png, gif and webp are accepted (no svg — it's a stored-XSS vector). Size is capped by ink.uploads.max_bytes — a HEAD request rejects an oversized url by its Content-Length before the body is downloaded where the server advertises one; the body itself is still measured against the cap either way.

'uploads' => [
    'disk' => 'public',       // matches the Filament featured-image field's disk
    'directory' => 'ink',     // matches its directory too — panel and MCP uploads share a home
    'max_bytes' => 3 * 1024 * 1024,
],

The tool returns a path (pass it as featured_image to create-post-tool / update-post-tool), a public url, and a ready-to-paste markdown snippet for in-content images:

{
  "path": "ink/01hz...webp",
  "url": "https://example.test/storage/ink/01hz...webp",
  "markdown": "![A dashboard screenshot](https://example.test/storage/ink/01hz...webp)"
}

featured_image on create-post-tool / update-post-tool only accepts a path upload-image itself produced — it's validated against the uploads disk and directory, so an agent can't point it at an arbitrary file. Pass featured_image: null on update-post-tool to clear it. Rendering assumes the public disk with storage:link run — the six asset('storage/…') call sites documented in the README are unchanged by this feature. Rendered post images get loading="lazy" and decoding="async" automatically on both render paths (Post::toHtml() and Post::toSafeHtml()), leaving any attribute the author declared by hand alone; there is no automatic resizing or srcset generation yet, so an oversized source image still costs bandwidth and LCP — keep uploads reasonably sized until a resizing pipeline ships.

Scheduling

A post with status: "published" and a future published_at is scheduled, not published immediately: Post::published() is evaluated at query time, so the post appears on the public index/show/feed/sitemap the moment the clock passes published_at, with no queue or command involved. Its signed preview URL (generate-preview-url-tool) keeps working right up until then.

Content format

The tools store the markdown you send, exactly as the Filament editor does; they do not convert it to HTML. Rendering — and therefore HTML sanitisation — happens at read time through your application's markdown configuration.

Extending

Custom blog tools should extend Relaticle\Ink\Mcp\BlogTool rather than Laravel\Mcp\Server\Tool. Its handle() is final and performs authorization before delegating, so a new tool cannot ship without it. Declare ability(), tokenAbility(), model() and run(); override resolveRecord() when the tool operates on one record.