{"id":49084514,"url":"https://github.com/dirnbauer/typo3-agentation","last_synced_at":"2026-04-20T14:15:49.350Z","repository":{"id":352397393,"uuid":"1214876151","full_name":"dirnbauer/typo3-agentation","owner":"dirnbauer","description":"TYPO3 v14 integration for Agentation — visual UI annotations for AI coding agents (FE Admin Panel + BE User Settings + MCP).","archived":false,"fork":false,"pushed_at":"2026-04-19T12:24:27.000Z","size":166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T12:29:02.276Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dirnbauer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T07:01:31.000Z","updated_at":"2026-04-19T12:24:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dirnbauer/typo3-agentation","commit_stats":null,"previous_names":["dirnbauer/typo3-agentation"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dirnbauer/typo3-agentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirnbauer%2Ftypo3-agentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirnbauer%2Ftypo3-agentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirnbauer%2Ftypo3-agentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirnbauer%2Ftypo3-agentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dirnbauer","download_url":"https://codeload.github.com/dirnbauer/typo3-agentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirnbauer%2Ftypo3-agentation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32050577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-20T14:15:48.491Z","updated_at":"2026-04-20T14:15:49.342Z","avatar_url":"https://github.com/dirnbauer.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EXT:agentation — Agentation for TYPO3 v14\n\nVisual UI annotations for AI coding agents — right inside your TYPO3 frontend **and** backend.\nWraps the [`agentation`](https://www.agentation.com/) npm package so users can click elements,\nannotate, and share structured context (CSS selectors, file paths, computed styles, user\nfeedback) with Claude Code, Cursor, or any MCP-capable agent.\n\n## Features mapped from agentation.com\n\n| Agentation feature | How this extension surfaces it |\n| --- | --- |\n| Element annotation toolbar | Loaded in FE + BE when enabled; position configurable |\n| Hover previews / frame pausing / text selection | Provided by upstream `agentation@^3` bundle |\n| Markdown export | Native upstream feature |\n| MCP (Model Context Protocol) server | BE module renders pre-filled `.mcp.json` snippet, one-click copy |\n| Webhooks | Configurable webhook URL in extension config, forwarded to toolbar init |\n| API key / workspace ID | Extension configuration (install tool) |\n| Framework-agnostic | Vanilla Vite bundle, zero React/Vue/Angular assumptions |\n\n## Requirements\n\n- TYPO3 ^14.0\n- PHP ^8.2\n- `typo3/cms-adminpanel` (bundled with v14)\n- Node 20+ for the build step (only needed at install time / when updating)\n- No TYPO3-side Vite integration extension needed — the built-in `ViteAssetResolver` reads `Resources/Public/Vite/manifest.json` directly.\n\n## Install\n\n```sh\ncomposer require webconsulting/agentation\ncd vendor/webconsulting/agentation   # or your extension path\nnpm install\nnpm run build\n```\n\n`npm run build` writes hashed assets + `manifest.json` into\n`Resources/Public/Vite/`. The PHP side reads the manifest at request time, so\nyou only need to rebuild when upgrading `agentation` on npm.\n\n## Configuration\n\nOpen **Admin Tools → Settings → Extension Configuration → agentation**.\n\n![Extension Configuration — basic tab](Documentation/Images/extension-configuration-basic.png)\n\n### Basic tab\n\n| Key | Type | Default | Purpose |\n| --- | --- | --- | --- |\n| `apiKey` | string | _empty_ | Agentation API key. Leave empty for free local-only mode (copy-paste markdown). Required for MCP + webhooks. |\n| `workspaceId` | string | _empty_ | Workspace / project ID shown in the MCP snippet and sent to the toolbar. |\n| `frontendEnabled` | boolean | ✓ | Global on/off for the FE toolbar. Still gated per BE-user via Admin Panel opt-in. |\n| `backendEnabled` | boolean | ✓ | Global on/off for the BE toolbar. Still gated per BE-user via User Settings → Agentation tab. |\n| `contextGate` | options | `Development` | `Development`, `Development and Testing`, or `All contexts`. Prevents production leaks. |\n| `defaultOptIn` | boolean | ✗ | Whether new BE users see the toolbar on by default (they can still toggle off). Tick this to skip the per-user opt-in step during initial setup. |\n\n### Advanced tab\n\n| Key | Type | Default | Purpose |\n| --- | --- | --- | --- |\n| `toolbarPosition` | string | `bottom-right` | `bottom-right` / `bottom-left` / `top-right` / `top-left`. |\n| `webhookUrl` | string | _empty_ | Forwarded to the toolbar; annotations POST here with an `Authorization: Bearer \u003capiKey\u003e` header if set. |\n| `additionalOptions` | JSON string | _empty_ | Raw JSON merged into the toolbar's props. Escape hatch for upstream features (e.g. `{\"enableDemoMode\": true}`). |\n\n### Where the screenshot lives\n\nSave it as `Documentation/Images/extension-configuration-basic.png` inside the extension directory. The README links to it relatively so it also renders on GitHub.\n\n## Frontend: Admin Panel section\n\nWhen a BE user is authenticated in the frontend and the application context matches\nthe gate, a new **Agentation** section appears in the TYPO3 Admin Panel. It exposes:\n\n- **Show toolbar on this page** — per-session opt-in\n- **Toolbar position** — override extension default\n- **Annotation scope** — `frontend` (ignore the admin panel chrome) or `frontend+adminpanel`\n\nNo toolbar ever ships to anonymous visitors. The gate is:\n\n```\ncontextGate passes  AND  BE user session  AND  admin panel section toggled on\n```\n\n## Backend: User Settings switch\n\nEach BE user gets an **Agentation** tab under **User Settings → Personal data** with:\n\n- Enable toolbar in backend\n- Enable toolbar in frontend (used alongside the Admin Panel opt-in)\n\nStored in `be_users.uc`, so admins can't force it globally — respect by design.\n\n## Backend module\n\nA module under **System → Agentation** (admin-only) shows:\n\n- Pre-filled `.mcp.json` snippet with one-click copy\n- Status: API key set, bundle built, context allowed, FE/BE toggles\n- Link to agentation.com\n\n## MCP — yes, and here's how\n\nThe `agentation` npm package ships an MCP server. Any agent that supports MCP\n(Claude Code, Cursor, Windsurf, Zed, Continue, Cline…) can connect to it and\nreceive annotations in real time instead of copy-paste.\n\n1. Open the **Agentation** backend module.\n2. Copy the shown JSON into your agent's MCP config:\n   - **Claude Code** — `~/.claude/mcp.json` (or project `.mcp.json`)\n   - **Cursor** — Settings → Features → MCP\n   - **Windsurf / Zed / Continue** — equivalent MCP servers section\n3. Reload your agent. It now has a tool like `agentation__get_annotation`.\n4. Click annotate in the toolbar, add a note — your agent can ask clarifying\n   questions and resolve the feedback against the codebase directly.\n\nExample (also at `.mcp.json.example`):\n\n```json\n{\n  \"mcpServers\": {\n    \"agentation\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentation\", \"mcp\"],\n      \"env\": {\n        \"AGENTATION_API_KEY\": \"your-api-key\",\n        \"AGENTATION_WORKSPACE\": \"your-workspace-id\"\n      }\n    }\n  }\n}\n```\n\nAPI key and workspace are only needed when you want multi-device sync or team\nsharing. The toolbar itself works locally without them.\n\n## Framework-agnostic (from the host page)\n\nThe `agentation` npm package is a React component under the hood. To keep\nthe integration framework-agnostic **from the TYPO3 site's perspective**,\nVite bundles agentation's React runtime + React DOM + our glue into a\nsingle self-contained ES module (~540 KB, ~136 KB gzipped).\n\n- Your TYPO3 site does **not** need React, Vue, or Angular.\n- If it already ships React for something else, our bundle runs its own\n  isolated instance via `createRoot` into a detached `#typo3-agentation-root`\n  container — no version conflicts, no hydration issues.\n- Toolbar config is passed via a single inline `\u003cscript\u003e` tag writing\n  `window.TYPO3Agentation` — no custom elements, no shadow DOM, no coupling\n  to host frameworks.\n\n## Security notes\n\n- Toolbar never loads for anonymous FE visitors. It requires a valid BE session.\n- `contextGate` blocks production by default.\n- API key is rendered into the BE module only — never exposed to the FE unless\n  the FE user is the same BE user (which they are, by design, since the\n  toolbar only runs when BE session is active).\n\n## License\n\nGPL-2.0-or-later\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirnbauer%2Ftypo3-agentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdirnbauer%2Ftypo3-agentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirnbauer%2Ftypo3-agentation/lists"}