{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreicod53du6mjw6yzho6y3t47bdifetfqh67g7z6aqcfj4xmuftj37q",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3monb464xl5m2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreibb7ai5kh2omigz3curdwybxzh7biulihtt3hg23lbzo3rsrkgr5q"
    },
    "mimeType": "image/webp",
    "size": 89692
  },
  "path": "/nasrulhazim/dev-log-2026-06-19-mcp-servers-everywhere-email-that-tracks-itself-and-menus-that-behave-19il",
  "publishedAt": "2026-06-19T11:20:43.000Z",
  "site": "https://dev.to",
  "tags": [
    "laravel",
    "php",
    "architecture",
    "opensource",
    "laravel-mcp-kit",
    "mail-history",
    "kickoff",
    "agent-skills"
  ],
  "textContent": "If today had a spine, it was MCP. I shipped the generic MCP toolbox into a public package and stood up MCP servers across a cluster of enterprise apps — same gate-first pattern, different domains. Around that, two other threads ran all day: making transactional email _tell you whether it was opened_ , and getting nested admin sidebars to behave across a half-dozen apps. Busy day. Here's the log.\n\n##  MCP toolbox, and three servers that use the pattern\n\nThe public, teachable piece I wrote up separately: `cleaniquecoders/laravel-mcp-kit` got a **generic, opt-in toolbox** — the ops tools (`whoami`, log tailing, failed-job retry, queue status, token management) that I kept rewriting in every MCP server. The trick is that each tool registers _only_ when its backing package is present, and every tool is gated and uuid-only. Full write-up is in today's focused post, so I won't repeat the code here.\n\nWhat's worth adding in the log is _why_ that package exists: today I also wired full MCP servers into a set of private enterprise platforms — an identity/IAM system, an API-gateway manager, and a user portal. Each got the same shape: read-only diagnostic tools behind an ability gate, a handful of write tools that funnel through Actions, and a small Livewire admin card to toggle the server and manage tokens. Building three of them back-to-back is exactly what surfaced the generic spine worth extracting. The rule I held to across all of them: **the agent gets read tools freely, write tools sparingly, and every write goes through a human-gated runbook** — orient, observe, diagnose, propose, then stop at the gate. An MCP server that can _do_ things is only safe if the dangerous verbs are few, audited, and explicitly authorized.\n\nA couple of generic hardening lessons fell out of that work, worth passing on because they bite any MCP build:\n\n  * **Hash passwords in the create-user tool, never store plaintext.** Obvious in hindsight, easy to miss when a tool is \"just\" forwarding input to a model. An MCP tool is an untrusted entry point like any controller — treat its input with the same suspicion.\n  * **Emit the public UUID, not the internal id, in audit/list tools.** A list tool that returns sequential primary keys leaks row counts and invites enumeration. The public id is the uuid; the internal id stays internal.\n  * **Add a STDIO actor fallback for resources.** When a tool can run over both HTTP and STDIO transports, \"who is the current user\" has to resolve in both — don't assume an HTTP request context is always there.\n\n\n\n##  Email that tracks itself\n\nThe other public thread: `cleaniquecoders/mail-history` learned to **auto-inject open and click tracking** , plus a universal `X-Metadata-hash` header on every outgoing message.\n\nThe teachable bit is _where_ the injection happens. You don't want every `Mailable` in your app to remember to add a tracking pixel and rewrite its links — that's the kind of cross-cutting concern that rots the moment one developer forgets. Instead it hangs off a mail-sending listener: as a message goes out, the listener rewrites the HTML body to inject the open pixel and wrap trackable links, and stamps a metadata hash so every message is correlatable later. The app code stays oblivious; tracking is a property of the _pipeline_ , not of each message.\n\nTwo edges worth flagging, because they're the difference between \"tracking works\" and \"tracking silently does nothing\":\n\n  * **`Mail::raw()` defeats open/click tracking.** Raw messages skip the HTML rewriting path entirely — there's no body to inject a pixel into the way you'd expect. If you care about opens, send a real HTML `Mailable`. I went and fixed a \"test email\" feature that was using `Mail::raw` and therefore never recording an open; switching it to a proper HTML mailable made the Opened/Clicked statuses light up.\n  * **Tracking on by default is a decision, not an accident.** I flipped the default to _on_. Defaults are a stance — if the feature only works when someone remembers to enable it, most installs never get it. Ship the useful default and let people opt out.\n\n\n\nA Pest sketch of the kind of test that guards the injection listener:\n\n\n\n    it('injects an open pixel and rewrites links in an html mail', function () {\n        Event::fake([MessageSending::class]);\n\n        Mail::to('user@example.test')->send(new DefaultMail(html: '<p>Hi <a href=\"https://example.test\">link</a></p>'));\n\n        // the listener should have stamped a correlatable hash\n        // and rewritten the body — assert on the resulting message,\n        // not on the mailable you handed in.\n        expect($lastSentBody)\n            ->toContain('/mail/open/')      // the injected pixel route\n            ->toContain('/mail/click/');    // the wrapped link\n    });\n\n\nThe principle: test the _outgoing_ message, not the `Mailable` you constructed. The whole point of the feature is that it changes the message _after_ your app is done with it, so asserting on your own input proves nothing.\n\n##  Menus and sidebars that behave\n\nA big slice of the day, across both my public scaffolder (`cleaniquecoders/kickoff`) and a few private enterprise apps, was admin-navigation work: a **nested Administration group** with right-chevron grouping, label truncation so long menu items don't break the layout, and a subtle vertical guide line down the children of an expanded group.\n\nThe pattern worth extracting isn't the CSS — it's how the menu is _built_. The whole sidebar is assembled from small invokable builder classes (one per group: `Administration`, `UserManagement`, `AuditMonitoring`, `Settings`), each declaring its own items, route, and required ability. That keeps navigation declarative and permission-aware: a group renders only what the current user may actually reach, and you add a section by dropping in a class, not by editing one ever-growing Blade file. When the same nav has to exist in five apps, a class-per-group structure is the only thing that stays maintainable — you compose, you don't copy.\n\nThe fiddly cross-app gotchas that ate real time:\n\n  * **A child route needs route-params support.** A \"Mail History\" link kept pointing at the wrong route because the child-item helper couldn't pass route parameters. Easy to miss until a deep link 404s.\n  * **Truncate labels at the component, not per-item.** Centralize the truncation in the navlist component so every label behaves the same; do it per-item and one menu entry will always be the odd one out.\n  * **Gate developer/ops tooling behind both an ability and the edition.** Surfacing things like Telescope or MCP token management in the menu is great — but only for users who may see them, and only in editions that ship them. Two gates, not one.\n\n\n\n##  Telescope, on by default (carefully)\n\nSmall but recurring theme across the scaffolder and the apps: I enabled **Telescope by default** so a freshly provisioned app actually serves `/telescope` instead of 404-ing, and set the dashboard route to register without needing an extra env var. The nuance — same as the mail-tracking default — is that a diagnostic tool nobody enabled is a diagnostic tool nobody has when the incident hits. Default it on, keep it gated, and let people scope or disable it. Visibility you have to remember to turn on is visibility you won't have at 2am.\n\n##  The skill that checks the work\n\nFinally, a quieter public win: my `kickoff-patch` agent skill (in `nasrulhazim/agent-skills`) got a hardened **verify step**. When the skill applies a patch to a scaffolded app, it now checks for the gaps that actually break a fresh install — uninstalled packages a stub quietly depends on, permissions that were never seeded, env keys that aren't set, migrations that didn't run, and stub-vs-project ownership mismatches. It also notes the `Mail::raw` tracking gotcha from above, so the lesson lives in the tooling and not just in my head.\n\nThat's the thread tying the whole day together, honestly: **make the safety net automatic.** Tracking on by default, Telescope on by default, a verify step that knows the usual ways a fresh app falls over. The best lesson is the one you encode so you never have to relearn it.\n\nPublic repos if you want to dig in: laravel-mcp-kit, mail-history, kickoff, and agent-skills.",
  "title": "Dev Log: 2026-06-19 — MCP Servers Everywhere, Email That Tracks Itself, and Menus That Behave"
}