Z-Code MCP

MCP (Model Context Protocol) server for orchestrating multiple Claude Code sessions with HEAD/SUB coordination pattern.

Overview

Z-Code MCP enables complex, multi-task coding projects by coordinating multiple Claude Code CLI sessions:

HEAD Phase: Analyzes objectives and creates execution plans
SUB Phase: Executes tasks in parallel with controlled concurrency
Aggregation Phase: Combines results and generates summaries

Installation

Using npx (Recommended)

npx z-code-mcp

For always getting the latest version:

npx z-code-mcp@latest

Global Installation

npm install -g z-code-mcp

Claude Desktop / Claude Code Configuration

Add to your Claude configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "z-code-mcp": {
      "command": "npx",
      "args": ["-y", "z-code-mcp@latest"]
    }
  }
}

Local Development Configuration

For testing local changes without publishing:

{
  "mcpServers": {
    "z-code-mcp-dev": {
      "command": "node",
      "args": ["C:/path/to/z-code-mcp/build/index.js"]
    }
  }
}

Environment Variables

Variable	Description	Default
`Z_MCP_CLAUDE_COMMAND`	Claude CLI command	`claude`
`Z_MCP_MAX_CONCURRENT`	Max concurrent processes (1-10)	`3`
`Z_MCP_TEMP_DIR`	Temp directory for outputs	System temp
`Z_MCP_KEEP_TEMP`	Keep temp files on error	`false`
`Z_MCP_TEMPLATE_DIR`	Custom templates directory	Built-in
`Z_MCP_LOG_LEVEL`	Log level (debug/info/warn/error)	`info`

Available Task Templates

Template	Description
`code_analysis`	Analyze existing code structure and patterns
`code_generation`	Generate new code based on specifications
`test_writing`	Write tests for existing code
`documentation`	Create documentation
`security_review`	Security analysis and vulnerability detection
`refactoring`	Code improvements and refactoring
`custom`	Use custom template

Usage Example

Once configured, the MCP exposes an orchestrate tool:

{
  "objective": "Implement user authentication feature",
  "workingDirectory": "/path/to/project",
  "tasks": [
    {
      "id": "analyze",
      "type": "code_analysis",
      "description": "Analyze current auth implementation"
    },
    {
      "id": "implement",
      "type": "code_generation",
      "description": "Implement JWT authentication",
      "dependencies": ["analyze"]
    },
    {
      "id": "test",
      "type": "test_writing",
      "description": "Write auth tests",
      "dependencies": ["implement"]
    }
  ],
  "coordination": {
    "strategy": "dependency-based",
    "maxConcurrent": 3
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run MCP Inspector
npm run inspector

Auto-Update Behavior

npx caches packages: Use npx z-code-mcp@latest to force latest version
Local development: Use direct path reference for immediate updates after build

License

MIT