Task orchestrator
Model Context Protocol (MCP) server for comprehensive task and feature management, providing AI assistants with a structured, context-efficient way to interact with project data.
42 Tools
Add to Docker Desktop
Version 4.43 or later needs to be installed to add the server automatically
Tools
| Name | Description |
|---|---|
add_section | Adds a section to a task, feature, or project. ## Purpose Sections store detailed content for tasks, features, and projects in a structured way. Instead of storing all content directly in the entities, sections allow for organized content blocks with specific formats and purposes. This approach optimizes context efficiency by keeping core entities lightweight. ## Usage Guidelines **EFFICIENCY RECOMMENDATION**: For adding multiple sections at once, prefer using `bulk_create_sections` instead of multiple `add_section` calls. This is especially important for: - Creating initial section sets for new tasks/features - Adding sections with shorter content (reduces network overhead) - Template-like section creation scenarios **WHEN TO USE add_section**: - Adding a single section with substantial content - Adding sections incrementally during task development - Creating sections that require careful individual validation ## Content Organization Strategy **Common Section Types** (use these title patterns for consistency): - **Requirements**: What needs to be accomplished, acceptance criteria - **Implementation Notes**: Technical approach, architecture decisions - **Testing Strategy**: Testing approach, coverage requirements - **Reference Information**: External links, documentation, resources - **Dependencies**: Prerequisites, related tasks, blocking issues - **Architecture**: Design patterns, system integration points **Ordinal Sequencing Best Practices**: - Start with ordinal 0 for the first section - Use increments of 1 for logical ordering - Leave gaps (0, 10, 20) when you anticipate inserting sections later - Requirements typically come first (ordinal 0) - Implementation details in the middle (ordinal 1-5) - Testing and validation toward the end (ordinal 6+) **Content Format Selection**: - **MARKDOWN**: Default for documentation, requirements, notes (rich formatting) - **PLAIN_TEXT**: Simple text without formatting needs - **JSON**: Structured data, configuration, API specifications - **CODE**: Source code examples, implementation snippets **Writing Markdown Content**: **CRITICAL - Section Title Handling**: - The `title` field becomes the section heading (rendered as ## H2 in markdown output) - **DO NOT** duplicate the section title as a heading in the `content` field - Content should start directly with the information, NOT with another heading - For subsections within content, use ### (H3) or lower headings **Markdown Formatting**: - Use subsection headings: `### Subsection` (H3 or lower, never H2) - Use lists: `- Item` or `1. Numbered` - Use emphasis: `**bold**` or `*italic*` - Use code: \`inline\` or \`\`\`kotlin code block\`\`\` - Use links: `[text](url)` **Example - WRONG (❌ Creates Duplicate Headings)**: ```markdown ## Requirements - **Must** support OAuth 2.0 ``` *Problem: Title field "Requirements" + content heading "## Requirements" = duplicate* **Example - CORRECT (✅ No Duplicate)**: ```markdown - **Must** support OAuth 2.0 - **Should** handle token refresh automatically - See [OAuth spec](https://oauth.net/2/) ``` *Correct: Title field "Requirements" provides the heading, content starts directly* **Example - With Subsections (✅ Also Correct)**: ```markdown ### Current Behavior The system currently... ### Proposed Changes - Change 1... - Change 2... ``` *Correct: Uses H3 for subsections, not H2* ## Integration with Workflow **Template Integration**: When using templates, they create standard sections automatically. Use add_section to supplement template-created sections with project-specific content. **Progressive Detail**: Start with high-level sections (Requirements, Architecture) and add implementation details as the task progresses. ## Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | entityType | string | Yes | - | Type of entity to attach this section to: 'PROJECT', 'TASK', or 'FEATURE' | | entityId | UUID string | Yes | - | ID of the project, task, or feature to add the section to (e.g., '550e8400-e29b-41d4-a716-446655440000') | | title | string | Yes | - | Section title (e.g., 'Requirements', 'Implementation Notes', 'Testing Plan') | | usageDescription | string | Yes | - | Description of how this section should be used by AI models or users | | content | string | Yes | - | The actual content of the section in the specified format | | contentFormat | string | No | "MARKDOWN" | Format of the content: 'MARKDOWN', 'PLAIN_TEXT', 'JSON', or 'CODE' | | ordinal | integer | Yes | - | Order position (0-based). Lower numbers appear first when ordered. | | tags | string | No | - | Comma-separated list of tags for categorization (e.g., 'documentation,frontend,api') | ## Response Format ### Success Response ```json { "success": true, "message": "Section added successfully", "data": { "section": { "id": "550e8400-e29b-41d4-a716-446655440000", "entityType": "TASK", "entityId": "661f9511-f30c-52e5-b827-557766551111", "title": "Implementation Steps", "contentFormat": "MARKDOWN", "ordinal": 1, "createdAt": "2025-05-10T14:30:00Z" } } } ``` ## Error Responses - RESOURCE_NOT_FOUND (404): When the specified task or feature doesn't exist ```json { "success": false, "message": "The specified task was not found", "error": { "code": "RESOURCE_NOT_FOUND" } } ``` - VALIDATION_ERROR (400): When provided parameters fail validation ```json { "success": false, "message": "Title is required", "error": { "code": "VALIDATION_ERROR" } } ``` - DATABASE_ERROR (500): When there's an issue storing the section in the database - INTERNAL_ERROR (500): For unexpected system errors during execution ## Usage Examples 1. Add a requirements section to a task: ```json { "entityType": "TASK", "entityId": "550e8400-e29b-41d4-a716-446655440000", "title": "Requirements", "usageDescription": "Key requirements that the implementation must satisfy", "content": "1. Must support OAuth2 authentication\\n2. Should handle token refresh\\n3. Needs rate limiting", "contentFormat": "MARKDOWN", "ordinal": 0, "tags": "requirements,security,api" } ``` 2. Add implementation notes to a feature: ```json { "entityType": "FEATURE", "entityId": "661e8511-f30c-41d4-a716-557788990000", "title": "Implementation Notes", "usageDescription": "Technical details on implementation approach", "content": "Use the AuthLib 2.0 library for OAuth implementation...", "contentFormat": "MARKDOWN", "ordinal": 1, "tags": "implementation,technical" } ``` 3. Add overview documentation to a project: ```json { "entityType": "PROJECT", "entityId": "772f9622-g41d-52e5-b827-668899101111", "title": "Project Overview", "usageDescription": "High-level overview of the project", "content": "This project aims to create a scalable infrastructure...", "contentFormat": "MARKDOWN", "ordinal": 0, "tags": "overview,documentation" } ``` 3. Add structured data as JSON: ```json { "entityType": "FEATURE", "entityId": "661e8511-f30c-41d4-a716-557788990000", "title": "API Endpoints", "usageDescription": "Definition of REST API endpoints", "content": "{\\"endpoints\\": [{\\"path\\": \\"/api/auth\\", \\"method\\": \\"POST\\"}]}", "contentFormat": "JSON", "ordinal": 0 } ``` 4. Add code sample: ```json { "entityType": "TASK", "entityId": "550e8400-e29b-41d4-a716-446655440000", "title": "Authentication Handler", "usageDescription": "Code for handling OAuth authentication", "content": "fun authenticateUser(credentials: Credentials): Result<User> {\n // Implementation\n}", "contentFormat": "CODE", "ordinal": 2 } ``` ## Common Section Types While you can create sections with any title, common section types include: - Requirements: Task or feature requirements (what needs to be done) - Implementation Notes: Technical details on how to implement - Testing Strategy: How to test the implementation - Reference Information: External links and resources - Architecture: Design and architecture details - Dependencies: Dependencies on other components ## Related Tools - `get_sections`: Retrieve sections for a task or feature - `update_section`: Modify an existing section - `delete_section`: Remove a section - `bulk_create_sections`: Create multiple sections at once (recommended when adding multiple sections) ## Efficiency Note For efficiency and better performance, when you need to add multiple sections to the same entity, use the `bulk_create_sections` tool instead. This reduces the number of database operations and network calls, resulting in faster execution, especially when dealing with multiple sections with shorter content. |
bulk_create_sections | Creates multiple sections in a single operation. ## Purpose This tool efficiently creates multiple sections for tasks, features, or projects in a single operation. PREFERRED over multiple `add_section` calls for efficiency and performance. ## When to Use bulk_create_sections **ALWAYS PREFER** for: - Creating initial section sets for new tasks/features (3+ sections) - Adding template-like section structures - Sections with shorter content (< 500 characters each) - Any scenario requiring multiple sections for the same entity **Performance Benefits**: - Single database transaction (atomic operation) - Reduced network overhead (one API call vs multiple) - Faster execution for multiple sections - Better error handling (all succeed or fail together) ## Common Section Creation Patterns **Standard Task Documentation Set**: ```json { "sections": [ { "entityType": "TASK", "entityId": "task-uuid", "title": "Requirements", "usageDescription": "Key requirements and acceptance criteria", "content": "[List specific requirements and success criteria]", "ordinal": 0, "tags": "requirements,core" }, { "entityType": "TASK", "entityId": "task-uuid", "title": "Technical Approach", "usageDescription": "Implementation strategy and architecture", "content": "[Describe technical approach and key decisions]", "ordinal": 1, "tags": "technical,architecture" }, { "entityType": "TASK", "entityId": "task-uuid", "title": "Testing Strategy", "usageDescription": "Testing approach and coverage requirements", "content": "[Define testing strategy and success criteria]", "ordinal": 2, "tags": "testing,quality" } ] } ``` **Feature Planning Documentation**: ```json { "sections": [ { "entityType": "FEATURE", "entityId": "feature-uuid", "title": "Business Context", "usageDescription": "Business value and user impact", "content": "[Explain business need and user benefits]", "ordinal": 0, "tags": "business,context" }, { "entityType": "FEATURE", "entityId": "feature-uuid", "title": "Feature Specification", "usageDescription": "Detailed feature requirements and behavior", "content": "[Define feature scope and detailed requirements]", "ordinal": 1, "tags": "requirements,specification" } ] } ``` ## Section Organization Best Practices **Ordinal Sequencing**: - Start with ordinal 0 for the first section - Use increments of 1 for tightly related sequences - Leave gaps (0, 10, 20) when you might insert sections later - Order logically: Context → Requirements → Implementation → Testing **Content Format Selection**: - **MARKDOWN**: Default for rich text, documentation, requirements - **PLAIN_TEXT**: Simple text without formatting needs - **JSON**: Structured data, API specs, configuration - **CODE**: Implementation examples, code snippets **Writing Markdown Content**: **CRITICAL - Section Title Handling**: - The `title` field becomes the section heading (rendered as ## H2 in markdown output) - **DO NOT** duplicate the section title as a heading in the `content` field - Content should start directly with the information, NOT with another heading - For subsections within content, use ### (H3) or lower headings **Markdown Formatting**: - Use subsection headings: `### Subsection` (H3 or lower, never H2) - Use lists: `- Item` or `1. Numbered` - Use emphasis: `**bold**` or `*italic*` - Use code: \`inline\` or \`\`\`kotlin code block\`\`\` - Use links: `[text](url)` **Example - WRONG (❌ Creates Duplicate Headings)**: ```markdown ## Requirements - **Must** support OAuth 2.0 ``` *Problem: Title field "Requirements" + content heading "## Requirements" = duplicate* **Example - CORRECT (✅ No Duplicate)**: ```markdown - **Must** support OAuth 2.0 - **Should** handle token refresh automatically - See [OAuth spec](https://oauth.net/2/) ``` *Correct: Title field "Requirements" provides the heading, content starts directly* **Example - With Subsections (✅ Also Correct)**: ```markdown ### Current Behavior The system currently... ### Proposed Changes - Change 1... - Change 2... ``` *Correct: Uses H3 for subsections, not H2* **Tagging Strategy**: - Use consistent tags across similar section types - Include functional area: "requirements", "testing", "architecture" - Add technical context: "api", "database", "frontend", "security" - Mark importance: "core", "optional", "critical" ## Integration with Templates **Templates vs Manual Sections**: - Templates provide standardized section structures automatically - Use bulk_create_sections to supplement template sections with project-specific content - Templates handle common patterns; bulk_create_sections handles custom needs **Post-Template Enhancement**: After applying templates, use bulk_create_sections to add: - Project-specific context sections - Additional technical details - Custom workflow or process sections - Domain-specific requirements or constraints ## Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | sections | array | Yes | - | Array of section objects to create | Each section object in the array must include: | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | entityType | string | Yes | - | Type of entity: 'PROJECT', 'TASK', or 'FEATURE' | | entityId | UUID string | Yes | - | ID of the project, task, or feature to add the section to | | title | string | Yes | - | Section title (e.g., 'Requirements', 'Implementation Notes') | | usageDescription | string | Yes | - | Description of how this section should be used | | content | string | Yes | - | The actual content of the section | | contentFormat | string | No | "MARKDOWN" | Format of the content: 'MARKDOWN', 'PLAIN_TEXT', 'JSON', or 'CODE' | | ordinal | integer | Yes | - | Order position (0-based). Lower numbers appear first. | | tags | string | No | - | Comma-separated list of tags for categorization | ## Response Format ### Success Response (All Sections Created) ```json { "success": true, "message": "3 sections created successfully", "data": { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "entityType": "task", "entityId": "661f9511-f30c-52e5-b827-557766551111", "title": "Requirements", "contentFormat": "markdown", "ordinal": 0, "createdAt": "2025-05-10T14:30:00Z" } ], "count": 3, "failed": 0 } } ``` ## Error Responses - VALIDATION_ERROR (400): When the input doesn't match the expected format or values are invalid - OPERATION_FAILED (500): When all sections fail to create - RESOURCE_NOT_FOUND (404): When an entity doesn't exist ## Usage Examples 1. Create multiple sections for a task: ```json { "sections": [ { "entityType": "TASK", "entityId": "550e8400-e29b-41d4-a716-446655440000", "title": "Requirements", "usageDescription": "Key requirements for implementation", "content": "1. Must support user authentication\n2. Should integrate with existing systems", "contentFormat": "MARKDOWN", "ordinal": 0, "tags": "requirements,core" }, { "entityType": "TASK", "entityId": "550e8400-e29b-41d4-a716-446655440000", "title": "Technical Approach", "usageDescription": "Implementation strategy and technical details", "content": "We'll use Spring Security for authentication and implement REST endpoints...", "contentFormat": "MARKDOWN", "ordinal": 1, "tags": "technical,implementation" }, { "entityType": "TASK", "entityId": "550e8400-e29b-41d4-a716-446655440000", "title": "Testing Strategy", "usageDescription": "Test approach and coverage requirements", "content": "Ensure 80% unit test coverage and implement integration tests for key flows", "contentFormat": "MARKDOWN", "ordinal": 2, "tags": "testing,quality" } ] } ``` 2. Create multiple sections for a project: ```json { "sections": [ { "entityType": "PROJECT", "entityId": "772f9622-g41d-52e5-b827-668899101111", "title": "Project Overview", "usageDescription": "High-level description of the project", "content": "This project aims to create a scalable infrastructure...", "contentFormat": "MARKDOWN", "ordinal": 0, "tags": "overview,documentation" }, { "entityType": "PROJECT", "entityId": "772f9622-g41d-52e5-b827-668899101111", "title": "Project Architecture", "usageDescription": "Technical architecture details", "content": "The project uses a modular architecture with the following components...", "contentFormat": "MARKDOWN", "ordinal": 1, "tags": "architecture,technical" } ] } ``` ## Performance Benefits Using `bulk_create_sections` instead of multiple calls to `add_section` offers significant advantages: 1. Reduced network overhead: Only one API call instead of multiple calls 2. Improved transaction efficiency: Database operations are batched 3. Faster execution: Creating multiple sections in parallel 4. Atomic operations: All sections succeed or useful error information is provided ## Common Section Combinations Typical section combinations for tasks include: 1. Requirements + Implementation Approach + Testing Strategy 2. Problem Statement + Solution Design + Acceptance Criteria 3. Context + Technical Details + References |
create_task | Creates a new task with the specified properties. ## Purpose Tasks are the primary work items in the system and can be organized into Features. Each task has basic metadata (title, status, etc.) and can have Sections for detailed content. ## Template Integration RECOMMENDED: Apply templates at creation time using templateIds parameter for consistent documentation structure. Use `list_templates` first to find appropriate templates. Template application creates standardized sections automatically: - Use single-item array for one template: ["template-uuid"] - Use multiple templates for comprehensive coverage: ["uuid1", "uuid2"] - Templates are applied in order, with later templates' sections appearing after earlier ones ## Best Practices - Use descriptive titles that clearly indicate the work to be done - Write comprehensive summaries with acceptance criteria when helpful - Set appropriate complexity ratings (1=trivial, 10=highly complex) - Use consistent tagging conventions (e.g., "task-type-feature", "task-type-bug") - Associate with features when the task is part of larger functionality - Apply templates that match the work type (implementation, testing, documentation) ## Entity Relationships - Tasks can belong to Features (use featureId to establish relationship) - Tasks can belong to Projects (use projectId for top-level organization) - Use dependencies to link related tasks (see create_dependency tool) ## Workflow Integration Tasks integrate with the complete project management workflow: 1. Start with get_overview to understand current work 2. Create task with appropriate templates and metadata 3. Use add_section or bulk_create_sections for additional content 4. Update status as work progresses (pending → in_progress → completed) 5. Create dependencies between related tasks Example successful response: { "success": true, "message": "Task created successfully with 2 template(s) applied, creating 6 section(s)", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "Implement OAuth Authentication API", "summary": "Create secure API endpoints for OAuth 2.0 authentication with JWT tokens", "status": "pending", "priority": "high", "complexity": 8, "createdAt": "2025-05-10T14:30:00Z", "modifiedAt": "2025-05-10T14:30:00Z", "featureId": "661e8511-f30c-41d4-a716-557788990000", "tags": ["task-type-feature", "oauth", "authentication", "api", "security"], "appliedTemplates": [ { "templateId": "technical-approach-uuid", "sectionsCreated": 3 }, { "templateId": "implementation-workflow-uuid", "sectionsCreated": 3 } ] } } For task creation patterns and best practices, see: task-orchestrator://guidelines/task-management Common error responses: - VALIDATION_ERROR: When provided parameters fail validation (empty title/summary, invalid UUIDs) - RESOURCE_NOT_FOUND: When specified featureId, projectId, or templateIds don't exist - DATABASE_ERROR: When there's an issue storing the task or applying templates - INTERNAL_ERROR: For unexpected system errors |
Manual installation
You can install the MCP server using:
Installation for