MCP server not discoverable when Claude Code runs from a different project

[mrtwebdesign]

Problem

After running ./install.sh successfully (MCP server builds, status shows green), the MCP tools are not available when Claude Code opens a different project (e.g., a WordPress theme repo). The preflight shows Connection Failed.

Root cause

.mcp.json in the AI-DDTK repo root uses a relative path:

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

Claude Code auto-detects .mcp.json from the currently open project directory. When the user opens a WordPress theme or plugin repo (not AI-DDTK itself), Claude Code doesn't see this config and has no way to start the MCP server.

Where the instructions fail

The install flow (issue #725 and install.sh) tells users to:

1. Clone and install AI-DDTK at ~/bin/ai-ddtk
2. Open their project repo in VS Code with Claude Code
3. Run a preflight that probes MCP tools like wpcc_list_features and local_wp_list_sites

Step 3 fails because there's no step between 1 and 2 that wires MCP into the project repo. The setup-mcp output shows client configuration snippets, but doesn't make it clear that the user needs to create a .mcp.json in each project they want to use AI-DDTK from.

What works today (but isn't documented in the install flow)

experimental/wire-project exists and does exactly this:

~/bin/ai-ddtk/experimental/wire-project /path/to/my-project

It creates .mcp.local.json in the target project with absolute paths to the MCP server. But this script is:

• In experimental/ — not mentioned in install.sh output or next-steps
• Not referenced in the preflight instructions
• Not mentioned in the README quick-start

Suggested fix

After setup-mcp completes, install.sh should either:

Option A — Add a clear next-step to the output:

To use AI-DDTK MCP tools from other projects, run:
  ~/bin/ai-ddtk/experimental/wire-project /path/to/your-project

Option B — Add a new install.sh subcommand:

./install.sh wire /path/to/your-project

This would be a thin wrapper around wire-project with the same validation.

Option C — Document it prominently in the preflight/onboarding flow so that when MCP fails, the user knows exactly what to do.

Expected MCP config for a wired project

{
  "mcpServers": {
    "ai-ddtk": {
      "command": "bash",
      "args": ["/Users/<you>/bin/ai-ddtk/tools/mcp-server/start.sh"],
      "cwd": "/Users/<you>/bin/ai-ddtk"
    }
  }
}

Reproduction

1. Fresh clone: git clone -b development ... ~/bin/ai-ddtk
2. cd ~/bin/ai-ddtk && ./install.sh — MCP builds successfully
3. Open a different project in VS Code with Claude Code
4. Ask Claude to call wpcc_list_features — fails, MCP not connected

🤖 Generated with Claude Code