Yuga Planner acts as an intelligent project assistant that takes the guesswork out of scheduling. By simply describing a project—such as "building a new website"—this tool automatically breaks the big goal down into smaller, manageable tasks and finds the perfect spots for them on a calendar. It can even read existing appointments from a calendar file to ensure there are no overlaps, making sure new work fits seamlessly into a busy day without manual planning. Under the hood, this system uses a neuro-symbolic approach to solve complex organizational problems. It leverages LLamaIndex and Nebius AI to perform task decomposition and estimation, transforming natural language descriptions into actionable structured data. Once tasks are identified, the Timefold optimization engine takes over, applying advanced constraints such as business hours, weekend prevention, and skill matching. This ensures that every task is not just scheduled, but assigned to the right resources at the most efficient time while respecting sequential dependencies. For developers building AI agents, Yuga Planner provides a robust Model Context Protocol (MCP) interface that simplifies the integration of sophisticated scheduling logic into larger AI workflows. The architecture includes a specialized tool-call assembler to handle streaming data from LLMs and built-in JSON repair to maintain reliability during real-time interactions. By exposing these capabilities as a standardized MCP tool, it allows agents to handle complex project management and personal productivity tasks with professional-grade constraint satisfaction and reasoning.
1. Installation Prerequisites: * Python 3.10 * Java 17+ * Nebius API credentials (for LLM-powered features) * Docker (optional) Local Setup: 1. Clone the repository:bash git clone https://github.com/blackopsrepl/yuga-planner.git cd yuga-planner 2. Create a virtual environment:bash make venv 3. Install dependencies:bash make install 4. Run the application:bash make runDocker Setup: 1. Build the image:bash docker build -t yuga-planner . 2. Run the container:bash docker run -p 7860:7860 yuga-planner
2. Configuration API Credentials: The system requires Nebius API credentials to function. 1. Run the setup command: bash make setup-secrets 2. Edit the generated file tests/secrets/cred.py to add your actual API credentials. MCP Settings: The provided content does not include a specific mcpServers JSON configuration block for standard MCP clients (like Claude Desktop or Cursor). However, it notes that the application provides an MCP endpoint for agent workflow integration and a Chat Interface with MCP via its Gradio UI.
3. Available Tools * yuga-planner mcp tool: The primary tool for task scheduling and personal productivity. * Task Description: Accepts a natural language description of a project or task. * Calendar Integration: Accepts .ics file attachments to parse existing commitments. * Capabilities: Performs task decomposition, estimation, and constraint-based scheduling (respecting business hours 09:00-18:00 and preventing weekend assignments).
4. Example Prompts For Scheduling Requests: * "Create a new EC2 instance on AWS" * "Create a Svelte UI that allows me to query a postgresql database" * "Develop a chatbot UI based on Gradio" Standard MCP Tool Syntax:text use yuga-planner mcp tool Task Description: [Your task description] [Attach calendar.ics file]
What you can do with Yuga Planner
Use Case 1: Fitting Deep Work Projects into a Packed Meeting Schedule Problem: Professionals often have large projects (e.g., "Write the Q3 Security Audit") but struggle to find the actual "blocks" of time to do them because their calendars are fragmented by recurring meetings and appointments. Solution: Yuga Planner takes a project description and an uploaded .ics calendar file. It identifies the gaps in the user’s existing schedule, enforces business hours (9:00–18:00) and lunch breaks, and automatically pins the project tasks into the available free time. Example: A developer uploads their work calendar and asks, "Schedule the implementation of a new payment gateway." Yuga Planner breaks the project into sub-tasks like "API research," "Stripe integration," and "Unit testing," then slots them into the 2-hour windows between their existing Zoom meetings.
Use Case 2: Automated Technical Project Decomposition and Timeline Estimation Problem: When starting a new technical project, like "Building a RAG-based chatbot," it is difficult to estimate the total duration and determine the correct sequence of tasks (dependencies). Solution: The MCP uses LLamaIndex and Nebius AI to decompose a high-level goal into actionable, sequential tasks. It then uses the Timefold constraint solver to ensure that tasks requiring dependencies (e.g., "Setup Database" before "Write Query Logic") are scheduled in the correct order. Example: A user provides the prompt: "Develop a chatbot UI based on Gradio." The MCP generates a step-by-step schedule including environment setup, UI layout design, backend integration, and deployment, providing a realistic finish date based on task complexity.
Use Case 3: Skill-Based Team Task Allocation for Managers Problem: Project managers need to assign tasks to multiple team members based on their specific skills while ensuring no one is overbooked and that the project respects a 40-hour work week. Solution: Yuga Planner utilizes its neuro-symbolic architecture to match task requirements with employee skill sets. It acts as a team-wide constraint solver that prevents weekend work and ensures that the person assigned to "Database Migration" actually has the "PostgreSQL" skill tag identified during the LLM analysis phase. Example: A manager inputs a project for a "Cloud Migration." The MCP identifies tasks requiring "AWS" and "Networking" skills, checks the availability of three different team members, and generates a formatted table showing exactly who is doing what and when, ensuring the "Networking" specialist isn't assigned "UI design" tasks.
Use Case 4: Intelligent "Work-Life Balance" Personal Planning Problem: Freelancers and…
MCP Naver News — Search for news articles using the Naver News API. Requires Naver News API credentials.
MCP Orchestro — Trello for Claude Code: AI-powered task management with 60 MCP tools, visual Kanban board, and intelligent orchestration for product teams…
MCP Outlook Tools — Interact with Microsoft Outlook for calendar management, email operations, and search functionality.
MCP Personal Assistant Agent — A versatile AI personal assistant for managing your calendar, tasks, emails, web searches, and smart home.