Development Environment Setup

This document explains how to set up a local development environment for contributing to the MCP Adapter project using wp-env, a Docker-based WordPress environment manager. It covers prerequisite tools, initial setup commands, and environment verification.

For installing MCP Adapter as a package or plugin in an existing WordPress site, see page 2.1 (Installation). For detailed testing instructions after environment setup, see page 7.1 (Testing). For code quality requirements, see page 7.2 (Code Quality).

---

Overview

The MCP Adapter uses wp-env (provided by @wordpress/env npm package) to create isolated Docker containers for WordPress development and testing. This approach eliminates manual database configuration and ensures consistent environments across all contributors.

Why wp-env:

• Zero-configuration WordPress: Automatically installs WordPress core, MySQL, and PHP
• Dual environments: Separate containers for development (manual testing) and tests (PHPUnit)
• Volume mounting: Source code changes are immediately reflected without rebuilds
• WP-CLI access: Built-in command-line interface for WordPress operations

Environment Structure:

Component	Purpose	Location
Development Container	Manual testing at http://localhost:8888	Port 8888
Test Container	Automated PHPUnit execution	Port 8889
Source Code	Volume-mounted plugin files	wp-content/plugins/mcp-adapter/
Composer Dependencies	PHP packages (PHPUnit, PHPCS, PHPStan)	vendor/
Node Dependencies	npm packages (wp-env, Prettier)	node_modules/

Sources: CONTRIBUTING.md30-67 docs/guides/testing.md19-31 </old_str> <new_str>

Overview

The MCP Adapter uses @wordpress/env (wp-env) to create isolated Docker containers for WordPress development and testing. This approach eliminates manual database configuration and ensures consistent environments across all contributors.

Why wp-env:

• Zero-configuration WordPress: Automatically installs WordPress core, MySQL, and PHP
• Dual environments: Separate containers for development (manual testing) and tests (PHPUnit)
• Volume mounting: Source code changes are immediately reflected without rebuilds
• WP-CLI access: Built-in command-line interface via npm run wp-env run tests-cli

Environment Structure:

Component	Purpose	Access
Development Container	Manual testing, debugging	http://localhost:8888
Test Container	PHPUnit test execution	http://localhost:8889
MySQL Database	WordPress database engine	Internal (Docker network)
Volume Mount	Plugin source at wp-content/plugins/mcp-adapter/	Bidirectional sync

Sources: CONTRIBUTING.md30-67 docs/guides/testing.md19-31

---

Overview

The MCP Adapter uses wp-env to provide a containerized WordPress development environment with all dependencies pre-configured. This eliminates manual database setup and ensures consistent development environments across contributors.

Development Environment Components:

Component	Purpose	Technology
wp-env	WordPress container orchestration	Docker, Node.js
PHPUnit	Unit and integration testing	PHP testing framework
PHPCS	Code style enforcement	WordPress Coding Standards
PHPStan	Static analysis	Type checking at level 8
Prettier	Code formatting	Non-PHP file formatting
Composer	PHP dependency management	Autoloading, dev tools

Sources: CONTRIBUTING.md30-60 docs/guides/testing.md6-22

---

Prerequisites

The following tools must be installed on your development machine:

Tool	Version	Purpose
Node.js	20.x	Required for wp-env and npm scripts
Docker	Latest	Container runtime for WordPress environment
Git	Latest	Version control
Composer	Latest	Optional: for local PHP tool execution

Recommended: Use NVM for Node.js version management to ensure compatibility with the .nvmrc file in the repository.

Sources: CONTRIBUTING.md32-39

---

Initial Setup

Repository Clone and Dependency Installation

This installs:

• npm dependencies: wp-env, testing utilities, formatting tools
• Composer dependencies: PHPUnit, PHPCS, PHPStan, WordPress stubs, test fixtures

Sources: CONTRIBUTING.md43-60

Starting the Development Environment

This command:

1. Downloads WordPress Docker images (first run only)
2. Creates two WordPress instances:
   • Development: http://localhost:8888
   • Tests: http://localhost:8889 (used by PHPUnit)
3. Installs and activates the MCP Adapter plugin
4. Configures WordPress with default admin credentials

Default Credentials:

• Username: admin
• Password: password
• Admin Dashboard: http://localhost:8888/wp-admin/

Sources: CONTRIBUTING.md62-67 docs/guides/testing.md24-31

---

Development Environment Architecture

Docker Container Architecture

wp-env Container Structure:

Key Points:

• wordpress:cli Docker image provides WordPress + PHP + WP-CLI
• Volume mounts enable real-time code updates (no container rebuild needed)
• Separate MySQL databases for development and testing prevent data conflicts
• npm run wp-env run tests-cli executes WP-CLI commands in test container

Sources: CONTRIBUTING.md30-82 docs/guides/testing.md19-31

Project Directory Structure

The repository follows standard WordPress plugin structure with additional development tooling:

mcp-adapter/
├── src/ # Plugin source code (PSR-4: WP\MCP)
│ ├── Core/ # McpAdapter, McpServer, McpComponentRegistry
│ ├── Transport/ # HttpTransport, RequestRouter, StdioServerBridge
│ ├── Handlers/ # ToolsHandler, ResourcesHandler, PromptsHandler
│ ├── Domain/ # McpTool, McpResource, McpPrompt
│ └── Infrastructure/ # McpErrorFactory, observability handlers
├── tests/ # PHPUnit test suite
│ ├── Unit/ # Logic tests (no WordPress dependencies)
│ ├── Integration/ # WordPress API integration tests
│ ├── Fixtures/ # DummyObservabilityHandler, DummyErrorHandler
│ └── _output/ # Generated coverage reports (git-ignored)
├── vendor/ # Composer dependencies (git-ignored)
│ ├── phpunit/phpunit/ # Test framework
│ ├── squizlabs/php_codesniffer/ # PHPCS linter
│ └── phpstan/phpstan/ # Static analyzer
├── node_modules/ # npm dependencies (git-ignored)
│ └── @wordpress/env/ # wp-env Docker orchestration
├── composer.json # PHP dependencies + PSR-4 autoloading
├── package.json # npm scripts (wp-env, lint, test)
├── .wp-env.json # wp-env configuration (optional)
├── phpunit.xml # PHPUnit bootstrap and test paths
├── phpstan.neon.dist # PHPStan level 8 configuration
└── phpcs.xml.dist # WordPress coding standards rules

Configuration File Purposes:

File	Purpose	Used By
composer.json	PHP dependency management, PSR-4 autoloading	composer install
package.json	npm scripts, wp-env configuration	npm run * commands
phpunit.xml	Test suite configuration, bootstrap file	npm run test:php
phpcs.xml.dist	PHPCS WordPress coding standards	npm run lint:php
phpstan.neon.dist	PHPStan level 8 rules	npm run lint:php:stan

Sources: docs/guides/testing.md13-18 CONTRIBUTING.md43-60

---

Verifying Installation

After completing initial setup, verify that the environment is working correctly:

Check WordPress Installation

Check WP-CLI Access

Check Composer Autoloader

Access WordPress Admin

1. Navigate to http://localhost:8888/wp-admin/
2. Log in with credentials: admin / password
3. Go to Plugins → Verify "MCP Adapter" is active
4. Go to Tools → Site Health → Verify no critical issues

Sources: CONTRIBUTING.md62-67

Available npm Scripts

Environment Management:

Command	Purpose	Notes
npm run wp-env start	Start Docker containers	First run downloads WordPress images (~5GB)
npm run wp-env stop	Stop containers	Data persists for next start
npm run wp-env clean	Remove containers/volumes	Destroys all data, requires restart
npm run wp-env run tests-cli <cmd>	Execute WP-CLI command	Runs in test container

Development Tasks:

Command	Purpose	When to Use
npm run test:php	Run PHPUnit tests	After code changes, before commit
npm run lint:php	Check coding standards	Before commit
npm run lint:php:fix	Auto-fix PHPCS issues	Before manual review
npm run lint:php:stan	PHPStan analysis	Before commit
npm run format	Format non-PHP files	Before commit

Build:

Command	Purpose	Notes
npm run plugin-zip	Create distribution ZIP	After composer install --no-dev

For detailed testing instructions, see page 7.1 (Testing). For code quality requirements, see page 7.2 (Code Quality).

Sources: CONTRIBUTING.md69-110 docs/guides/testing.md33-43

---

Environment Management

Common wp-env Operations

Lifecycle Commands:

WP-CLI Command Execution:

Container Access:

Instance	HTTP URL	Purpose	Database
Development	http://localhost:8888	Manual testing, debugging	wordpress_dev
Tests	http://localhost:8889	PHPUnit execution	wordpress_test

Sources: CONTRIBUTING.md76-82 docs/guides/testing.md148-152

Custom wp-env Configuration

Create .wp-env.json in the repository root to customize the environment:

Configuration Options:

Common Customizations:

Option	Purpose	Example Value
core	WordPress version	"WordPress/WordPress#6.8" (tag) or "latest"
phpVersion	PHP version	"7.4", "8.0", "8.1", "8.2", "8.3"
plugins	Additional plugins	["."] (current plugin) + dependency URLs
port	Development HTTP port	8890 (if 8888 is in use)
testsPort	Test instance port	8891
env.development	WordPress constants	{"WP_DEBUG": true}

Note: After modifying .wp-env.json, run npm run wp-env clean all to apply changes.

Sources: CONTRIBUTING.md39-42

---

Troubleshooting

Common Issues and Solutions

Class Not Found Errors

Symptom: Fatal error: Class 'WP\MCP\...' not found

Cause: Composer autoloader outdated after adding new classes or switching branches

Solution:

The --env-cwd flag sets the working directory inside the Docker container to the plugin directory.

Sources: docs/guides/testing.md138-142

wp-env Start Failures

Symptom: Error: Docker is not running or container creation failures

Solution:

Persistent Issues:

• Verify Docker is running: docker ps
• Check available disk space: Docker requires ~5GB
• Remove dangling containers: docker system prune

Sources: docs/guides/testing.md123-135

Port Conflicts

Symptom: Error: Port 8888 is already allocated

Solution:

Sources: docs/guides/testing.md144-146

Permission Errors

Symptom: Cannot write to vendor/ or tests/_output/

Solution:

Sources: docs/guides/testing.md144

Test Database Corruption

Symptom: Tests fail with database errors after interrupted runs

Solution:

This destroys and recreates the test environment from scratch.

Sources: docs/guides/testing.md127-135

---

WP-CLI Access

The MCP Adapter includes STDIO transport for WP-CLI integration, allowing AI agents to interact with WordPress via command-line interface. This requires the environment to be running.

Basic WP-CLI Usage

Available wp mcp Commands:

Command	Purpose	Example
wp mcp server	Start STDIO MCP server	Interactive JSON-RPC session
wp mcp list-tools	List available tools	Shows registered abilities
wp mcp list-resources	List available resources	Shows resource abilities
wp mcp list-prompts	List available prompts	Shows prompt abilities

For detailed STDIO transport documentation, see page 5.5 (STDIO Transport).

Sources: CONTRIBUTING.md76-82

---

Next Steps

After setting up your development environment:

1. Write Tests: See Testing for detailed testing guide
2. Create Abilities: See Creating Abilities for ability development
3. Review Architecture: See Core System to understand system design
4. Submit Contributions: Follow Contributing Guide for PR workflow

For troubleshooting specific issues, see Common Issues

Sources: docs/README.md29-33