Development to Main

.github/workflows/ci-mcp-server.yml

@@ -0,0 +1,36 @@
+name: MCP Server CI
+
+on:
+  push:
+    paths:
+      - 'tools/mcp-server/**'
+  pull_request:
+    paths:
+      - 'tools/mcp-server/**'
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        working-directory: tools/mcp-server
+        run: npm ci
+
+      - name: Build
+        working-directory: tools/mcp-server
+        run: npm run build
+
+      - name: Test
+        working-directory: tools/mcp-server
+        run: npm test

.gitignore

@@ -5,6 +5,11 @@
 !temp/README.md
 !temp/*/.gitkeep
 !temp/*/*/.gitkeep
+!temp/mcp/
+!temp/mcp/local-snippets/
+!temp/mcp/notes/
+!temp/mcp/local-snippets/.gitkeep
+!temp/mcp/notes/.gitkeep
 
 # Credentials (never commit these)
 *.credentials
@@ -20,7 +25,9 @@ playwright-auth.json
 
 # IDE files
 .DS_Store
-.vscode/
+.vscode/*
+!.vscode/tasks.json
+!.vscode/launch.json
 .idea/
 *.sublime-*
 *.swp
@@ -57,4 +64,13 @@ coverage/
 *.bak
 *.cache
 
-.DS_Store
+# Root-level shell transcript artifacts from script(1)
+/typescript
+/typescript.[0-9]*
+
+/.claude
+/.mcp.local.json
+
+# Machine-specific symlinks (never commit these)
+/npx
+/playwright

.mcp.README.md

@@ -0,0 +1,109 @@
+# .mcp.json — MCP Server Configuration for Claude Code
+
+`.mcp.json` is how Claude Code discovers MCP servers for this project.
+JSON does not support comments, so this companion file documents the config.
+
+## Repo Safety Reminder
+
+Do not commit site-specific LocalWP names, internal hostnames, user IDs, filesystem paths, bearer tokens, cookies, auth-state files, or other confidential environment details into `.mcp.json` or related MCP docs.
+
+Keep the checked-in `.mcp.json` generic and public-safe. If you need a second WordPress MCP Adapter entry for a real site, keep that variant local-only and store working snippets or notes under `temp/` instead of committing them.
+
+Tracked helpers for local use:
+- `.mcp.local.example.json` shows a generic dual-server shape with placeholders.
+- `./bin/mcp-local-config` merges `.mcp.json` with any local-only snippets under `temp/mcp/local-snippets/`.
+- `examples/mcp/local-snippet.example.json` shows the exact snippet shape expected under `temp/mcp/local-snippets/`.
+
+Scaffolded local snippet directories are kept in git with:
+- `temp/mcp/local-snippets/.gitkeep`
+- `temp/mcp/notes/.gitkeep`
+
+## Current: Single-Server (AI-DDTK)
+
+The checked-in `.mcp.json` now defaults to the public-safe AI-DDTK server only. Add a second WordPress MCP Adapter entry locally when you want site-specific abilities without committing a real Local site name into the repo.
+
+## Dual-Server Config: AI-DDTK + WordPress MCP Adapter
+
+To run the WP MCP Adapter alongside AI-DDTK, replace `.mcp.json` with:
+
+```json
+{
+  "mcpServers": {
+    "ai-ddtk": {
+      "command": "bash",
+      "args": ["tools/mcp-server/start.sh"]
+    },
+    "wordpress": {
+      "command": "./bin/local-wp",
+      "args": [
+        "<site-name>",
+        "mcp-adapter", "serve",
+        "--server=mcp-adapter-default-server",
+        "--user=1"
+      ]
+    }
+  }
+}
+```
+
+You can also keep the checked-in `.mcp.json` generic, place one or more real local adapter snippets in `temp/mcp/local-snippets/*.json`, and generate a merged local config with:
+
+```bash
+./bin/mcp-local-config --write .mcp.local.json
+```
+
+`/.mcp.local.json` is gitignored on purpose.
+
+Preview a write target without modifying files:
+
+```bash
+./bin/mcp-local-config --dry-run --write .mcp.local.json
+```
+
+If you intentionally want to overwrite the repo-root `.mcp.json` for local-only work, the helper supports that too but requires an explicit warning acknowledgment:
+
+```bash
+printf 'OVERWRITE\n' | ./bin/mcp-local-config --write-root
+```
+
+### Notes
+
+- Replace `<site-name>` with your Local site (e.g. `love2hugcom-clone`).
+- Use `--user=1` (user ID), not `--user=admin` — admin usernames vary per site.
+- Do not commit the resolved site name, internal domain, or user identifier from your local environment back into the checked-in `.mcp.json`.
+- For Valet sites, use system WP-CLI instead of `./bin/local-wp`:
+  ```json
+  "wordpress": {
+    "command": "wp",
+    "args": [
+      "--path=/Users/<you>/Valet-Sites/<site>",
+      "mcp-adapter", "serve",
+      "--server=mcp-adapter-default-server",
+      "--user=admin"
+    ]
+  }
+  ```
+
+### Tool namespaces (no collisions)
+
+| Server | Tools | Prefix |
+|---|---|---|
+| ai-ddtk | 18 | `local_wp_*`, `pw_auth_*`, `tmux_*`, `wpcc_*`, `wp_ajax_test` |
+| wordpress | 3 | `mcp-adapter-*` (discover, get-info, execute) |
+
+### Custom ability requirements
+
+Abilities must set three things to be visible via MCP Adapter:
+1. Hook: `add_action('wp_abilities_api_init', ...)`
+2. Category: `'category' => 'site'` (or `user`, `mcp-adapter`)
+3. MCP flag: `'meta' => ['mcp' => ['public' => true]]`
+
+See `P1-WP-MCP-ADAPTER.md` Phase 0.2 for the full mu-plugin pattern.
+
+### No-parameter abilities — omit `input_schema`
+
+Abilities that take no parameters must **not** include an `input_schema`. Using `'properties' => new stdClass()` triggers two bugs in `ExecuteAbilityAbility` v0.4.1. See [docs/MCP-ADAPTER-SETUP.md](docs/MCP-ADAPTER-SETUP.md#abilities-with-no-parameters-must-omit-input_schema) for details.
+
+---
+Validated 2026-03-22 on Local and Valet test sites.
+Validated 2026-03-21 on a Local WordPress 6.9.4 site — all 12 Phase 1+2 abilities confirmed.

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "ai-ddtk": {
+      "command": "bash",
+      "args": ["tools/mcp-server/start.sh"]
+    }
+  }
+}

.mcp.local.example.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "ai-ddtk": {
+      "command": "bash",
+      "args": ["tools/mcp-server/start.sh"]
+    },
+    "wordpress-local": {
+      "command": "./bin/local-wp",
+      "args": [
+        "<site-name>",
+        "mcp-adapter",
+        "serve",
+        "--server=mcp-adapter-default-server",
+        "--user=1"
+      ]
+    }
+  }
+}

.vscode/launch.json

@@ -0,0 +1,48 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "MCP Server (stdio)",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/tools/mcp-server/dist/src/index.js",
+      "outFiles": ["${workspaceFolder}/tools/mcp-server/dist/**/*.js"],
+      "sourceMaps": true,
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}/tools/mcp-server",
+      "preLaunchTask": "MCP: Build"
+    },
+    {
+      "name": "MCP Server (HTTP :3100)",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/tools/mcp-server/dist/src/index.js",
+      "args": ["--http"],
+      "outFiles": ["${workspaceFolder}/tools/mcp-server/dist/**/*.js"],
+      "sourceMaps": true,
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}/tools/mcp-server",
+      "preLaunchTask": "MCP: Build"
+    },
+    {
+      "name": "MCP Server Tests",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/tools/mcp-server/dist/test/${input:testFile}",
+      "args": ["--test"],
+      "outFiles": ["${workspaceFolder}/tools/mcp-server/dist/**/*.js"],
+      "sourceMaps": true,
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}/tools/mcp-server",
+      "preLaunchTask": "MCP: Build"
+    }
+  ],
+  "inputs": [
+    {
+      "id": "testFile",
+      "description": "Test file to debug (e.g. local-wp.test.js)",
+      "type": "promptString",
+      "default": "local-wp.test.js"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,87 @@
+{
+  "version": "2.0.0",
+  "inputs": [
+    {
+      "id": "siteUrl",
+      "description": "WordPress site URL (e.g. http://my-site.local)",
+      "type": "promptString"
+    },
+    {
+      "id": "siteName",
+      "description": "Local by Flywheel site name",
+      "type": "promptString"
+    },
+    {
+      "id": "ajaxUrl",
+      "description": "WordPress site URL for AJAX testing",
+      "type": "promptString"
+    },
+    {
+      "id": "ajaxAction",
+      "description": "WordPress AJAX action name",
+      "type": "promptString"
+    },
+    {
+      "id": "scanPaths",
+      "description": "Path(s) to scan with WPCC (relative to workspace)",
+      "type": "promptString",
+      "default": "."
+    }
+  ],
+  "tasks": [
+    {
+      "label": "MCP: Start Server (stdio)",
+      "type": "shell",
+      "command": "npm run mcp",
+      "options": { "cwd": "${workspaceFolder}/tools/mcp-server" },
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "MCP: Start Server (HTTP)",
+      "type": "shell",
+      "command": "npm run mcp:http",
+      "options": { "cwd": "${workspaceFolder}/tools/mcp-server" },
+      "group": "none",
+      "problemMatcher": [],
+      "isBackground": true
+    },
+    {
+      "label": "MCP: Build",
+      "type": "shell",
+      "command": "npm run build",
+      "options": { "cwd": "${workspaceFolder}/tools/mcp-server" },
+      "group": "build",
+      "problemMatcher": ["$tsc"]
+    },
+    {
+      "label": "MCP: Test",
+      "type": "shell",
+      "command": "npm test",
+      "options": { "cwd": "${workspaceFolder}/tools/mcp-server" },
+      "group": "test",
+      "problemMatcher": []
+    },
+    {
+      "label": "WPCC: Run Scan",
+      "type": "shell",
+      "command": "wpcc --paths ${input:scanPaths} --format json",
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "pw-auth: Login",
+      "type": "shell",
+      "command": "pw-auth login --site-url ${input:siteUrl} --wp-cli 'local-wp ${input:siteName}'",
+      "group": "none",
+      "problemMatcher": []
+    },
+    {
+      "label": "AJAX Test",
+      "type": "shell",
+      "command": "wp-ajax-test --url ${input:ajaxUrl} --action ${input:ajaxAction} --format json",
+      "group": "none",
+      "problemMatcher": []
+    }
+  ]
+}