{"_id":"@brokui/brok-mcp","_rev":"2-ca3adbbc12472a1d267d7bb14beb7547","name":"@brokui/brok-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@brokui/brok-mcp","version":"0.1.0","keywords":["mcp","laravel","blade","ui","registry"],"license":"MIT","_id":"@brokui/brok-mcp@0.1.0","maintainers":[{"name":"joshjml","email":"packages@jml-agency.com"}],"homepage":"https://brokui.dev/docs/mcp","bugs":{"url":"https://github.com/jml-agency/brok-mcp/issues"},"bin":{"brok-mcp":"dist/index.js"},"dist":{"shasum":"26ec1cf4c18a897f3456cf75014f86f81872fa33","tarball":"https://registry.npmjs.org/@brokui/brok-mcp/-/brok-mcp-0.1.0.tgz","fileCount":151,"integrity":"sha512-UkLgKlvCZKU7L3JgKVizPR2hzgBZkvk/zmvNmEjKKR2GV+I0kpeUtOi+Q6uULNnq079VfH+/uTQo5gj4F6ih4g==","signatures":[{"sig":"MEQCIBYHBbFZHXbCejrTpAjH1yqE/fyQI+GVRGw5iHIwA12mAiBk++A1eIf4CusF7Of/7c2pPPcNQogbFB+fiX3MxeUVnQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":853946},"type":"module","engines":{"node":">=26.0.0"},"gitHead":"3c271e6a199bbbe2613fdbf60fa52af3620b4ccc","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","test:stdio":"node test/stdio-smoke.mjs","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"joshjml","email":"packages@jml-agency.com"},"overrides":{"@hono/node-server":"^2.0.5"},"repository":{"url":"git+https://github.com/jml-agency/brok-mcp.git","type":"git"},"_npmVersion":"11.17.0","description":"MCP server exposing the Brok component registry to AI coding tools.","directories":{},"_nodeVersion":"26.5.0","dependencies":{"zod":"^3.23.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^5.5.0","@types/node":"^26.1.1"},"_npmOperationalInternal":{"tmp":"tmp/brok-mcp_0.1.0_1787849702344_0.11147063786045708","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@brokui/brok-mcp","version":"0.1.1","description":"MCP server exposing the Brok component registry to AI coding tools.","homepage":"https://brokui.dev/docs/mcp","keywords":["mcp","laravel","blade","ui","registry"],"license":"MIT","type":"module","bin":{"brok-mcp":"dist/index.js"},"engines":{"node":">=26.0.0"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","test:stdio":"node test/stdio-smoke.mjs","test:watch":"vitest","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.0"},"overrides":{"@hono/node-server":"^2.0.5"},"devDependencies":{"typescript":"^5.5.0","vitest":"^4.1.10","@types/node":"^26.1.1"},"gitHead":"5af12ec6024af5e564a1149c1faf5ebe667bea36","_id":"@brokui/brok-mcp@0.1.1","_nodeVersion":"26.5.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-/OSuI6UvAA6thf6JhrtG4RhtfXrxuujfWugUh7KzDHXK4uTcXiZUhqCbqW0HLyoAZ2zVs30o/nGkTRE5IHNl4g==","shasum":"e51fcdecfb8c17e0058a404208756aaee18e643c","tarball":"https://registry.npmjs.org/@brokui/brok-mcp/-/brok-mcp-0.1.1.tgz","fileCount":203,"unpackedSize":1209133,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDR7itgsDmURtj+rAiW4YDOgAiDlwIs7DFAfovptf0Y8AiA5N3eD/pLphgbmcj89Y0wAgCRcGA/Q3GuD+7QxMvF1DQ=="}]},"_npmUser":{"name":"joshjml","email":"packages@jml-agency.com"},"directories":{},"maintainers":[{"name":"joshjml","email":"packages@jml-agency.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/brok-mcp_0.1.1_1787850951680_0.15922465081206094"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-27T16:55:02.156Z","modified":"2026-08-27T17:15:52.063Z","0.1.0":"2026-08-27T16:55:02.612Z","0.1.1":"2026-08-27T17:15:51.865Z"},"license":"MIT","homepage":"https://brokui.dev/docs/mcp","keywords":["mcp","laravel","blade","ui","registry"],"description":"MCP server exposing the Brok component registry to AI coding tools.","maintainers":[{"name":"joshjml","email":"packages@jml-agency.com"}],"readme":"# @brokui/brok-mcp\n\nAn MCP (Model Context Protocol) server that exposes the [Brok](https://brokui.dev) component registry to AI coding tools like Claude Code and Cursor. Discovery and guidance only — installation always stays `php artisan ui:add <name>` in your Laravel app.\n\n## What it does\n\n`@brokui/brok-mcp` connects AI assistants to the Brok registry so they can:\n\n- Browse and search the full catalog of open and Pro components, blocks, pages, and bundles\n- Filter items by owner and inspect ownership, stability, review dates, known issues, support links, dependencies, and file targets\n- Read executable Blade examples and find blocks that compose a component\n- Read preferred `<brok:*>` and compatibility Blade usage, Livewire guidance,\n  prop value constraints, supported states, responsive behavior, design\n  rationale, and the release compatibility matrix\n- Validate Blade markup and retrieve version-scoped migration instructions\n- Resolve dependency graphs, install plans, release changes, and upgrade impact\n- Audit client-supplied project manifests and Blade source without reading project files\n- Generate validated Blade markup, a bounded Livewire class, and a Livewire Blade view without writing files\n- Discover, validate, and compare semantic design tokens and signed themes\n- Generate the correct `php artisan ui:add` command for any item\n- Build a ranked starter kit from a natural-language product intent\n- Diagnose registry connectivity and Pro authentication status\n\nThe server never writes files to your project. It provides information only; your agent runs `php artisan ui:add` to perform the actual installation.\n\nThe public npm package and Open registry are live. Pro registry access requires\na Brok license token.\n\n## Local development\n\nFrom the repository root, build the registry and MCP package, then run the\ncompiled server with explicit local tier roots:\n\n```bash\ndocker compose -f docker/compose.local.yml exec docs-app php artisan registry:build\ncd packages/mcp\nnpm ci\nnpm run build\nBROK_REGISTRY_LOCAL_OPEN=../../apps/docs-registry/public/r/open \\\nBROK_REGISTRY_LOCAL_PRO=../../apps/docs-registry/storage/app/registry/pro \\\nnode dist/index.js\n```\n\n## Published package configuration\n\n### npx (no install required)\n\n```bash\nnpx @brokui/brok-mcp\n```\n\n### Claude Code\n\n```bash\nclaude mcp add brok -- npx -y @brokui/brok-mcp\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"brok\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brokui/brok-mcp\"]\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `BROK_REGISTRY_URL` | `https://brokui.dev` | HTTPS base URL for `r/<tier>/...`. Set a local URL only for local development. |\n| `BROK_REGISTRY_LOCAL` | unset | Legacy combined root containing `<tier>/registry.json`; used when a tier-specific root is not configured. |\n| `BROK_REGISTRY_LOCAL_OPEN` | auto-detect | Open-tier directory containing `registry.json` directly. Auto-detects `apps/docs-registry/public/r/open`. |\n| `BROK_REGISTRY_LOCAL_PRO` | auto-detect | Pro-tier directory containing `registry.json` directly. Auto-detects `apps/docs-registry/storage/app/registry/pro`. |\n| `BROK_LICENSE_TOKEN` | unset | Bearer token for the `pro` tier. Obtain via `php artisan ui:auth` in your Laravel app. |\n| `BROK_DOCS_URL` | same as `BROK_REGISTRY_URL` | Base URL for documentation links returned by `get_item_examples`. |\n| `BROK_REGISTRY_WATERMARK_FILE` | user config directory | Persistent replay watermark file. The MCP server records the newest trusted registry release here. |\n| `BROK_REGISTRY_SIGNING_PUBLIC_KEY` | official Brok publisher key | One Base64 Ed25519 public key, or a comma-separated current/next keyring during rotation, used to authenticate open and Pro registry indexes. Override only for a private registry you control. |\n| `BROK_TRUSTED_REGISTRY_HOSTS` | `brokui.dev` | Comma-separated additional HTTPS hostnames allowed to receive `BROK_LICENSE_TOKEN`. Add only private registries you control. |\n| `BROK_MCP_UNSAFE_ALLOW_UNSIGNED_LOCAL` | unset | Set to `1` only for local development with unsigned files. It is ignored for HTTPS sources and reported prominently by `doctor`. |\n\nTier-specific variables override the legacy combined root for their tier, and all\nconfigured paths are normalized to absolute paths. Local Pro reads still require\n`BROK_LICENSE_TOKEN`; the token is sent only over HTTPS to the official host or an\nexact hostname explicitly listed in `BROK_TRUSTED_REGISTRY_HOSTS`.\n\nEach registry request has a 30-second ceiling. A complete root-plus-transitive\ndependency resolution also shares one 30-second operation budget. Traversal is\ncached, ordered, deduplicated, and cycle-safe; any descendant failure returns an\nerror instead of partial installation guidance. Network failures may fall back to\nthe configured local source while the shared operation budget remains live. Local\nfallbacks must carry detached signatures by default. The explicit unsafe local\noverride never disables signature verification for an HTTPS response.\n\nSuccessful registry responses are also byte-bounded before JSON parsing: indexes\nmay be at most 8 MiB and individual item manifests at most 2 MiB. The checked-in\ncatalog is currently about 1.1 MiB for the open index and roughly 40 KiB for its\nlargest item, so these limits leave substantial growth room while preventing an\nuntrusted endpoint from forcing unbounded buffering. Both declared\n`Content-Length` and streamed bytes are enforced; malformed UTF-8, malformed JSON,\nand payloads outside the documented registry schema fail as `invalid_registry`.\n\nBefore an index is parsed or cached, the server verifies its sibling\n`registry.sig`, the signed SHA-256 digest, the embedded publisher key, and the\nEd25519 signature against the pinned keyring. Open and Pro replay watermarks are\nkept separately by publisher and tier in a user-only persistent file, so a\nprocess restart does not clear downgrade protection. A legacy signed index without `issuedAt` can still be\nauthenticated, but cannot advance or benefit from replay detection. Every item\nmanifest is then matched against its signed tier entry and the same content and\nmetadata contract hashes used by the Laravel registry builder. Altered source,\nfile targets, dependencies, guidance, license metadata, or lifecycle metadata\ntherefore fails closed before a tool can return it.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_component` | Return the complete metadata and design-system contract for one component. |\n| `find_pattern` | Recommend a component pattern for a bounded natural-language use case and return the next MCP calls. |\n| `generate_code` | Return deterministic Blade usage plus a Livewire class and view as bounded file payloads. It does not write them. |\n| `list_items` | List registry items with `kind`/`tier`/`layer`/`owner` filters and bounded `limit`/`offset` pagination. |\n| `search_items` | Rank identity, intent, positive guidance, and contraindications; returns complete decision-routing metadata. |\n| `get_item` | Full manifest: type, architecture layer, ownership, stability, lifecycle dates, support links, preferred Blade and Livewire usage, props, slots, states, responsive behavior, rationale, accessibility, compatibility, examples, dependencies, migrations, and source files (pass `includeContent: true` for file source). |\n| `get_item_examples` | Executable Blade examples, items whose `registryDependencies` include the requested item, and docs links. |\n| `get_add_command` | The exact `php artisan ui:add <name>` command plus prerequisite notes. |\n| `doctor` | Diagnose registry reachability, active source (HTTP vs local), and Pro auth status. |\n| `build_kit` | Rank pages, blocks, components, bundles, and themes for a natural-language intent and return a recommended starting move. |\n| `compose_page` | Compose 1–50 ordered canonical block names into read-only install and Blade guidance. |\n| `validate_markup` | Validate Brok Blade markup for component contracts, required props, field wrappers, accessible names, keyboard behavior, raw controls, compatibility syntax, and raw color utilities. |\n| `get_migration` | Return ordered migration notes and declarative codemods for an item and optional version interval. Stable clients can pass `component` and installed `version`; existing clients can use `name`, `fromVersion`, and `toVersion`. |\n| `get_compatibility` | Return the machine-readable framework, package, foundation, and browser support contract from the signed Open index. |\n| `resolve_install_plan` | Resolve ordered transitive dependencies, target files, package prerequisites, conflicts, compatibility checks, and install commands. |\n| `audit_project` | Audit bounded, client-supplied lock data, package manifests, and Blade files for drift, updates, missing dependencies, deprecated APIs, markup errors, and token violations. |\n| `compare_items` | Compare two to ten items as a decision matrix for a stated use case. |\n| `plan_upgrade` | Build an ordered multi-item upgrade plan with migrations, codemods, breaking changes, and foundation requirements. |\n| `get_dependency_graph` | Return direct and transitive dependencies, reverse dependents, and cycles for one item. |\n| `impact_analysis` | Show the items, owners, and checks that a proposed item change can affect. |\n| `generate_markup` | Generate deterministic Brok Blade markup from declared props and slots, then validate it. |\n| `get_state_example` | Return executable source, preview guidance, responsive behavior, and accessibility evidence for one supported state. |\n| `get_release_changes` | Compare a project or complete prior-registry version inventory with the current signed registry and classify added, changed, deprecated, and removed items. |\n| `list_tokens` | List paginated design tokens by category, semantic role, or query. |\n| `get_token` | Return one token with its CSS variable, Tailwind utilities, category, source, and rationale. |\n| `validate_token_usage` | Validate Blade, HTML, CSS, or class strings for raw colors, spacing, typography, numeric layers, and unknown Brok token names. |\n| `suggest_token` | Rank semantic tokens for a bounded usage context and optional raw value. |\n| `compare_themes` | Compare CSS variable overrides from two to ten signed registry themes. |\n\nEvery successful tool response also exposes the same JSON payload through MCP `structuredContent`, so clients do not need to parse display text.\nNatural-language search and kit-building inputs are limited to 200 characters.\nCanonical registry names are limited to 160 characters and consist of lowercase\nalphanumeric kebab-case path segments separated by `/`. Invalid inputs are\nrejected before registry I/O.\n\n### Stable design-system workflow\n\n1. Call `find_pattern` with `use_case`.\n2. Call `get_component` with the recommended component name.\n3. Call `generate_code` with `component`, declared `props`, and optional default-slot `content`.\n4. Call `validate_markup` with the returned Blade view.\n5. Call `get_migration` when the consumer has an older installed version.\n\n`generate_code` returns `app/Livewire/*.php` and\n`resources/views/livewire/*.blade.php` payloads. It does not create those files,\nrun Artisan, infer application authorization, or execute supplied Blade content.\n\n### Paginating registry items\n\n`list_items` returns at most 50 items by default and accepts a maximum `limit` of 100. Start with `offset: 0`, then pass each non-null `nextOffset` into the next request:\n\n```json\n{\n  \"items\": [],\n  \"pagination\": {\n    \"total\": 0,\n    \"limit\": 50,\n    \"offset\": 0,\n    \"nextOffset\": null\n  }\n}\n```\n\nContinue until `nextOffset` is `null`. Totals include only items visible with the current Pro credentials.\n\n### Composing block guidance\n\nUse paginated `list_items` or `search_items` to discover canonical block names, then pass up to 50 names to `compose_page`. Names do not include the Pro transport prefix:\n\n```json\n{\n  \"blocks\": [\n    \"blocks/auth-02\",\n    \"blocks/admin/billing-page\"\n  ]\n}\n```\n\nThe result preserves block order in `bladeMarkup` and returns first-seen, deduplicated commands such as:\n\n```json\n{\n  \"installCommands\": \"php artisan ui:add blocks/auth-02\\nphp artisan ui:add pro/blocks/admin/billing-page\",\n  \"bladeMarkup\": \"<x-layouts.app>\\n    <x-blocks.auth-02 />\\n    <x-blocks.admin.billing-page />\\n</x-layouts.app>\"\n}\n```\n\nCommands are guidance only and are never executed; no files are written. If any name is invalid, inaccessible, not a block, or lacks an unambiguous block Blade target, the whole composition fails without partial markup.\n\n## Resources\n\nMCP clients can subscribe to or read stable JSON resource URIs without selecting a tool:\n\n| URI | Content |\n|-----|---------|\n| `brok://item/{name}` | Signed item contract without source-file content. |\n| `brok://examples/{name}` | Executable examples, states, and docs URL. |\n| `brok://migrations/{name}` | Versioned migrations and deprecation data. |\n| `brok://theme/{name}` | Signed theme metadata and CSS source. |\n| `brok://compatibility` | Signed framework and browser support matrix. |\n| `brok://tokens` | Generated semantic-token catalog. |\n| `brok://schemas/registry-item` | Registry contract and schema entry point. |\n\nItem and theme resource templates support MCP completion. Each resource listing is bounded to 1,000 signed Open-tier items.\n\n## Prompt templates\n\nThe server provides seven reusable MCP prompts:\n\n| Prompt | Purpose |\n|--------|---------|\n| `generate_application_ui` | Generate a complete Blade + Livewire application UI from approved blueprints, registry contracts, and semantic tokens. |\n| `select_component` | Select the best item for a use case and reject unsuitable alternatives. |\n| `review_blade_markup` | Review Blade against component and token contracts. |\n| `migrate_brok_project` | Create a read-only project upgrade plan. |\n| `compose_application_page` | Select and order blocks for an application page. |\n| `review_accessibility` | Review metadata requirements and supplied usage separately from browser evidence. |\n| `replace_deprecated_component` | Plan a safe replacement with migration data. |\n\nItem-name arguments provide completion from the signed registry index.\n\n`generate_application_ui` automatically routes recognized tasks to approved\n`ui:generate` blueprints. For example, account settings and password tasks use\n`pattern:settings-page`. Callers can also supply an explicit approved blueprint.\nEvery prompt includes a compact semantic-token vocabulary with category, CSS\nvariable, current value, approved utilities, and the core consistency rules.\nThe generation prompt also resolves the required component\ncontracts for its selected blueprint and includes their props, slots, states,\nusage, and accessibility requirements. If one contract is not available, the\nprompt identifies it and tells the agent to resolve it before generation.\nEvery response must follow `brok.ui-generation-output.v1`, which requires the\nblueprint decision, install guidance, token and component evidence, complete\nBlade and Livewire source, validation, accessibility, UI states, tests, and\nverification instructions. The prompt tells the agent to inspect signed MCP\nresources and to preview generator output before any file write.\n\n## Token contract\n\nThe token tools and `brok://tokens` resource use a generated snapshot of the canonical `packages/ui/resources/css/ui.css` `@theme` declarations. The snapshot includes its source SHA-256 digest. Repository and CI checks run `npm run tokens:mcp:check` so token metadata cannot drift from the canonical CSS file.\n\n## Read-only project audit\n\n`audit_project` does not accept project paths and does not read arbitrary files. The client supplies bounded `ui-lock.json`, `composer.json`, `package.json`, and Blade content in the request. The tool validates that content and returns findings only. It does not install packages, execute commands, or write fixes.\n\n## Pro components\n\nPro items require a license token. To set one up:\n\n1. In your Laravel app, run: `php artisan ui:auth`\n2. Export the token: `export BROK_LICENSE_TOKEN=<your-token>`\n3. Or set it in your MCP client config via the `env` key.\n\nWithout a token, the server returns a structured `auth_required` result instead of throwing.\nCommands returned for visible Pro items include the required `pro/` prefix, for example `php artisan ui:add pro/blocks/admin/billing-page`.\n\nDocumentation links follow the registry kind: components use `/docs/components/<name>`, blocks use `/blocks/<slug>`, pages use `/pages/<slug>`, bundles use `/bundles`, and themes use `/theme-generator#presets`.\n\n## Prerequisites (for consumers)\n\nBefore `ui:add` can run, you need the Brok package installed:\n\n```bash\ncomposer require jml/brok\nphp artisan ui:install\n```\n\nThen add any component:\n\n```bash\nphp artisan ui:add button\nphp artisan ui:add blocks/auth-02\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}