https://github.com/dirnbauer/webcon-mcp-chat-bridge

Webcon MCP Chat Bridge TYPO3 extension
https://github.com/dirnbauer/webcon-mcp-chat-bridge

Last synced: about 1 month ago
JSON representation

Webcon MCP Chat Bridge TYPO3 extension

Host: GitHub
URL: https://github.com/dirnbauer/webcon-mcp-chat-bridge
Owner: dirnbauer
License: other
Created: 2026-06-28T13:44:07.000Z (about 1 month ago)
Default Branch: main
Last Pushed: 2026-07-01T21:40:44.000Z (about 1 month ago)
Last Synced: 2026-07-01T23:25:26.567Z (about 1 month ago)
Language: PHP
Size: 162 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Webcon MCP Chat Bridge

TYPO3 extension that turns Slack, Microsoft Teams, WhatsApp, and other
channel adapters into a controlled bridge to `hn/typo3-mcp-server`.

The extension does not implement a second TYPO3 write layer. Channel requests
resolve a backend user, then execute MCP tools such as `CreateSite`,
`WriteTable`, `ImportContent`, `WorkspaceReview`, and `GetPreviewUrl` inside
TYPO3 with normal permissions, TCA validation, workspaces, history, and
DataHandler behavior.

## Features

- Public token-protected MCP chat bridge API at `/webcon-mcp-chat-bridge/api`
- Direct MCP tool listing, single calls, and bounded batch execution
- Opinionated site creation action backed by MCP `CreateSite`
- Strict document/news text import that only uses supplied text and writes via
MCP `WriteTable`
- DDEV/development bypass for unsigned local requests
- Slack incoming webhook notifications
- Slack slash-command adapter for interactive chat commands
- Slack Events API chatbot adapter for app mentions, direct messages, and
uploaded PDF/text-file imports
- Optional Slack-to-`nr_mcp_agent` wrapper for free-form AI request/response
chat without a Flue sidecar
- Slack context wrapper that keeps one AI conversation per Slack thread and
injects Slack/TYPO3 context into each request
- Microsoft Teams webhook/adaptive-card notifications
- WhatsApp Cloud API notifications
- Backend user settings for provider preferences and external identity mapping
- Workspace actions:
- list pending workspace records
- move selected records to an approval stage
- move selected records to `Ready to publish` and publish them
- `@claude` mentions inside TYPO3 (GitHub-style):
- workspace stage-change comments containing `@claude …` get an AI reply
posted back into the workspace comment history
- internal notes (`sys_note`) containing `@claude …` are answered with a
new note on the same page
- a **Claude Chat** backend module (Tools) with workspace selector, powered
by the same optional `nr_mcp_agent` brain as the Slack chatbot
- AI workspace reviewer with per-workspace settings on the `sys_workspace`
record (AI Review tab): review & recommend (default), advance stage on
approval, or full auto-publish; every verdict is audited in
`tx_webconmcpchatbridge_ai_review` (see `Documentation/ClaudeMentions.rst`)

## Installation

Install as a path package or move this directory into its own repository:

```bash
composer require webconsulting/webcon-mcp-chat-bridge
bin/typo3 extension:setup
```

For local development in this repository, add it as a Composer path
repository in the TYPO3 project that should load it.

The package requires `hn/typo3-mcp-server`; install and configure that
extension in the same TYPO3 instance.

## Step-by-step mini manual

1. Install the extension and the TYPO3 MCP server.
2. Create or choose the backend user that chat actions should run as.
3. Create an editorial workspace, for example workspace `1`.
4. Add an approval stage, for example `Chief editor approval` with stage ID `1`.
5. Configure the bridge and keep tokens/webhooks in environment variables.
6. Connect backend users to chat identities in the `MCP Chat Bridge` settings
tab.
7. Create a Slack slash command that posts to `/webcon-mcp-chat-bridge/slack`.
8. For chatbot mode, enable Slack Events API at
`/webcon-mcp-chat-bridge/slack/events` and add a bot token.
9. Test `ping`, `mcp.tools`, and one notification before enabling automation.

Minimal project configuration:

```php
$slackWebhook = getenv('WEBCON_MCP_CHAT_BRIDGE_SLACK_WEBHOOK') ?: '';
$slackSigningSecret = getenv(
'WEBCON_MCP_CHAT_BRIDGE_SLACK_SIGNING_SECRET'
) ?: '';
$slackBotToken = getenv('WEBCON_MCP_CHAT_BRIDGE_SLACK_BOT_TOKEN') ?: '';
$slackBotUserId = getenv(
'WEBCON_MCP_CHAT_BRIDGE_SLACK_BOT_USER_ID'
) ?: '';
$teamsWebhook = getenv('WEBCON_MCP_CHAT_BRIDGE_TEAMS_WEBHOOK') ?: '';
$whatsAppPhoneNumberId = getenv(
'WEBCON_MCP_CHAT_BRIDGE_WHATSAPP_PHONE_NUMBER_ID'
) ?: '';
$whatsAppAccessToken = getenv(
'WEBCON_MCP_CHAT_BRIDGE_WHATSAPP_ACCESS_TOKEN'
) ?: '';

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['webcon_mcp_chat_bridge'] = [
'enabled' => true,
'apiPath' => '/webcon-mcp-chat-bridge/api',
'slackCommandPath' => '/webcon-mcp-chat-bridge/slack',
'slackEventsPath' => '/webcon-mcp-chat-bridge/slack/events',
'apiToken' => getenv('WEBCON_MCP_CHAT_BRIDGE_API_TOKEN') ?: '',
'allowUnsignedDevelopmentRequests' => true,
'developmentBackendUserId' => 1,
'approvalStageId' => 1,
'defaultWorkspaceId' => 1,
'allowedTables' => 'pages,tt_content,tx_news_domain_model_news',
'slackEnabled' => true,
'slackWebhookUrl' => $slackWebhook,
'slackSigningSecret' => $slackSigningSecret,
'slackBotToken' => $slackBotToken,
'slackBotUserId' => $slackBotUserId,
'teamsEnabled' => false,
'teamsWebhookUrl' => $teamsWebhook,
'whatsappEnabled' => false,
'whatsappPhoneNumberId' => $whatsAppPhoneNumberId,
'whatsappAccessToken' => $whatsAppAccessToken,
'whatsappDefaultRecipients' => '',
];
```

Do not leave `WEBCON_MCP_CHAT_BRIDGE_API_TOKEN` empty outside a local
development context. The full TYPO3 documentation entry point is
`Documentation/Index.rst`; the step-by-step guide is
`Documentation/QuickStart.rst`.

## Environment variables

Use environment variables for secrets and provider credentials. Do not commit
real values to Git.

`WEBCON_MCP_CHAT_BRIDGE_API_TOKEN`
: A random token you generate yourself. It protects direct JSON API calls to
`/webcon-mcp-chat-bridge/api`. Generate one with `openssl rand -hex 32` and
send it as `Authorization: Bearer `.

`WEBCON_MCP_CHAT_BRIDGE_SLACK_WEBHOOK`
: Slack incoming webhook URL. It lets TYPO3 post notifications into the Slack
channel selected when the webhook was installed, for example `#typo3-lab`.
It usually starts with `https://hooks.slack.com/services/...`.

`WEBCON_MCP_CHAT_BRIDGE_SLACK_SIGNING_SECRET`
: Slack app signing secret from **Basic Information > App Credentials**. It is
used to verify requests sent by Slack to `/webcon-mcp-chat-bridge/slack` and
`/webcon-mcp-chat-bridge/slack/events`. Configure it before exposing Slack
endpoints through a tunnel.

`WEBCON_MCP_CHAT_BRIDGE_SLACK_BOT_TOKEN`
: Slack bot token, usually starting with `xoxb-`. Required for Slack Events
API chatbot replies and uploaded file downloads.

`WEBCON_MCP_CHAT_BRIDGE_SLACK_BOT_USER_ID`
: Optional Slack bot user ID, for example `U012ABCDEF`. Recommended if you
subscribe to normal channel message events.

`WEBCON_MCP_CHAT_BRIDGE_TEAMS_WEBHOOK`
: Microsoft Teams webhook or Workflow URL for Teams notifications.

`WEBCON_MCP_CHAT_BRIDGE_WHATSAPP_PHONE_NUMBER_ID`
: WhatsApp Cloud API phone number ID.

`WEBCON_MCP_CHAT_BRIDGE_WHATSAPP_ACCESS_TOKEN`
: WhatsApp Cloud API bearer token.

`WEBCON_MCP_CHAT_BRIDGE_WHATSAPP_RECIPIENTS`
: Optional comma-separated fallback WhatsApp recipients in E.164 format.

Full environment documentation is in `Documentation/EnvironmentVariables.rst`.

## API examples

Ping the bridge:

```bash
curl -s https://example.test/webcon-mcp-chat-bridge/api \
-H "Authorization: Bearer $WEBCON_MCP_CHAT_BRIDGE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"ping"}'
```

List MCP tools:

Call one MCP tool:

```bash
curl -s https://example.test/webcon-mcp-chat-bridge/api \
-H "Authorization: Bearer $WEBCON_MCP_CHAT_BRIDGE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "mcp.call",
"backendUserId": 5,
"workspaceId": 1,
"tool": "WriteTable",
"params": {
"action": "create",
"table": "pages",
"pid": 42,
"data": {"title": "TYPO3 Developer Days"}
}
}'
```

Import exact document text as a page after an existing page:

```bash
curl -s https://example.test/webcon-mcp-chat-bridge/api \
-H "Authorization: Bearer $WEBCON_MCP_CHAT_BRIDGE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "document.import",
"backendUserId": 5,
"workspaceId": 1,
"afterPageUid": 505,
"title": "News",
"strict": true,
"content": "News headline\n\nExact paragraph from the uploaded document."
}'
```

List pending records:

Request approval:

```bash
curl -s https://example.test/webcon-mcp-chat-bridge/api \
-H "Authorization: Bearer $WEBCON_MCP_CHAT_BRIDGE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "workspace.review.request",
"workspaceId": 1,
"backendUserId": 5,
"comment": "Ready for chief editor approval",
"records": [
{"table": "pages", "workspaceUid": 123},
{"table": "tt_content", "workspaceUid": 456}
]
}'
```

Approve and publish:

```bash
curl -s https://example.test/webcon-mcp-chat-bridge/api \
-H "Authorization: Bearer $WEBCON_MCP_CHAT_BRIDGE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "workspace.review.approve",
"workspaceId": 1,
"backendUserId": 7,
"comment": "Approved in Slack",
"records": [
{"table": "pages", "workspaceUid": 123}
]
}'
```

Production approval actions should resolve the actor through a connected
chat identity. In development context, unsigned requests can use the
configured development backend user.

## Slack slash command examples

Point a Slack command such as `/typo3-lab` to:

```text
https://example.test/webcon-mcp-chat-bridge/slack
```

The endpoint verifies Slack's request signature with
`WEBCON_MCP_CHAT_BRIDGE_SLACK_SIGNING_SECRET`.

Supported command examples:

```text
help
ping
tools
pending workspace=1 page=42
review workspace=1 table=pages
call WorkspaceReview {"limit":10}
request pages:123 Ready for chief editor approval
approve pages:123
```

## Slack chatbot examples

Generate a Slack App Manifest instead of configuring Slack screens manually:

```bash
ddev exec vendor/bin/typo3 mcp-chat-bridge:slack:manifest \
--base-url=https://example.trycloudflare.com \
--slash-command=/typo3-lab
```

In Slack, create the app from the generated manifest. Then copy the Slack
`Signing Secret` and `Bot User OAuth Token` into the TYPO3 environment.

Check setup:

```bash
ddev exec vendor/bin/typo3 mcp-chat-bridge:slack:doctor \
--base-url=https://example.trycloudflare.com
```

In Slack:

```text
@typo3-lab ping
```

With a PDF or text file attached:

```text
@typo3-lab create news in page 123
```

Free-form AI chatbot mode is available when `netresearch/nr-mcp-agent` is
installed and configured:

```text
@typo3-lab summarize page 123
@typo3-lab what content is on page 42?
@typo3-lab create a draft news from this PDF on page 123
```

The Slack adapter keeps one `nr_mcp_agent` conversation per Slack thread and
TYPO3 backend user. Replies in the same Slack thread can refer to earlier
messages, uploaded files, and previous assistant answers. Each request also
gets a Slack/TYPO3 context wrapper with channel, thread, backend user, and
workspace hints. This uses the existing TYPO3 AI Chat configuration; it does
not require Flue.

After installing or updating the bridge, run `vendor/bin/typo3 extension:setup`
so TYPO3 creates the Slack thread mapping table.

PDF extraction requires `pdftotext` in the TYPO3 web runtime, for example via
`poppler-utils` in DDEV.

## Documentation

See `Documentation/Index.rst` for the TYPO3 documentation entry point.

## Repository mirror

Canonical repository: (composer source).
Internal mirror: — push to both remotes (`composer`, `gitlab`) when releasing.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/dirnbauer/webcon-mcp-chat-bridge

Awesome Lists containing this project

README