# Lackey
**Task chain management engine for AI agents with MCP integration**
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
## Overview
Lackey is a sophisticated task chain management engine designed specifically for AI agents. It provides intelligent dependency management, DAG validation, and comprehensive workflow automation while storing all data directly in your project repository. This design enables AI agents to work within consistent, structured workflows while maintaining full human visibility and control.
### Key Features
🤖 **AI-First Design**: Built specifically for AI agent workflows with MCP integration
📁 **Repository-Based Storage**: All task data lives in your project repository
🔗 **Intelligent Dependencies**: Advanced DAG validation prevents circular dependencies
📝 **Rich Notes System**: Comprehensive note-taking with search and categorization
🔄 **Workflow Automation**: Bulk operations and status management
🎯 **Zero Global State**: Each project is completely self-contained
🔧 **Extensible Architecture**: Template system for domain-specific customization
## Quick Start
### Installation
```bash
pip install lackey-mcp
```
### Initialize Your First Project
```bash
# Initialize a new project
lackey init --domain web-development --name "My Web Project"
# Start the MCP server
lackey serve
```
### Connect with AI Agents
```bash
# Using Amazon Q
q chat --agent manager "Let's plan the first sprint for our web project"
# Or connect any MCP-compatible AI agent to localhost:3000
```
### Basic Usage
```python
from lackey import LackeyCore
# Initialize Lackey in your project
lackey = LackeyCore()
# Create a project
project = lackey.create_project(
friendly_name="My Project",
description="A sample project",
objectives=["Build MVP", "Deploy to production"]
)
# Create tasks with dependencies
task1 = lackey.create_task(
project_id=project.id,
title="Setup Development Environment",
objective="Configure development tools and dependencies",
steps=["Install Python", "Setup virtual environment", "Install dependencies"],
success_criteria=["All tests pass", "Development server runs"]
)
task2 = lackey.create_task(
project_id=project.id,
title="Implement Core Features",
objective="Build the main application features",
steps=["Design API", "Implement endpoints", "Add tests"],
success_criteria=["API documented", "Tests pass", "Code reviewed"],
dependencies=[task1.id] # This task depends on task1
)
```
## MCP Integration
Lackey provides 25 comprehensive MCP tools for AI agents:
### Project Management
- `create_project` - Create new projects with objectives and metadata
- `list_projects` - List and filter projects by status or tags
- `get_project` - Get detailed project information
- `update_project` - Update project details and status
### Task Management
- `create_task` - Create tasks with dependencies and success criteria
- `get_task` - Get detailed task information
- `list_tasks` - List and filter tasks by various criteria
- `update_task_status` - Update task status with notes
- `complete_task_steps` - Mark specific task steps as complete
- `get_task_progress` - Get detailed progress information
### Assignment & Collaboration
- `assign_task` - Assign tasks to team members
- `reassign_task` - Reassign tasks with notes
- `bulk_assign_tasks` - Assign multiple tasks at once
- `bulk_update_task_status` - Update status for multiple tasks
### Dependency Management
- `add_task_dependencies` - Add dependencies with cycle validation
- `remove_task_dependencies` - Remove task dependencies
- `validate_dependencies` - Check for dependency cycles
- `validate_task_dependencies_integrity` - Comprehensive dependency validation
- `get_ready_tasks` - Get tasks ready to work on
- `get_blocked_tasks` - Get tasks blocked by dependencies
### Notes & Documentation
- `add_task_note` - Add rich notes with markdown support
- `get_task_notes` - Retrieve task notes with filtering
- `search_task_notes` - Search notes by content and metadata
### Advanced Operations
- `clone_task` - Clone tasks with optional modifications
- `archive_task` - Archive completed or obsolete tasks
## Architecture
Lackey uses a file-based storage system that keeps all data in your repository:
```
your-project/
├── .lackey/
│ ├── projects/ # Project definitions
│ ├── tasks/ # Task data and metadata
│ ├── notes/ # Rich notes and documentation
│ └── config.yaml # Workspace configuration
├── your-code/ # Your actual project files
└── README.md
```
### Core Components
- **LackeyCore**: Main engine for task and project management
- **MCP Server**: FastMCP-based server providing 25 tools for AI agents
- **DAG Validator**: NetworkX-based dependency validation
- **Notes System**: Rich note-taking with search and categorization
- **File Operations**: Atomic operations with rollback capabilities
## Use Cases
### Software Development
```bash
lackey init --domain software-development --name "API Service"
# Creates tasks for: planning, development, testing, deployment
```
### Data Science Projects
```bash
lackey init --domain data-science --name "ML Pipeline"
# Creates tasks for: data collection, analysis, modeling, validation
```
### Content Creation
```bash
lackey init --domain content-creation --name "Blog Series"
# Creates tasks for: research, writing, editing, publishing
```
## Advanced Features
### Rich Notes System
Add comprehensive notes to any task with markdown support:
```python
lackey.add_task_note(
project_id=project.id,
task_id=task.id,
content="## Progress Update\n\nCompleted API design. Next: implementation.",
note_type="progress",
tags="api,design,milestone"
)
```
### Bulk Operations
Efficiently manage multiple tasks:
```python
# Update multiple task statuses
lackey.bulk_update_task_status(
project_id=project.id,
task_ids=[task1.id, task2.id, task3.id],
status="in-progress",
note="Starting sprint 2"
)
```
### Dependency Validation
Automatic cycle detection and validation:
```python
# Lackey automatically prevents circular dependencies
lackey.add_task_dependencies(
project_id=project.id,
task_id=task1.id,
dependency_ids=[task2.id] # Will fail if this creates a cycle
)
```
## Configuration
### MCP Server Configuration
Add to your MCP client configuration:
```json
{
"mcpServers": {
"lackey": {
"command": "lackey",
"args": ["serve"],
"env": {}
}
}
}
```
### Agent Templates
Lackey includes templates for different agent roles:
- **Manager**: Project planning and coordination
- **Developer**: Code implementation and technical tasks
- **Architect**: System design and technical decisions
- **Writer**: Documentation and content creation
## Documentation
- **[User Guide](docs/basic-usage-guide.md)** - Comprehensive usage examples
- **[Design Specification](docs/design-spec.md)** - System architecture and design
- **[Development Guide](docs/development-spec.md)** - API reference and implementation details
- **[Notes System](docs/notes_system.md)** - Rich note-taking features
## Requirements
- **Python**: 3.10 or higher
- **Dependencies**: PyYAML, NetworkX, Click, MCP SDK
- **Storage**: File-based (no database required)
- **Platform**: Cross-platform (Windows, macOS, Linux)
## Installation Options
### Standard Installation
```bash
pip install lackey-mcp
```
### Development Installation
```bash
git clone https://github.com/lackey-ai/lackey
cd lackey
pip install -e ".[dev,security]"
```
### With Documentation Tools
```bash
pip install lackey-mcp[docs]
```
## CLI Commands
```bash
# Initialize new project
lackey init [--domain DOMAIN] [--name NAME]
# Start MCP server
lackey serve [--port PORT] [--host HOST]
# Check system health
lackey doctor
# Show version information
lackey version
```
## Contributing
We welcome contributions! Please see our [Development Guide](DEVELOPMENT.md) for setup instructions and coding standards.
### Development Setup
```bash
# Clone and setup
git clone https://github.com/lackey-ai/lackey
cd lackey
pip install -e ".[dev,security]"
# Install pre-commit hooks
pre-commit install
# Run tests
pytest --cov=lackey
# Format code
black src tests
```
### Testing
Lackey maintains high test coverage with comprehensive test suites:
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=lackey --cov-report=html
# Run specific test categories
pytest tests/test_core/
pytest tests/test_mcp/
```
## License
This project is licensed under a Proprietary License. See [LICENSE](LICENSE) for details.
---
**Built for AI agents, designed for humans.** 🤖✨
Raw data
{
"_id": null,
"home_page": null,
"name": "lackey-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "task-management, mcp, ai-agents, dag, workflow",
"author": null,
"author_email": "Lackey Contributors <contact@lackey.dev>",
"download_url": "https://files.pythonhosted.org/packages/23/85/b8f0f4c8ddc0872ce58c3a1eacb77d5067d4708731e70f1cbdbf56dab4c7/lackey_mcp-1.1.0.tar.gz",
"platform": null,
"description": "# Lackey\n\n**Task chain management engine for AI agents with MCP integration**\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://modelcontextprotocol.io/)\n\n## Overview\n\nLackey is a sophisticated task chain management engine designed specifically for AI agents. It provides intelligent dependency management, DAG validation, and comprehensive workflow automation while storing all data directly in your project repository. This design enables AI agents to work within consistent, structured workflows while maintaining full human visibility and control.\n\n### Key Features\n\n\ud83e\udd16 **AI-First Design**: Built specifically for AI agent workflows with MCP integration\n\ud83d\udcc1 **Repository-Based Storage**: All task data lives in your project repository\n\ud83d\udd17 **Intelligent Dependencies**: Advanced DAG validation prevents circular dependencies\n\ud83d\udcdd **Rich Notes System**: Comprehensive note-taking with search and categorization\n\ud83d\udd04 **Workflow Automation**: Bulk operations and status management\n\ud83c\udfaf **Zero Global State**: Each project is completely self-contained\n\ud83d\udd27 **Extensible Architecture**: Template system for domain-specific customization\n\n## Quick Start\n\n### Installation\n\n```bash\npip install lackey-mcp\n```\n\n### Initialize Your First Project\n\n```bash\n# Initialize a new project\nlackey init --domain web-development --name \"My Web Project\"\n\n# Start the MCP server\nlackey serve\n```\n\n### Connect with AI Agents\n\n```bash\n# Using Amazon Q\nq chat --agent manager \"Let's plan the first sprint for our web project\"\n\n# Or connect any MCP-compatible AI agent to localhost:3000\n```\n\n### Basic Usage\n\n```python\nfrom lackey import LackeyCore\n\n# Initialize Lackey in your project\nlackey = LackeyCore()\n\n# Create a project\nproject = lackey.create_project(\n friendly_name=\"My Project\",\n description=\"A sample project\",\n objectives=[\"Build MVP\", \"Deploy to production\"]\n)\n\n# Create tasks with dependencies\ntask1 = lackey.create_task(\n project_id=project.id,\n title=\"Setup Development Environment\",\n objective=\"Configure development tools and dependencies\",\n steps=[\"Install Python\", \"Setup virtual environment\", \"Install dependencies\"],\n success_criteria=[\"All tests pass\", \"Development server runs\"]\n)\n\ntask2 = lackey.create_task(\n project_id=project.id,\n title=\"Implement Core Features\",\n objective=\"Build the main application features\",\n steps=[\"Design API\", \"Implement endpoints\", \"Add tests\"],\n success_criteria=[\"API documented\", \"Tests pass\", \"Code reviewed\"],\n dependencies=[task1.id] # This task depends on task1\n)\n```\n\n## MCP Integration\n\nLackey provides 25 comprehensive MCP tools for AI agents:\n\n### Project Management\n- `create_project` - Create new projects with objectives and metadata\n- `list_projects` - List and filter projects by status or tags\n- `get_project` - Get detailed project information\n- `update_project` - Update project details and status\n\n### Task Management\n- `create_task` - Create tasks with dependencies and success criteria\n- `get_task` - Get detailed task information\n- `list_tasks` - List and filter tasks by various criteria\n- `update_task_status` - Update task status with notes\n- `complete_task_steps` - Mark specific task steps as complete\n- `get_task_progress` - Get detailed progress information\n\n### Assignment & Collaboration\n- `assign_task` - Assign tasks to team members\n- `reassign_task` - Reassign tasks with notes\n- `bulk_assign_tasks` - Assign multiple tasks at once\n- `bulk_update_task_status` - Update status for multiple tasks\n\n### Dependency Management\n- `add_task_dependencies` - Add dependencies with cycle validation\n- `remove_task_dependencies` - Remove task dependencies\n- `validate_dependencies` - Check for dependency cycles\n- `validate_task_dependencies_integrity` - Comprehensive dependency validation\n- `get_ready_tasks` - Get tasks ready to work on\n- `get_blocked_tasks` - Get tasks blocked by dependencies\n\n### Notes & Documentation\n- `add_task_note` - Add rich notes with markdown support\n- `get_task_notes` - Retrieve task notes with filtering\n- `search_task_notes` - Search notes by content and metadata\n\n### Advanced Operations\n- `clone_task` - Clone tasks with optional modifications\n- `archive_task` - Archive completed or obsolete tasks\n\n## Architecture\n\nLackey uses a file-based storage system that keeps all data in your repository:\n\n```\nyour-project/\n\u251c\u2500\u2500 .lackey/\n\u2502 \u251c\u2500\u2500 projects/ # Project definitions\n\u2502 \u251c\u2500\u2500 tasks/ # Task data and metadata\n\u2502 \u251c\u2500\u2500 notes/ # Rich notes and documentation\n\u2502 \u2514\u2500\u2500 config.yaml # Workspace configuration\n\u251c\u2500\u2500 your-code/ # Your actual project files\n\u2514\u2500\u2500 README.md\n```\n\n### Core Components\n\n- **LackeyCore**: Main engine for task and project management\n- **MCP Server**: FastMCP-based server providing 25 tools for AI agents\n- **DAG Validator**: NetworkX-based dependency validation\n- **Notes System**: Rich note-taking with search and categorization\n- **File Operations**: Atomic operations with rollback capabilities\n\n## Use Cases\n\n### Software Development\n```bash\nlackey init --domain software-development --name \"API Service\"\n# Creates tasks for: planning, development, testing, deployment\n```\n\n### Data Science Projects\n```bash\nlackey init --domain data-science --name \"ML Pipeline\"\n# Creates tasks for: data collection, analysis, modeling, validation\n```\n\n### Content Creation\n```bash\nlackey init --domain content-creation --name \"Blog Series\"\n# Creates tasks for: research, writing, editing, publishing\n```\n\n## Advanced Features\n\n### Rich Notes System\nAdd comprehensive notes to any task with markdown support:\n\n```python\nlackey.add_task_note(\n project_id=project.id,\n task_id=task.id,\n content=\"## Progress Update\\n\\nCompleted API design. Next: implementation.\",\n note_type=\"progress\",\n tags=\"api,design,milestone\"\n)\n```\n\n### Bulk Operations\nEfficiently manage multiple tasks:\n\n```python\n# Update multiple task statuses\nlackey.bulk_update_task_status(\n project_id=project.id,\n task_ids=[task1.id, task2.id, task3.id],\n status=\"in-progress\",\n note=\"Starting sprint 2\"\n)\n```\n\n### Dependency Validation\nAutomatic cycle detection and validation:\n\n```python\n# Lackey automatically prevents circular dependencies\nlackey.add_task_dependencies(\n project_id=project.id,\n task_id=task1.id,\n dependency_ids=[task2.id] # Will fail if this creates a cycle\n)\n```\n\n## Configuration\n\n### MCP Server Configuration\n\nAdd to your MCP client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"lackey\": {\n \"command\": \"lackey\",\n \"args\": [\"serve\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Agent Templates\n\nLackey includes templates for different agent roles:\n\n- **Manager**: Project planning and coordination\n- **Developer**: Code implementation and technical tasks\n- **Architect**: System design and technical decisions\n- **Writer**: Documentation and content creation\n\n## Documentation\n\n- **[User Guide](docs/basic-usage-guide.md)** - Comprehensive usage examples\n- **[Design Specification](docs/design-spec.md)** - System architecture and design\n- **[Development Guide](docs/development-spec.md)** - API reference and implementation details\n- **[Notes System](docs/notes_system.md)** - Rich note-taking features\n\n## Requirements\n\n- **Python**: 3.10 or higher\n- **Dependencies**: PyYAML, NetworkX, Click, MCP SDK\n- **Storage**: File-based (no database required)\n- **Platform**: Cross-platform (Windows, macOS, Linux)\n\n## Installation Options\n\n### Standard Installation\n```bash\npip install lackey-mcp\n```\n\n### Development Installation\n```bash\ngit clone https://github.com/lackey-ai/lackey\ncd lackey\npip install -e \".[dev,security]\"\n```\n\n### With Documentation Tools\n```bash\npip install lackey-mcp[docs]\n```\n\n## CLI Commands\n\n```bash\n# Initialize new project\nlackey init [--domain DOMAIN] [--name NAME]\n\n# Start MCP server\nlackey serve [--port PORT] [--host HOST]\n\n# Check system health\nlackey doctor\n\n# Show version information\nlackey version\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Development Guide](DEVELOPMENT.md) for setup instructions and coding standards.\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/lackey-ai/lackey\ncd lackey\npip install -e \".[dev,security]\"\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest --cov=lackey\n\n# Format code\nblack src tests\n```\n\n### Testing\n\nLackey maintains high test coverage with comprehensive test suites:\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=lackey --cov-report=html\n\n# Run specific test categories\npytest tests/test_core/\npytest tests/test_mcp/\n```\n\n## License\n\nThis project is licensed under a Proprietary License. See [LICENSE](LICENSE) for details.\n\n---\n\n**Built for AI agents, designed for humans.** \ud83e\udd16\u2728\n",
"bugtrack_url": null,
"license": "Proprietary",
"summary": "Task chain management engine for AI agents with MCP integration",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/lackey-ai/lackey/issues",
"Documentation": "https://docs.lackey.dev",
"Homepage": "https://lackey.dev",
"Repository": "https://github.com/lackey-ai/lackey"
},
"split_keywords": [
"task-management",
" mcp",
" ai-agents",
" dag",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "80e34f035213b61fd06abe1a5aac69bf254f42c5ecbaa1ca0b13563cb216c8b6",
"md5": "b9d05d268df1871145831214a252ec22",
"sha256": "66c5b5ec9f1b7556d2a6751bab9877b87afd0935876d52d5f88631fab17cbd63"
},
"downloads": -1,
"filename": "lackey_mcp-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9d05d268df1871145831214a252ec22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 133363,
"upload_time": "2025-08-07T12:32:05",
"upload_time_iso_8601": "2025-08-07T12:32:05.903990Z",
"url": "https://files.pythonhosted.org/packages/80/e3/4f035213b61fd06abe1a5aac69bf254f42c5ecbaa1ca0b13563cb216c8b6/lackey_mcp-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2385b8f0f4c8ddc0872ce58c3a1eacb77d5067d4708731e70f1cbdbf56dab4c7",
"md5": "d8fbb4eb0201a1caef0332656fad7625",
"sha256": "5711615c9ada56911009acb1ccd4092d76f729b65105ccd023989c900a174578"
},
"downloads": -1,
"filename": "lackey_mcp-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d8fbb4eb0201a1caef0332656fad7625",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 134558,
"upload_time": "2025-08-07T12:32:07",
"upload_time_iso_8601": "2025-08-07T12:32:07.134707Z",
"url": "https://files.pythonhosted.org/packages/23/85/b8f0f4c8ddc0872ce58c3a1eacb77d5067d4708731e70f1cbdbf56dab4c7/lackey_mcp-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 12:32:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lackey-ai",
"github_project": "lackey",
"github_not_found": true,
"lcname": "lackey-mcp"
}
JSON
