# Heisenberg

> A block-based content engine and bilingual blog backend for Laravel Gutenberg-style editor, media library, post templates, roles, and an AI writing assistant, with zero host coupling.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tedydonel-heisenberg`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tedydonel](https://agentstack.voostack.com/s/tedydonel)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [tedydonel](https://github.com/tedydonel)
- **Source:** https://github.com/tedydonel/Heisenberg

## Install

```sh
agentstack add mcp-tedydonel-heisenberg
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Heisenberg

  A block-based content engine and bilingual blog backend for Laravel.
  Drop a full Gutenberg-style editor, media library, taxonomy, post templates and an AI writing assistant into any Laravel app.

  
  
  
  

---

Heisenberg has **no users, no theme lock-in and no frontend framework**. Your app keeps its users, its routes and its pages — Heisenberg brings the editor at `/editor`, the content model, and narrow contracts you bind to make everything yours.

## Installation

```bash
composer require heisenberg/heisenberg
php artisan migrate
php artisan storage:link   # public media URLs (the uploads link is pre-registered)
```

That's it — open **`/editor`**. The service provider is auto-discovered, migrations load automatically, and every seam ships a working default. On a machine where `APP_ENV=local`, everything works anonymously out of the box; real deployments authorize through your own users (below).

Optional but recommended:

```bash
composer require intervention/image:^3.9   # responsive image variants (v4 is NOT compatible)
```

## Connecting your users

Heisenberg never creates users. Your existing users get abilities through the `RoleGate` contract, with four canonical roles — WordPress-familiar:

| Role | Can |
|---|---|
| `admin` | everything, including AI/provider settings |
| `editor` | publish, schedule, archive; manage anyone's media |
| `author` | write and draft; upload media; edit own files |
| `viewer` | browse and pick media, read-only |

The bundled gate reads either **Spatie permissions** (`getRoleNames()`) or a plain **`role` string column** on your user model:

```php
Schema::table('users', fn (Blueprint $t) => $t->string('role')->nullable());
// then: $user->role = 'editor';
```

Different role names in your app? Remap them in `config/heisenberg.php` under `roles`, or bind your own `RoleGate` implementation entirely. Production apps should also wrap the route groups in their own auth middleware (`heisenberg.middleware.editor` / `.media` / `.ai`, all default `['web']`).

## Publishing content with your own templates

Heisenberg renders block content; **you own the page around it**. A post template is a JSON contract declaring which chrome capabilities the page has — featured image, authored table of contents, reading time, breadcrumbs, share buttons, comments, and more:

```php
// config/heisenberg.php (php artisan vendor:publish --tag=heisenberg-config)
'template_root' => resource_path('heisenberg-templates'),
```

```jsonc
// resources/heisenberg-templates/mysite/mysite.json
{
  "name": "heisenberg/mysite",
  "render": { "view": "blog.show" },   // YOUR Blade view
  "capabilities": {
    "featuredImage":   { "enabled": true, "source": "post-attribute", "context": "hero" },
    "tableOfContents": { "enabled": true, "source": "entries" },
    "comments":        { "enabled": true, "allowGuests": true, "sortOrder": "newest" }
  }
}
```

Validate with `php artisan templates:verify`. In your controller, resolve `PostTemplateRegistryService` from the container, read the contract, and render the body exactly like the built-in preview does (`BlockRenderer::renderBlocks()` plus the block/theme stylesheets). The full schema — all 11 capabilities and the render-vs-adapter decision for each — is in [`docs/post-template-schema.md`](docs/post-template-schema.md).

Data Heisenberg doesn't own arrives through **provider contracts** with null defaults — bind yours in the published config:

```php
'post_template' => [
    'comments_provider' => App\Support\MyCommentProvider::class,  // implements PostCommentProvider
    // post_views_provider, related_posts_provider, seo_meta_provider
],
```

## What the editor gives your authors

- **Twelve block types** — headings, paragraphs, images, buttons, quotes, lists, icons, separators, embeds, and nestable groups/columns — each defined by a JSON contract, validated server-side, rendered through a sanitizing pipeline.
- **Full-page authoring chrome** — inspector, floating toolbar, navigator tree, undo/redo, revisions, autosave with optimistic locking, drag & drop, dark mode, `en`/`fr` UI.
- **Post management** — status lifecycle (draft → review → published/scheduled/archived, tier-gated), categories & tags, featured image, authored table of contents, page layout and discussion settings.
- **Media library** — drag-drop uploads with per-file progress, responsive variants, bilingual alt/caption metadata, virus-scan seam (`VirusScanner` contract), collision-safe naming (`photo(1).jpg`), role-scoped permissions.
- **Visual ⇄ Code view** — the whole document round-trips through a compact shortcode dialect (see [`docs/code-view.md`](docs/code-view.md)).
- **AI writing assistant** — bring your own provider (Anthropic, OpenAI, or any OpenAI-compatible endpoint; keys stored write-only and encrypted). The assistant writes to the live canvas through a validated tool call, streams its reasoning, and remembers conversations. Works with MCP in both directions: connect external MCP servers to the assistant, and/or expose Heisenberg itself as an MCP server so external agents can author drafts via bearer token.

## Configuration surface

`php artisan vendor:publish --tag=heisenberg-config` gives you `config/heisenberg.php`: table names and model classes (all swappable), role map, lifecycle transitions, media rules (size caps, allowed extensions, virus scanner), template root, AI provider settings, and the middleware stacks for each route group. Every contract (`RoleGate`, `MediaResolver`, `VirusScanner`, `AuditSink`, `IconProvider`, the four template providers) is a config-named binding with a working default.

## Security posture

- Every content write funnels through one validated, sanitizing pipeline (HTML Purifier at the XSS boundary); nothing bypasses it — including AI- and MCP-authored content.
- Media uploads: extension allowlist, size caps, scan-before-write, no PHP in the public read path (see [`docs/media-library-backend-blueprint.md`](docs/media-library-backend-blueprint.md) for the web-server hardening snippets).
- The anonymous local-dev convenience is structurally incapable of activating outside `APP_ENV=local`.
- The inbound MCP server is disabled by default and draft-only when enabled.

## Documentation

| Doc | What it covers |
|---|---|
| [`docs/BLUEPRINT.md`](docs/BLUEPRINT.md) | The full specification — every class, column, contract key and security gate |
| [`docs/block-schema.md`](docs/block-schema.md) | Writing block contracts |
| [`docs/post-template-schema.md`](docs/post-template-schema.md) | Writing post templates |
| [`docs/code-view.md`](docs/code-view.md) | The shortcode dialect |
| [`docs/media-library-backend-blueprint.md`](docs/media-library-backend-blueprint.md) | The media subsystem, end to end |
| [`docs/ai-mcp-plan.md`](docs/ai-mcp-plan.md) | The AI assistant and MCP integration |

## Requirements

PHP ^8.2 · Laravel 11 / 12 / 13 · Livewire ^4.3

## License

[Apache-2.0](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tedydonel](https://github.com/tedydonel)
- **Source:** [tedydonel/Heisenberg](https://github.com/tedydonel/Heisenberg)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tedydonel-heisenberg
- Seller: https://agentstack.voostack.com/s/tedydonel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.