huly-vibe-sync

Huly-Vibe Sync is a bidirectional synchronization service that connects Huly, Vibe Kanban, and an optional Beads/Git-backed issue tracker using the MCP protocol. It continuously syncs projects and issues between the Huly REST API and Vibe Kanban, with an additional third integration layer (Beads) for distributed issue tracking. The server is designed for near real-time updates, parallel processing across multiple projects, and smart caching to skip empty projects. To use it, run the Docker image in a container and configure the environment to point at your Huly instance and Vibe MCP endpoint. The service exposes its sync capabilities through MCP endpoints and a REST API client for efficient, incremental synchronization. You can tune behavior with environment variables such as SYNC_INTERVAL, MAX_WORKERS, and SKIP_EMPTY_PROJECTS to balance speed and API load. Ensure Huly, Vibe, and Beads (if used) are reachable from the container.

Prerequisites:

• Docker installed on your host
• Access to Huly API and Vibe MCP endpoint
• Network connectivity between container and Huly/Vibe endpoints

Installation steps:

1. Pull the latest image (or use in your MCP config): docker pull ghcr.io/oculairmedia/huly-vibe-sync:latest

2. Create an environment configuration file or set environment variables when running the container. Example values:

   • HULY_API_URL=http://<host>:3457/api
   • HULY_USE_REST=true
   • VIBE_MCP_URL=http://<host>:9717/mcp
   • SYNC_INTERVAL=10000
   • INCREMENTAL_SYNC=true
   • PARALLEL_SYNC=true
   • MAX_WORKERS=5
   • SKIP_EMPTY_PROJECTS=true
   • DRY_RUN=false

3. Run the container with the required env vars. Example (adjust host URLs as needed): docker run -d
   -e HULY_API_URL=http://huly-host:3457/api
   -e HULY_USE_REST=true
   -e VIBE_MCP_URL=http://vibe-host:9717/mcp
   -e SYNC_INTERVAL=10000
   -e INCREMENTAL_SYNC=true
   -e PARALLEL_SYNC=true
   -e MAX_WORKERS=5
   -e SKIP_EMPTY_PROJECTS=true
   -e DRY_RUN=false
   ghcr.io/oculairmedia/huly-vibe-sync:latest

4. (Optional) If using docker-compose, create a docker-compose.yml that uses image ghcr.io/oculairmedia/huly-vibe-sync:latest and defines the same environment variables, then run: docker-compose up -d

5. Monitor logs for health and progress: docker logs -f <container_id>

Tips and notes:

• Environment variables control core behavior; adjust SYNC_INTERVAL for faster/slower cycles and MAX_WORKERS to manage API load. Start with defaults and tune based on observed performance.
• Ensure HULY_API_URL, VIBE_MCP_URL, and any Beads integration endpoints are accessible from the host running the container.
• If running as MCP server in a multi-node setup, consider coordinating environment variable values across nodes to avoid conflicts.
• For debugging, set DRY_RUN=true to test the sync flow without writing changes.
• If you encounter issues with authentication or network, verify firewall rules and that the container has proper DNS resolution for the endpoints.
• The container supports both full and incremental sync; ensure INCORRECTLY configured timestamps don’t block updates by enabling incremental mode.
• When using Beads integration, ensure the git-backed issue tracker is reachable and properly authenticated if required.