Merge pull request #308 from wunderio/feature/WNDR-385

WNDR-385: Lando cleanup and add ddev-agents

Author: vermario

.agents/README.md

@@ -0,0 +1,191 @@
+# Local Development MCP
+
+An MCP server that gives AI agents tools to run commands in DDEV containers via SSH. Tools are defined in YAML configuration files.
+
+## Architecture
+
+- **Execution Method**: SSH (passwordless key-based authentication)
+- **SSH Keys**: Ephemeral Ed25519 keys, generated fresh each `ddev start` and distributed via `docker exec`
+- **SSH User**: Automatically detected from web container's `/var/www/html` ownership, configured via SSH client `User` directive
+- **No Docker Socket**: Fully isolated from host Docker daemon
+- **No Persistent State**: No `.runtime.env` or stored keys — everything is set up by the `set-up` hook
+
+## How to Use
+
+1. **Installation:**
+   ```bash
+   cd /path/to/ddev-project
+   ddev get wunderio/ddev-agents
+   ddev restart  # Builds container and sets up SSH automatically
+   ```
+
+2. **First Launch:**
+   - Open VS Code in the devcontainer
+   - The wdrmcp MCP server config is at `.vscode/mcp.json`
+   - Note: Due to VS Code bug, search `@mcp` in extension gallery to enable the MCP registry
+   - Open Command Palette: `MCP Servers: List`, find wdrmcp and click Start
+
+3. **Using Tools:**
+   - Open VS Code Copilot chat
+   - Use tools like `drush`, `composer_install`, `logs_nginx_access`, etc.
+   - All tools connect via SSH automatically
+
+## How SSH Works
+
+SSH keys are **ephemeral** — generated fresh on every `ddev start`:
+
+1. The `set-up` hook (runs post-start on host) generates an Ed25519 keypair
+2. Public key is placed in the web container via `docker exec`
+3. Private key + SSH client config are placed in the agents container via `docker exec`
+4. The SSH client config includes a `User` directive with the detected DDEV user
+5. Keys exist only in container memory — never written to disk on the host
+
+Tool configs use `ssh_target: "web"` — the SSH client config handles which user to connect as.
+
+## Files
+
+- `tools-config/` – YAML tool definitions
+- `mcp.json` – MCP server configuration (copied to `.vscode/mcp.json` by set-up hook)
+
+## Adding a Tool
+
+Create a file in `tools-config/my_tool.yml`:
+
+```yaml
+tools:
+  - name: my_tool
+    type: command
+    enabled: true
+    description: "What this tool does"
+    command_template: "my_command {command} {args}"
+    ssh_target: "web"
+    working_dir: "/var/www/html"
+    default_args:
+      args: []
+    input_schema:
+      type: object
+      properties:
+        command:
+          type: string
+          description: "Command to run"
+        args:
+          type: array
+          items:
+            type: string
+          description: "Flags and options, each as a separate array element"
+      required:
+        - command
+```
+
+### Parameter types
+
+- **`string`** — for single values (commands, package names, file paths).
+- **`array`** with `items: { type: string }` — for flags/options. Each element is individually shell-escaped, so multi-flag use is safe: `["--format=json", "--fields=name,status"]`.
+- **`integer`** — for numeric values (line counts, limits).
+
+String parameters are shell-escaped as a single token. Array parameters have each element escaped individually and joined with spaces. Empty strings and empty arrays produce no output in the rendered command.
+
+## Project `.env` Credentials
+
+If any MCP tool config needs credentials (e.g., Drupal MCP proxy), define them in `.env` inside the `tools-config` directory.
+
+Example credentials file (`.agents/tools-config/.env`):
+
+```dotenv
+DRUPAL_MCP_USER=admin
+DRUPAL_MCP_PASS=admin
+```
+
+This file is preserved across addon reinstalls (non-destructive merge).
+
+## Available Tool Types
+
+- `command` – Run shell commands with parameter substitution
+- `mcp_server` – Proxy to additional MCP servers
+
+### Command Tool Type
+
+Command tools execute shell commands in DDEV containers with parameter substitution.
+
+Example:
+
+```yaml
+tools:
+  - name: my_command_tool
+    type: command
+    enabled: true
+    description: "Execute a custom command"
+    command_template: "my_command {name} {args}"
+    ssh_target: "web"
+    working_dir: "/var/www/html"
+    default_args:
+      args: []
+
+    input_schema:
+      type: object
+      properties:
+        name:
+          type: string
+          description: "Name argument"
+        args:
+          type: array
+          items:
+            type: string
+          description: "Flags and options as separate array elements"
+      required:
+        - name
+```
+
+### MCP Server Tool Type
+
+MCP Server tools proxy requests to other MCP servers via HTTP. Both plain JSON-RPC HTTP endpoints and Streamable HTTP MCP endpoints are supported.
+
+For Streamable HTTP MCP endpoints, the proxy uses the MCP SDK Client which handles the protocol handshake, session management, and reconnection automatically. If the remote server does not support the MCP protocol, the proxy falls back to plain JSON-RPC.
+
+**Dynamic Tool Discovery:** When `expose_remote_tools: true` is set, the proxy will query the remote MCP server for all its available tools and expose them as if they were local tools. This allows seamless integration with external MCP servers.
+
+Example (single proxy tool):
+
+```yaml
+tools:
+  - name: my_mcp_tool
+    type: mcp_server
+    enabled: true
+    description: "Proxy to another MCP server"
+    server_url: "http://localhost:8080/endpoint"
+    forward_args: true       # Optional: forward arguments (default: true)
+    timeout: 30              # Optional: timeout in seconds (default: 30)
+    auth_username: "${MCP_USER}"     # Optional: basic auth username
+    auth_password: "${MCP_PASS}"     # Optional: basic auth password
+    input_schema:
+      type: object
+      properties:
+        query:
+          type: string
+      required:
+        - query
+```
+
+Example (dynamic tool exposure):
+
+```yaml
+tools:
+  - name: drupal_mcp
+    type: mcp_server
+    enabled: true
+    description: "Proxy to Drupal MCP server"
+    server_url: "https://drupal-project.ddev.site/mcp/post"
+    auth_username: "${DRUPAL_MCP_USER}"
+    auth_password: "${DRUPAL_MCP_PASS}"
+    expose_remote_tools: true    # Dynamically fetch and expose remote tools
+    tool_prefix: "drupal_"       # Optional: prefix remote tool names
+    timeout: 30
+```
+
+## Logging
+
+View MCP server logs:
+
+```bash
+tail -f /tmp/wdrmcp.log
+```

.agents/tools-config/composer.yml

@@ -0,0 +1,127 @@
+# Composer PHP Dependency Manager Configuration
+# Defines available composer commands
+
+tools:
+  - name: composer_install
+    enabled: true
+    description: |
+      Install dependencies from composer.lock file.
+
+      Always run in the Drupal project directory (/var/www/html).
+      Installs packages with versions locked in composer.lock.
+
+    type: command
+    command_template: "composer install {args}"
+    ssh_target: "web"
+    ssh_user: "${DDEV_SSH_USER}"
+    working_dir: "/var/www/html"
+    default_args:
+      args: ["--no-interaction"]
+
+    input_schema:
+      type: object
+      properties:
+        args:
+          type: array
+          items:
+            type: string
+          description: >
+            Each flag or option as a separate array element.
+            The default ["--no-interaction"] is always included unless overridden.
+            Examples: ["--no-dev"], ["--no-dev", "--optimize-autoloader"].
+
+  - name: composer_update
+    enabled: true
+    description: |
+      Update dependencies to latest versions.
+
+      Always run in the Drupal project directory (/var/www/html).
+      Updates packages according to version constraints in composer.json.
+
+    type: command
+    command_template: "composer update {package} {args}"
+    ssh_target: "web"
+    ssh_user: "${DDEV_SSH_USER}"
+    working_dir: "/var/www/html"
+    default_args:
+      package: ""
+      args: ["--no-interaction"]
+
+    input_schema:
+      type: object
+      properties:
+        package:
+          type: string
+          description: >
+            Package name to update (e.g., "drupal/pathauto").
+            Omit or leave empty to update all packages.
+        args:
+          type: array
+          items:
+            type: string
+          description: >
+            Each flag or option as a separate array element.
+            Examples: ["--with-dependencies"], ["--no-dev", "--prefer-dist"].
+
+  - name: composer_require
+    enabled: true
+    description: |
+      Add one or more dependencies to composer.json.
+
+      Always run in the Drupal project directory (/var/www/html).
+      Adds packages and updates composer.lock.
+
+      Supports multiple packages in a single call — prefer this over separate
+      calls when installing related packages together:
+        {"packages": ["drupal/pathauto", "drupal/token:^1.0"]}
+        {"packages": ["drupal/mcp_server", "drupal/tool"], "args": ["--ignore-platform-req=ext-gd"]}
+
+      Single package still works:
+        {"packages": ["drupal/pathauto"]}
+
+      Troubleshooting installation failures:
+
+      1. **PHP Version Incompatibility** - Package may require different PHP version
+         - Check PHP version: Use drush_php_eval "echo PHP_VERSION;"
+         - Check composer.json: Look for "platform" sections with PHP constraints
+         - Try: args: ["--ignore-platform-req=php-ext-*"]
+
+      2. **Stability Constraints** - Package below minimum-stability threshold
+         - Try: packages: ["drupal/package:@dev"] (or @beta, @alpha)
+         - Or update composer.json "minimum-stability" to "dev"
+
+      3. **Memory Errors** - Large installation can exceed PHP memory limit
+         - Try: Use COMPOSER_MEMORY_LIMIT=-1 environment variable
+
+      4. **Dependency Conflicts** - New package conflicts with existing ones
+         - Try: args: ["--with-all-dependencies"]
+         - This updates related packages to compatible versions
+
+    type: command
+    command_template: "composer require {packages} {args}"
+    ssh_target: "web"
+    ssh_user: "${DDEV_SSH_USER}"
+    working_dir: "/var/www/html"
+    default_args:
+      args: ["--no-interaction"]
+
+    input_schema:
+      type: object
+      properties:
+        packages:
+          type: array
+          items:
+            type: string
+          description: >
+            One or more package names to require.
+            Examples: ["drupal/pathauto"], ["drupal/mcp_server", "drupal/tool:^1.0"].
+            Each element is shell-escaped and joined with spaces in the command.
+        args:
+          type: array
+          items:
+            type: string
+          description: >
+            Each flag or option as a separate array element.
+            Examples: ["--with-all-dependencies"], ["--no-dev", "--prefer-dist"].
+      required:
+        - packages

.agents/tools-config/drupal.yml

@@ -0,0 +1,74 @@
+# Drupal MCP Server Proxy Configuration
+# Proxies to a Drupal-specific MCP server
+#
+# == SETUP INSTRUCTIONS (run once per project) ==
+#
+# 1. Install and enable the module:
+#      composer_require: drupal/mcp
+#      drush pm:enable mcp -y
+#      drush_cr
+#
+# 2. Enable basic auth:
+#      drush config:set mcp.settings enable_auth true -y
+#      drush config:set mcp.settings auth_settings.enable_basic_auth true -y
+#
+# 3. Verify — expect a JSON-RPC response containing "protocolVersion":
+#      drush_php_eval:
+#        $req = \Symfony\Component\HttpFoundation\Request::create('/mcp/post','POST',[],[],[],
+#          ['HTTP_AUTHORIZATION'=>'Basic '.base64_encode('admin:admin'),'CONTENT_TYPE'=>'application/json'],
+#          json_encode(['jsonrpc'=>'2.0','method'=>'initialize','params'=>['protocolVersion'=>'2024-11-05','capabilities'=>[],'clientInfo'=>['name'=>'test','version'=>'1.0']],'id'=>1]));
+#        echo \Drupal::classResolver(\Drupal\mcp\Controller\McpController::class)->post($req)->getContent();
+#
+# 4. Ask the user for the Drupal admin username and password, then create
+#    .agents/tools-config/.env:
+#      DRUPAL_MCP_USER=<username>
+#      DRUPAL_MCP_PASS=<password>
+#
+# NOTE: Use http://web/mcp/post (internal container URL — bypasses Varnish).
+#       The tool config below already references this URL and the env vars above.
+
+tools:
+  - name: drupal
+    enabled: true
+    type: mcp_server
+    description: |
+      Drupal MCP server proxy for accessing tools provided by the Drupal site.
+
+      This proxies requests to the Drupal site's /mcp/post endpoint to discover
+      and call available tools. Discovered tools are prefixed with "drupal_"
+      (e.g., drupal_general_info).
+
+      Usage:
+      - Use discovered tools directly (e.g., drupal_general_info, drupal_entity_info)
+      - Each discovered tool is automatically prefixed
+
+    # Drupal MCP server endpoint - uses internal DDEV network address
+    server_url: "http://web/mcp/post"
+
+    # Basic authentication (if required by Drupal module)
+    auth_username: "${DRUPAL_MCP_USER}"
+    auth_password: "${DRUPAL_MCP_PASS}"
+
+    # Dynamically expose all tools from the remote MCP server
+    # Tools are automatically prefixed with the tool name: drupal_<tool_name>
+    expose_remote_tools: true
+
+    # Initialization timeout for fetching remote tools (seconds)
+    # Drupal MCP server can be slow, so allow enough time during startup
+    init_timeout: 60
+
+    # Request timeout in seconds (for runtime tool execution)
+    timeout: 60
+
+    # Input schema for JSON-RPC method calls
+    input_schema:
+      type: object
+      properties:
+        method:
+          type: string
+          description: "JSON-RPC method name (e.g., 'tools/list', 'tools/call')"
+        params:
+          type: object
+          description: "Method parameters (varies by method)"
+      required:
+        - method