shopware-env

Imported from shopwareLabs/ai-coding-tools (plugins/shopware-env/AGENTS.md). Install upstream with npx skills add shopwareLabs/ai-coding-tools --skill shopware-env. Copyright stays with the author.

@README.md

Component Overview

This plugin provides:

• One MCP Server via .mcp.json:
  • lifecycle-tooling — 8 tools for dependencies, database, frontend builds, and plugin management
• SessionStart Hook via hooks/hooks.json:
  • Injects lifecycle tool directives into conversation context at session start
  • Prompt maintained in hooks/prompts/mcp-tool-directives.md
  • Outputs JSON additionalContext format
• PreToolUse Hook via hooks/hooks.json:
  • Blocks bash commands that should use lifecycle MCP tools instead
  • Blocks: composer install/update, npm install/ci, bin/console system:install, bin/console plugin:create, bin/console plugin:install/refresh/activate, bin/console bundle:dump, bin/console assets:install, bin/console feature:dump, bin/console framework:schema:dump, bin/console theme:compile
  • Configurable via enforce_mcp_tools: false in .mcp-php-tooling.json
• One Skill (dev-environment-bootstrapping):
  • Orchestrates the full first-run setup: detects state, proposes a plan, confirms with the user, executes lifecycle tools
  • Activates automatically when the user asks to bootstrap, set up, or initialize a Shopware environment

Directory & File Structure

plugins/shopware-env/
├── README.md                                      # User documentation
├── AGENTS.md                                      # LLM navigation guide (this file)
├── CLAUDE.md                                      # Points to AGENTS.md
├── CHANGELOG.md                                   # Version history
├── LICENSE                                        # MIT license
├── .mcp.json                                      # MCP server registration (lifecycle-tooling)
│
├── hooks/                                         # HOOKS (MCP tool enforcement)
│   ├── hooks.json                                 # Hook configuration (SessionStart + PreToolUse)
│   ├── prompts/
│   │   └── mcp-tool-directives.md                 # SessionStart prompt: lifecycle tool listing and usage rules
│   └── scripts/
│       ├── session-start.sh                       # SessionStart hook: reads prompt file, checks enforcement, outputs JSON
│       ├── check-lifecycle-tools.sh               # Blocks composer, npm, bin/console lifecycle commands
│       └── lib/
│           └── common.sh                          # Shared: parse_hook_input(), load_mcp_config(), block_tool()
│
├── shared/                                        # SHARED FRAMEWORK (byte-identical to dev-tooling templates)
│   ├── mcpserver_core.sh                          # JSON-RPC 2.0 protocol handler
│   ├── config.sh                                  # Config discovery & merging (CONFIG_PREFIX parameterized)
│   ├── environment.sh                             # Environment detection, command wrapping, noise filtering
│   └── docker-compose.sh                          # Docker Compose environment: call-time container/workdir resolution
│
├── mcp-server-lifecycle/                          # LIFECYCLE TOOLS MCP SERVER
│   ├── server.sh                                  # Entry point — sets CONFIG_PREFIX="php-tooling"
│   ├── config.json                                # Server metadata (name="lifecycle-tooling")
│   ├── tools.json                                 # All 8 tool schemas
│   └── lib/
│       ├── resolve_env.sh                         # resolve_lifecycle_env(): config-wins env resolution
│       ├── dependencies.sh                        # tool_install_dependencies()
│       ├── database.sh                            # tool_database_install(), tool_database_reset()
│       ├── testdb.sh                              # tool_testdb_prepare()
│       ├── frontend.sh                            # tool_frontend_build_admin(), tool_frontend_build_storefront()
│       └── plugin.sh                              # tool_plugin_create(), tool_plugin_setup()
│
└── skills/
    └── dev-environment-bootstrapping/
        └── SKILL.md                               # 5-phase bootstrapping orchestration skill

Architecture

Config Strategy

The lifecycle-tooling server uses CONFIG_PREFIX="php-tooling", which means it reads the same .mcp-php-tooling.json config that dev-tooling's PHP server reads. This is intentional: users who already have dev-tooling configured get automatic environment resolution in lifecycle tools without any additional setup.

Resolution priority (highest to lowest):

1. .mcp-php-tooling.json (any config search location) — environment, docker_service, compose_file read from config
2. Tool call arguments — explicit environment, docker_service, compose_file passed by caller
3. Default — native environment, project root as workdir

When a config file is present, tool call arguments for environment settings are silently ignored. The skill handles this by detecting the config file and omitting env args from MCP calls when found.

Environment Resolution Pattern (resolve_lifecycle_env)

Each tool lib file calls resolve_lifecycle_env from lib/resolve_env.sh before building its command. This function:

1. Calls load_config (from shared config.sh) to read and merge all config files found in the discovery search path
2. If config has environment set, exports ENVIRONMENT, DOCKER_SERVICE, COMPOSE_FILE from config
3. If no config environment, falls back to function arguments
4. Sets WORKDIR to the config cwd if present, or the process cwd

The result: tools never see "config wins but arg was passed" conflicts — the resolution is centralised and consistent.

Tool Dispatch Convention

Tools in tools.json map to bash functions with tool_ prefix, sourced from lib/*.sh:

# In server.sh
source "${SERVER_DIR}/lib/dependencies.sh"
source "${SERVER_DIR}/lib/database.sh"
# ...

# Dispatch via mcpserver_core.sh
# tools.json "name": "install_dependencies" → tool_install_dependencies()

mcpserver_core.sh (shared) routes JSON-RPC tools/call requests to functions named tool_<tool_name>, where underscores in the tool name map directly to underscores in the function name.

Hook Flow

SessionStart:
  session-start.sh
    → reads hooks/prompts/mcp-tool-directives.md
    → checks enforce_mcp_tools in .mcp-php-tooling.json
    → outputs JSON additionalContext with directive text (or empty if enforcement disabled)

PreToolUse (Bash matcher):
  check-lifecycle-tools.sh
    → parse_hook_input() (from lib/common.sh)
    → load_mcp_config("php-tooling") — reads enforce_mcp_tools flag
    → pattern-matches COMMAND against blocked bash patterns
    → block_tool() outputs JSON decision + message (exit 2) or exit 0

Both hooks share lib/common.sh which provides parse_hook_input(), load_mcp_config(), and block_tool().

Shared Templates Boundary

shared/ contains four files. Three of them — config.sh, environment.sh, and docker-compose.sh — are byte-identical to templates in the repository's templates/mcp-shared/ directory. A sync rule at .claude/rules/template-sync.md declares these three files as template derivatives. Edits to shared framework behavior must be applied to the templates and then synced to all consumers (dev-tooling and shopware-env). Never edit these three files directly for behavior changes; edit the template and sync. The fourth, shared/mcpserver_core.sh, is not a template derivative — it is vendored from shopwareLabs/bash-mcp-sdk at the release pinned in .mcp-sdk.lock; changes to it go upstream.

The hooks lib/common.sh is derived from templates/hooks-shared/common.sh. Same sync rule applies.

Tool Reference

All tools accept environment, docker_service, and compose_file arguments that are overridden by .mcp-php-tooling.json when present.

Testing

BATS tests are in plugin-tests/shopware-env/:

Run tests:

.bats/bats-core/bin/bats plugin-tests/shopware-env/*.bats

Key Navigation Points

Relationship to dev-tooling

shopware-env and dev-tooling are independent plugins installed separately. They share:

• The same config file (.mcp-php-tooling.json) — shopware-env reads it for environment resolution, dev-tooling reads it for tool configuration
• The same shared framework files (shared/*.sh) — config.sh, docker-compose.sh, and environment.sh are byte-identical copies derived from the same templates; mcpserver_core.sh is vendored from shopwareLabs/bash-mcp-sdk at the release pinned in .mcp-sdk.lock

They do not share MCP server processes or runtime state. Installing one does not require the other, though the bootstrapping skill's Phase 5 handoff message directs users to install dev-tooling after environment setup is complete.

See README for the user-facing integration description.

External References

• bash-mcp-sdk — the server's protocol handler is vendored from here
• MCP Protocol Specification — JSON-RPC 2.0 protocol details