SuluMcpBundle - GitLite

KO | EN

gitlite — search

#deep-learning #awesome #gemini #ruby #windows #tensorflow #chatbot #json #bash #react-native

SuluMcpBundle

(★ 9)

No description available.

File Explorer

ZIP Download

- - require-product-bundle.sh
- - test-application-product.yaml
  - test-application.yaml
- PULL_REQUEST_TEMPLATE.md
- routing_admin.yaml
- routing_website.yaml
- services.php
- services_product.php
- - chatgpt.md
  - claude-ai.md
  - claude-code.md
  - claude-cowork.md
  - codex.md
- configuration.md
- CONTENT_ASSISTANT_PROMPT.md
- PRODUCT_ASSISTANT_PROMPT.md
- README.md
- - .env
  - Kernel.php
  - PreviewKernel.php
  - PreviewKernelFactory.php
- - docker-compose.mysql-84.yml
- - ArticleGroupScopingTest.php
  - ContentLocaleCreationTest.php
  - ContentRepublishTest.php
  - FunctionalTestCase.php
  - McpFirewallMapTest.php
  - McpScopeEnforcementTest.php
  - MediaCollectionAclTest.php
  - OAuthRoutingTest.php
  - PageDescendantAclTest.php
  - PageMoveTest.php
  - PermissionAclSmokeTest.php
  - PermissionFixtureBuilder.php
  - PermissionHandlerSmokeTest.php
  - ProductPermissionScopingTest.php
  - ProductVariantLifecycleTest.php
  - RequestHandlerWiringTest.php
  - RequestListenerOrderTest.php
  - SectionMetadataResourceTest.php
  - SecurityBoundaryTest.php
  - ToolDiscoverySmokeTest.php
  - ToolPermissionMapCompletenessTest.php
  - ToolTitleCompletenessTest.php
  - WebspaceScopingTest.php
  - WellKnownWebsiteContextTest.php
- test-bootstrap.php
- sulu_mcp.de.yaml
- sulu_mcp.en.yaml
.gitattributes
.gitignore
.php-cs-fixer.dist.php
composer.json
CONTRIBUTING.md
LICENSE
phpstan.neon
phpunit.xml.dist
README.md
rector.php
SECURITY.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">SuluMcpBundle</h1>

<p align="center">
    <a href="https://sulu.io/" target="_blank">
        <img width="30%" src="https://sulu.io/uploads/media/800x/00/230-Official%20Bundle%20Seal.svg?v=2-6&inline=1" alt="Official Sulu Bundle Badge">
    </a>
</p>

<p align="center">
    <a href="LICENSE" target="_blank">
        <img src="https://img.shields.io/github/license/sulu/SuluMcpBundle.svg" alt="GitHub license">
    </a>
    <a href="https://github.com/sulu/SuluMcpBundle/releases" target="_blank">
        <img src="https://img.shields.io/github/tag/sulu/SuluMcpBundle.svg" alt="GitHub tag (latest SemVer)">
    </a>
    <a href="https://github.com/sulu/SuluMcpBundle/actions" target="_blank">
        <img src="https://img.shields.io/github/actions/workflow/status/sulu/SuluMcpBundle/test-application.yaml" alt="Test workflow status">
    </a>
    <a href="https://github.com/sulu/sulu/releases" target="_blank">
        <img src="https://img.shields.io/badge/sulu%20compatibility-%3E=3.0-52b6ca.svg" alt="Sulu compatibility">
    </a>
</p>
<br/>

The **SuluMcpBundle** turns a [Sulu](https://sulu.io/) installation into a
[Model Context Protocol](https://modelcontextprotocol.io) server. AI assistants connect over Streamable HTTP and
**create pages, edit articles, manage media and publish content** through the same operations the administration
interface uses. Every request runs as the **authenticated Sulu user**, so an operation that is denied in the
administration interface is denied over MCP as well. There is no separate authentication layer and no privilege
escalation.

## 🚀&nbsp; Installation and Documentation

```bash
composer config extra.symfony.allow-contrib true
composer require sulu/mcp-bundle
```

The first command enables the [contrib recipes](https://github.com/symfony/recipes-contrib), where this bundle's
[Flex recipe](https://github.com/symfony/recipes-contrib/tree/main/sulu/mcp-bundle) lives. The recipe registers the
bundles, writes the routes and the configuration, including the allowed hosts of the transport and the default OAuth
scopes, and adds `SULU_MCP_SERVER_URL` to `.env`. The OAuth key pair, the `league/oauth2-server-bundle` grants, the
migration and the security setup have no Flex configurator and stay manual.

The steps below spell out everything, both for installations without Flex and for reading back what the recipe put
into your project. Start by registering the bundle in `config/bundles.php`, along with its two required
dependencies. `league/oauth2-server-bundle` registers itself through its own recipe, while `symfony/mcp-bundle` has
none and is registered by ours:

```php
return [
    // ...
    Symfony\AI\McpBundle\McpBundle::class => ['all' => true],
    League\Bundle\OAuth2ServerBundle\LeagueOAuth2ServerBundle::class => ['all' => true],
    Sulu\Mcp\Infrastructure\Symfony\HttpKernel\SuluMcpBundle::class => ['all' => true],
];
```

Import the routes in `config/routes.yaml`. The `mcp` entry registers the MCP transport endpoint provided by
`symfony/mcp-bundle`. This bundle ships its OAuth endpoints in two files: the admin ones take the same prefix your
project already uses for the rest of the Sulu admin, and the RFC 8414/9728 discovery documents stay unprefixed in the
host's `/.well-known/` namespace:

```yaml
mcp:
    resource: .
    type: mcp

sulu_mcp_admin:
    resource: '@SuluMcpBundle/config/routing_admin.yaml'
    prefix: /admin

sulu_mcp_website:
    resource: '@SuluMcpBundle/config/routing_website.yaml'
```

Generate the RSA key pair that `league/oauth2-server-bundle` signs its tokens with. Skipping this step leaves every
MCP request failing with `Invalid key supplied`:

```bash
mkdir -p config/jwt
openssl genrsa -aes128 -out config/jwt/private.pem 4096
openssl rsa -in config/jwt/private.pem -pubout -out config/jwt/public.pem
```

Both commands prompt for the passphrase, so it stays out of your shell history.

Keep both keys out of version control, for example by adding `/config/jwt/*.pem` to your `.gitignore`.

Set the public server URL and the OAuth secrets in your environment. The passphrase has to match the one used above,
and the encryption key is any random string:

```bash
SULU_MCP_SERVER_URL=https://your-sulu-host.example.com
OAUTH_PRIVATE_KEY=%kernel.project_dir%/config/jwt/private.pem
OAUTH_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
OAUTH_PASSPHRASE=<passphrase>
OAUTH_ENCRYPTION_KEY=<random-string>
```

Configure `league/oauth2-server-bundle` in `config/packages/league_oauth2_server.yaml`. Its Flex recipe generates most
of the file; make sure the authorization-code and refresh-token grants MCP uses are enabled and the password and
implicit grants are explicitly off. `scopes.default` is required by league and comes from this bundle's recipe, which
appends the MCP scopes to the ones the league recipe wrote; set it yourself when you install without Flex:

```yaml
league_oauth2_server:
    authorization_server:
        private_key: '%env(resolve:OAUTH_PRIVATE_KEY)%'
        private_key_passphrase: '%env(OAUTH_PASSPHRASE)%'
        encryption_key: '%env(OAUTH_ENCRYPTION_KEY)%'
        enable_auth_code_grant: true
        enable_refresh_token_grant: true
        enable_password_grant: false
        enable_implicit_grant: false

resource_server:
        public_key: '%env(resolve:OAUTH_PUBLIC_KEY)%'

scopes:
        default: ['mcp:tools', 'mcp:resources']

persistence:
        doctrine: ~
```

Name the public host on the MCP transport. The transport ships with DNS rebinding protection that accepts only
localhost, so a server on its own domain rejects every client with `Forbidden: Invalid Host header.` once the OAuth
handshake is through. This bundle's recipe writes the setting into `config/packages/sulu_mcp.yaml`; without Flex, put
it in `config/packages/mcp.yaml` yourself:

```yaml
mcp:
    http:
        allowed_hosts:
            - '%env(key:host:url:SULU_MCP_SERVER_URL)%'
            - localhost
            - 127.0.0.1
            - '[::1]'
```

Create the database tables. `league/oauth2-server-bundle` persists clients, authorization codes, access tokens and
refresh tokens through Doctrine:

```bash
bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate
```

The MCP endpoint then answers at `/admin/mcp`. The [`docs/`](docs/) directory documents the
[configuration reference](docs/configuration.md), the **required security setup**, and per-client connection guides for
[Claude.ai](docs/clients/claude-ai.md), [Claude Code](docs/clients/claude-code.md),
[Claude Cowork](docs/clients/claude-cowork.md), [ChatGPT](docs/clients/chatgpt.md) and [Codex](docs/clients/codex.md).

## 💡&nbsp; Key Concepts

### Permissions

The bundle adds no permission model of its own. Every tool declares the Sulu security context and permission type it
requires, a compile-time map is built from those declarations, and a central gate checks it before any tool runs.
Tools the current role cannot use are hidden from the tool listing, and calling one anyway returns a permission denial
rather than a missing-tool error.

### Dangerous tools

Tools with hard-to-reverse effects are **disabled by default** and enabled per category through the `dangerous_tools`
configuration. When a category is disabled its tools are removed from the container at compile time, so they never
appear to a client at all.

```yaml
# config/packages/sulu_mcp.yaml
sulu_mcp:
    server_url: '%env(SULU_MCP_SERVER_URL)%'
    dangerous_tools:
        delete: false        # sulu_content_delete, sulu_tag_delete, sulu_category_delete
        publish: false       # sulu_content_publish, sulu_content_unpublish, sulu_preview_link_revoke, sulu_page_move, sulu_page_reorder
        block_remove: false  # sulu_block_remove
        media_upload: false  # sulu_media_upload
```

### Available tools

40 tools spanning the core Sulu domains, plus 9 more when `sulu/product-bundle` is installed:

| Domain | Count | Examples |
|--------|-------|----------|
| Pages | 7 | `sulu_page_create`, `sulu_page_get`, `sulu_page_list`, `sulu_page_move`, `sulu_page_reorder`, `sulu_page_tree`, `sulu_page_update` |
| Blocks | 5 | `sulu_block_add`, `sulu_block_update`, `sulu_block_reorder`, `sulu_block_list`, `sulu_block_remove` |
| Articles | 4 | `sulu_article_create`, `sulu_article_update`, `sulu_article_get`, `sulu_article_list` |
| Snippets | 4 | `sulu_snippet_create`, `sulu_snippet_update`, `sulu_snippet_get`, `sulu_snippet_list` |
| Unified content | 3 | `sulu_content_delete`, `sulu_content_publish`, `sulu_content_unpublish` |
| Media | 4 | `sulu_media_list`, `sulu_media_get`, `sulu_media_update`, `sulu_media_upload` |
| Taxonomy | 6 | `sulu_tag_*`, `sulu_category_*` |
| Preview | 2 | `sulu_preview_link_generate`, `sulu_preview_link_revoke` |
| Navigation | 1 | `sulu_navigation_get` |
| Contact | 1 | `sulu_contact_list` |
| Products *(optional)* | 9 | `sulu_product_create`, `sulu_product_update`, `sulu_product_get`, `sulu_product_list`, `sulu_product_variant_*`, `sulu_product_family_list`, `sulu_attribute_list` — require [`sulu/product-bundle`](https://github.com/sulu/SuluProductBundle) |
| Misc | 3 | `sulu_content_search`, `sulu_get_context`, `sulu_ping` |

The block and unified content tools operate on pages, articles, snippets — and products, when
`sulu/product-bundle` is installed — alike through a `type` parameter.

#### Products (optional)

The product tools appear only when [`sulu/product-bundle`](https://github.com/sulu/SuluProductBundle)
is installed and registered in `bundles.php`; without it they are hidden from `tools/list`. The
bundle has no 3.x release yet, so it installs from its branch:

```bash
composer require sulu/product-bundle:3.0.x-dev
```

Products are modelled with a product family that decides which attributes apply, and support one
level of variants: a product of type `product_with_variants` holds `variant` children. Variants
cannot be nested. Because a variant inherits its parent's family and only carries the attributes
the family marks `variantSpecific`, they are created with `sulu_product_variant_create` rather than
`sulu_product_create`. Publishing the parent through `sulu_content_publish` cascades to all of its
variants.

### Authentication

Clients authenticate through OAuth 2.1 with Dynamic Client Registration, backed by `league/oauth2-server-bundle`.
Sulu opens the administration login when needed and then shows an explicit consent screen naming the client and the
requested scopes. Tokens are only issued once the user approves that screen.

For hosted clients, create an OAuth client up front:

```bash
bin/console sulu:mcp:create-client "Claude.ai Production"
```

## ❤️&nbsp; Support and Contributions

The Sulu content management system is a **community-driven open source project** backed by various partner companies.
We are committed to a fully transparent development process and **highly appreciate any contributions**.

Have a look at our [contribution guidelines](CONTRIBUTING.md) and the
[Sulu contribution documentation](https://docs.sulu.io/en/3.x/developer/contributing/index.html) before opening a pull
request. Security issues should be reported privately as described in [SECURITY.md](SECURITY.md).

## ✅&nbsp; Requirements

* PHP 8.2 or higher
* Symfony 7.3 or 8.x
* Sulu 3.0 or higher

Have a look at the `require` section in the [composer.json](composer.json) for an up-to-date list.

## 📘&nbsp; License

The Sulu content management system is released under the terms of the [MIT License](LICENSE).