Troubleshooting

Solutions for common issues with the WPZylos MCP server.

WPZYLOS_ROOT Not Set or Wrong Path

Symptom: Tools return errors like "Cannot find framework root" or "Package registry is empty".

Cause: The WPZYLOS_ROOT environment variable is missing, empty, or points to a directory that does not contain the WPZylos monorepo.

Fix:

1. Verify the variable is set in your IDE config:

{
  "env": {
    "WPZYLOS_ROOT": "D:/path/to/wpzylos"
  }
}

2. Verify the path exists and contains framework packages:

ls $WPZYLOS_ROOT/wpzylos-core/composer.json

3. Use forward slashes on Windows. Backslashes can cause parsing issues in JSON configs:

"WPZYLOS_ROOT": "D:/laragon/www/wpzylos"

4. Restart your IDE after changing the config. Most editors do not hot-reload MCP server configs.

Build Errors

TypeScript Compilation Failures

Symptom: npm run build fails with TypeScript errors.

Fix:

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build

If errors persist, check your Node.js version:

node --version   # Must be 18+

Missing Dependencies

Symptom: Cannot find module errors during build or at runtime.

Fix:

npm install

If using a monorepo with workspaces, run install from the monorepo root:

cd /path/to/wpzylos
npm install

Type Errors After Framework Changes

Symptom: Build fails after pulling new framework code.

Fix:

rm -rf dist
npm run build

The MCP server's type definitions may need to catch up with framework changes. Check for pending PRs or updates to the MCP package.

Tools Not Appearing in IDE

Symptom: The AI does not list any WPZylos tools, or says the MCP server is not connected.

Checklist:

1. Config location -- Make sure the MCP config is in the right file for your editor:
   • Cursor: .cursor/mcp.json in project root
   • VS Code: settings.json (user or workspace)
   • Claude Desktop: claude_desktop_config.json
2. JSON syntax -- Validate your config with a JSON linter. A trailing comma or missing quote will silently break the config.
3. Path to dist/index.js -- Use an absolute path or a path relative to the project root. Verify the file exists:

ls path/to/wpzylos-mcp/dist/index.js

4. Restart the editor -- MCP servers are launched as child processes. The editor must restart to pick up config changes.
5. Check server logs -- Some editors show MCP server output in a debug console or log panel. Look for startup errors there.

Testing the Server Manually

Run the server directly to check for startup errors:

WPZYLOS_ROOT=/path/to/wpzylos node path/to/wpzylos-mcp/dist/index.js

The server communicates over stdin/stdout, so it will appear to hang (waiting for JSON-RPC input). If it exits immediately with an error, that error is your problem.

On Windows (PowerShell):

$env:WPZYLOS_ROOT = "D:/path/to/wpzylos"
node path/to/wpzylos-mcp/dist/index.js

Stale Cache

Symptom: The server returns outdated class information, missing methods, or old package listings after you have updated the framework source.

Cause: The file-analyzer and package-registry cache parsed data in memory for performance. The cache persists for the lifetime of the server process.

Fix:

1. Restart the MCP server. In most editors, this means restarting the editor or toggling the MCP server off and on.
2. Force re-analysis. Use the set_project_target tool to re-initialize the server's context:

set_project_target({ path: "/path/to/your/plugin" })

This triggers a fresh scan of the framework packages.

3. If developing the framework itself, consider running the MCP in dev mode (npm run dev) which rebuilds the server on changes. Note that you still need to restart the editor to reconnect.

Large Plugin Analysis Timeouts

Symptom: Tools like validate_structure or inspect_hook_map take a very long time or time out on large plugins with many files.

Cause: The file-analyzer parses every PHP file in the target directory using regex-based extraction. Plugins with hundreds of files or very large files (10,000+ lines) can hit performance limits.

Fix:

1. Narrow the target. Use set_project_target to point at a specific subdirectory rather than the entire plugin:

set_project_target({ path: "/path/to/plugin/src/Modules/Orders" })

2. Exclude vendor directories. The analyzer should skip vendor/ and node_modules/ by default. If it does not, check that these directories are listed in the server's exclusion config.
3. Split analysis. Instead of running validate_structure on the whole plugin, validate one module at a time.

Common Generation Mistakes

Wrong Namespace

Symptom: Generated code uses an incorrect namespace like App\Providers instead of the plugin's namespace.

Fix: Always call set_project_target before generating code. This tells the server your plugin's root namespace and directory structure:

set_project_target({
  path: "/path/to/my-awesome-plugin",
  namespace: "MyAwesomePlugin"
})

Missing Provider Registration

Symptom: Generated providers, models, or commands exist but are not loaded by the plugin.

Cause: Code generation creates the file but does not auto-register it in the plugin's main provider. This is by design -- automatic file modification of existing code is risky.

Fix: After generating a provider, register it manually in your plugin's AppServiceProvider:

use MyAwesomePlugin\Providers\CacheProvider;

public function register(): void
{
    $this->app->register(CacheProvider::class);
}

The AI will usually remind you to do this, but always double-check.

Stub Variable Placeholders Left in Output

Symptom: Generated code contains {{ variable }} or __PLACEHOLDER__ strings.

Cause: A required stub variable was not provided and the stub engine left the placeholder as-is.

Fix: Check the tool's required parameters. Most generation tools require at least name and module. Provide all required fields:

generate_model({
  name: "Contact",
  module: "ContactManager",
  table: "contacts",
  fillable: ["name", "email", "phone"]
})

Getting Help

If your issue is not listed here:

1. Check the Overview to understand the architecture
2. Re-read Installation for setup steps
3. Open an issue in the repository with:
   • Your Node.js version (node --version)
   • Your editor name and version
   • The exact error message or unexpected behavior
   • Your MCP config (redact sensitive paths)