Z Code

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