Development Guide

This guide covers the development environment setup, workflow, and tooling for contributors to the MCP Adapter codebase. It provides an overview of prerequisites, local development setup, quality standards, and the contribution process.

For detailed information on specific topics:

• Testing practices and test execution: See Testing
• Code quality tools and standards: See Code Quality
• Contribution workflow and pull requests: See Contributing

Development Environment Architecture

The MCP Adapter uses wp-env to provide a containerized WordPress development environment with all necessary dependencies. This eliminates manual database setup and ensures consistency across development machines.

Key Components:

• wp-env: Docker-based WordPress environment manager from @wordpress/env package
• WordPress Container: Accessible at http://localhost:8888 with admin credentials admin/password
• tests-cli Container: Executes WP-CLI commands, PHPUnit tests, and Composer operations
• Volume Mounting: Plugin source code is mounted into both containers for live development

Sources: CONTRIBUTING.md32-66 docs/guides/testing.md21-31

Prerequisites

Requirement	Version	Installation Method
Node.js	20.x	NVM recommended
Docker	Latest	Docker Desktop
Git	Any	System package manager
Composer	Latest	Optional for local execution

NVM Usage:

Sources: CONTRIBUTING.md32-37

Local Setup

Initial Installation

The WordPress site will be available at:

• Frontend: http://localhost:8888
• Admin Dashboard: http://localhost:8888/wp-admin/ (username: admin, password: password)

Sources: CONTRIBUTING.md43-67

Environment Management Commands

Command	Purpose
npm run wp-env start	Start containers
npm run wp-env stop	Stop containers (preserve data)
npm run wp-env clean	Remove all volumes and data
npm run wp-env run tests-cli YOUR_CMD	Execute WP-CLI command

Example WP-CLI Usage:

Sources: CONTRIBUTING.md76-82 docs/guides/testing.md137-151

Development Workflow

Typical Development Iteration:

1. Make code changes in src/ directory
2. Run npm run test:php to verify functionality
3. Run npm run lint:php to check PHPCS compliance
4. Run npm run lint:php:stan to verify PHPStan level 8 analysis
5. Run npm run format to format non-PHP files
6. Commit and push when all checks pass

Sources: CONTRIBUTING.md84-99 docs/guides/testing.md36-56

Available Development Commands

Testing Commands

Command	Purpose	Passes Args to PHPUnit
npm run test:php	Run full PHPUnit test suite	Yes, via --
npm run test:php -- --filter test_name	Run specific test	Yes
npm run test:php -- tests/Unit/HandlerTest.php	Run specific file	Yes

Coverage Generation:

Coverage artifacts:

• HTML Report: tests/_output/html/index.html
• Clover XML: tests/_output/php-coverage.xml (for CI tools)

Sources: CONTRIBUTING.md92-98 docs/guides/testing.md59-72

Code Quality Commands

Command	Purpose	Auto-fix Available
npm run lint:php	Run PHPCS linting	Yes
npm run lint:php:fix	Auto-fix PHPCS issues	N/A
npm run lint:php:stan	Run PHPStan static analysis (level 8)	No
npm run format	Format with Prettier (JSON, MD, YML)	Yes (automatic)

Coding Standards:

• PHP: WordPress Coding Standards via PHPCS
• Static Analysis: PHPStan level 8
• Minimum PHP Version: 7.4
• Minimum WordPress Version: 6.8

Sources: CONTRIBUTING.md84-89 CONTRIBUTING.md13-16

Build Commands

Output: Distributable plugin ZIP file

Sources: CONTRIBUTING.md101-110

Test Suite Organization

Test Categories:

• Unit Tests: Pure PHP logic, no WordPress dependencies required
• Integration Tests: Exercise WordPress hooks, REST API, permissions, and full request flow
• Fixtures: Reusable test doubles implementing interfaces like McpObservabilityHandlerInterface and McpErrorHandlerInterface

For detailed testing practices, see Testing.

Sources: docs/guides/testing.md13-17 docs/guides/testing.md74-88

Quality Gates and CI/CD

GitHub Actions CI Matrix

The repository runs automated checks on every pull request via .github/workflows/test.yml:

All pull requests must pass:

1. PHPUnit tests on PHP 7.4 - 8.4 with WordPress latest and trunk
2. PHPCS coding standards checks
3. PHPStan level 8 static analysis

Sources: docs/guides/testing.md154-167

Common Development Scenarios

Adding a New Class

When adding new PHP classes to the codebase:

The --env-cwd flag sets the working directory inside the Docker container to ensure Composer operates on the correct composer.json.

Sources: docs/guides/testing.md138-142

Debugging Test Failures

Sources: docs/guides/testing.md122-145

Working with Multiple Branches

This ensures autoloader and dependencies stay in sync with the current branch.

Project Structure Reference

Key directories and files for development:

Path	Purpose
src/	Source code (autoloaded via PSR-4)
src/Handlers/	MCP protocol handlers
src/Transport/	HTTP and STDIO transport implementations
src/Core/	Core classes (McpAdapter, McpServer)
tests/Unit/	Unit tests
tests/Integration/	Integration tests
tests/Fixtures/	Test doubles and helpers
composer.json	PHP dependencies and autoloading
package.json	npm scripts and wp-env configuration
phpunit.xml	PHPUnit configuration
phpstan.neon.dist	PHPStan analysis configuration
.wp-env.json	wp-env environment configuration

Sources: CONTRIBUTING.md1-110 docs/guides/testing.md13-17

Next Steps

For detailed information on specific development topics:

• Testing: PHPUnit test structure, running tests, writing new tests, and troubleshooting
• Code Quality: PHPCS configuration, PHPStan analysis, formatting standards, and local quality checks
• Contributing: Pull request workflow, code review process, issue reporting, and community guidelines

Sources: CONTRIBUTING.md1-110 docs/README.md29-33