MCP Parallel Development Template

A FastMCP server template for parallelizing LLM-assisted development workflows across multiple git worktrees. This template enables developers to work on multiple features simultaneously while maintaining persistent MCP connections across isolated development environments.

Purpose

This template solves the problem of context-switching overhead when working on multiple features. Instead of constantly switching branches and losing your development context, you can:

• Work on multiple features in parallel using git worktrees
• Maintain separate, isolated development environments
• Keep MCP server connections persistent across all worktrees
• Merge changes seamlessly when features are complete

Quick Start

Prerequisites

• Git 2.5+ (for worktree support)
• Python 3.10+
• uv (Python package manager)
• VSCode (optional, for automatic editor launching)

Setup

# Clone or use this template
git clone <your-repo>
cd <your-repo>

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Run the MCP server
uv run main.py

Configure MCP in Kiro

Add this server to your .kiro/settings/mcp.json:

{
  "mcpServers": {
    "parallel-dev": {
      "command": "uv",
      "args": ["run", "main.py"],
      "disabled": false
    }
  }
}

Core Features

Worktree Management

Create a new worktree for parallel development:

create_worktree("feature-auth")

This creates an isolated workspace in .trees/feature-auth, symlinks your virtual environment, and launches VSCode.

List all active worktrees:

list_worktrees()

Check status of worktrees:

check_worktree_status()  # All worktrees
check_worktree_status("feature-auth")  # Specific worktree

Merge completed work:

merge_worktree("feature-auth")
merge_worktree("feature-auth", delete_after=True)  # Merge and cleanup

Clean up worktrees:

cleanup_worktree("feature-auth")
cleanup_worktree("old-experiment", force=True)  # Force removal

Development Workflow

Sync dependencies across worktrees:

sync_dependencies()  # All worktrees
sync_dependencies("feature-auth")  # Specific worktree

Run tests in parallel:

run_tests_parallel()  # All worktrees
run_tests_parallel(test_path="tests/test_api.py")  # Specific test
run_tests_parallel(worktrees=["feature-auth", "feature-api"])  # Specific worktrees

Create feature branches within worktrees:

create_feature_branch("feature-auth", "auth-oauth")

MCP Persistence

Sync MCP configuration to worktrees:

sync_mcp_config()  # All worktrees
sync_mcp_config("feature-auth")  # Specific worktree

View current MCP configuration:

get_mcp_config()

Update MCP server configuration:

update_mcp_config(
    server_name="my-server",
    command="uvx",
    args=["my-package@latest"],
    env={"LOG_LEVEL": "INFO"}
)

Typical Workflow

Starting a New Feature

1. Create a worktree for your feature:

   create_worktree("feature-payment-integration")
   

2. VSCode opens automatically in the new worktree

3. Work on your feature with full MCP support

4. Check status anytime:

   check_worktree_status("feature-payment-integration")
   

Working on Multiple Features

1. Create multiple worktrees:

   create_worktree("feature-auth")
   create_worktree("feature-api")
   create_worktree("bugfix-memory-leak")
   

2. Switch between VSCode windows as needed

3. Run tests across all features:

   run_tests_parallel()
   

4. Sync dependencies when needed:

   sync_dependencies()
   

Completing a Feature

1. Check your work:

   check_worktree_status("feature-auth")
   

2. Merge back to main:

   merge_worktree("feature-auth")
   

3. If conflicts occur, resolve them manually, then:

   # After resolving conflicts
   git commit
   

4. Clean up the worktree:

   cleanup_worktree("feature-auth")
   

Or do it all in one step:

merge_worktree("feature-auth", delete_after=True)

Project Structure

├── main.py                      # MCP server entry point
├── tools/
│   ├── worktree_manager.py      # Core worktree operations
│   ├── development_tools.py     # Testing, syncing, status checks
│   └── mcp_persistence.py       # MCP configuration management
├── .claude/
│   └── commands/                # Claude command definitions
│       ├── create_worktree.md   # Command for creating worktrees
│       └── merge_worktree.md    # Command for merging worktrees
├── .trees/                      # Worktree directory (auto-created)
├── tests/                       # Test suite
└── README.md                    # This file

Customization

This template is designed to be easily customized for your specific needs:

Adding Custom Tools

1. Create a new file in tools/ (e.g., tools/my_custom_tools.py)
2. Define your functions with proper type hints and docstrings
3. Import and register in main.py:

from tools.my_custom_tools import my_tool

mcp.tool()(my_tool)

Modifying Worktree Behavior

Edit tools/worktree_manager.py to customize:

• Default worktree location (change WORKTREE_BASE_DIR)
• VSCode launch behavior
• Virtual environment handling
• Branch naming conventions

Adding Pre/Post Hooks

Extend the tools to add hooks for:

• Pre-merge validation
• Post-creation setup scripts
• Custom dependency sync logic
• Automated testing triggers

Best Practices

1. Use descriptive worktree names: feature-user-auth instead of test1
2. Keep worktrees focused: One feature per worktree
3. Sync dependencies regularly: Especially after updating main workspace
4. Check status before merging: Avoid surprises with uncommitted changes
5. Clean up completed worktrees: Free disk space and reduce clutter
6. Run parallel tests: Catch integration issues early

Troubleshooting

Worktree creation fails

• Ensure you're in a git repository
• Check that the worktree name doesn't already exist
• Verify git version supports worktrees (2.5+)

VSCode doesn't launch

• Ensure code command is in your PATH
• Launch manually: code .trees/your-worktree-name

Merge conflicts

• Use the conflict information provided by merge_worktree()
• Resolve conflicts manually in your editor
• Complete merge with git commit

Dependencies out of sync

• Run sync_dependencies() to update all worktrees
• Check that uv.lock exists in main workspace

Advanced Usage

Custom MCP Servers per Worktree

While the template syncs MCP config by default, you can customize per-worktree:

1. Edit .trees/your-worktree/.kiro/settings/mcp.json directly
2. Add worktree-specific servers or disable unwanted ones
3. Restart MCP connection in that worktree

Automated Workflows

Combine tools for automated workflows:

# Create, sync, and test a new feature
create_worktree("feature-new")
sync_dependencies("feature-new")
run_tests_parallel(worktrees=["feature-new"])

Integration with CI/CD

Use the parallel testing capability in CI:

# In your CI script
uv run python -c "from tools.development_tools import run_tests_parallel; print(run_tests_parallel())"

Contributing

This is a template - fork it and make it your own! Consider contributing improvements back:

• Additional worktree management features
• Better conflict resolution assistance
• Enhanced MCP persistence mechanisms
• Cross-platform compatibility improvements

License

MIT License - see LICENSE file for details.

Credits

Built with FastMCP for seamless MCP server creation.