Task orchestrator MCP Server | Docker MCP Catalog

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
`bulk_update_tasks`	Updates multiple tasks in a single operation. ⚡ EFFICIENCY: This tool reduces token usage by 70-90% compared to individual updates! ## Purpose Efficiently update multiple tasks in a single API call with atomic transaction guarantees. This tool is CRITICAL for token optimization when working with multiple tasks. ## When to Use bulk_update_tasks ALWAYS PREFER for multi-task operations: - Sprint completion: Mark 10+ tasks as completed (86% token savings) - Feature migration: Move tasks between features (78-91% savings) - Priority adjustments: Bulk reprioritization (80-92% savings) - Status updates: Bulk workflow transitions (70-90% savings) Performance Benefits: - Single network round-trip instead of N calls - Atomic database transaction (all succeed or detailed failures) - 70-90% token reduction for typical scenarios - Consistent state across all task updates ## Token Savings Examples Sprint Completion (10 tasks): - Individual updates: ~2,500 tokens - Bulk update: ~350 tokens - Savings: 86% (2,150 tokens) Feature Reassignment (25 tasks): - Individual updates: ~7,000 tokens - Bulk update: ~650 tokens - Savings: 91% (6,350 tokens) Priority Adjustment (50 tasks): - Individual updates: ~12,500 tokens - Bulk update: ~1,000 tokens - Savings: 92% (11,500 tokens) ## Partial Updates ⚡ CRITICAL: Only send fields you're changing! Each task only needs `id` + changed fields. ❌ INEFFICIENT (sends unchanged data): ```json { "tasks": [ { "id": "task-uuid", "title": "Long unchanged title...", "summary": "Long unchanged summary...", "status": "completed", "priority": "medium", "complexity": 5, "tags": "unchanged,tags" } ] } ``` ✅ EFFICIENT (only changed field): ```json { "tasks": [ {"id": "task-uuid", "status": "completed"} ] } ``` ## Common Use Cases 1. Sprint Completion: ```json { "tasks": [ {"id": "task-1-uuid", "status": "completed"}, {"id": "task-2-uuid", "status": "completed"}, {"id": "task-3-uuid", "status": "completed"} ] } ``` 2. Emergency Reprioritization: ```json { "tasks": [ {"id": "critical-1", "priority": "high", "status": "in_progress"}, {"id": "critical-2", "priority": "high"}, {"id": "normal-1", "priority": "low", "status": "deferred"} ] } ``` 3. Feature Migration: ```json { "tasks": [ {"id": "task-a", "featureId": "new-feature-uuid"}, {"id": "task-b", "featureId": "new-feature-uuid"}, {"id": "task-c", "featureId": "new-feature-uuid"} ] } ``` 4. Mixed Updates: ```json { "tasks": [ {"id": "task-1", "status": "in_progress", "priority": "high"}, {"id": "task-2", "complexity": 8}, {"id": "task-3", "tags": "urgent,backend"} ] } ``` ## Parameters \| Parameter \| Type \| Required \| Description \| \|-----------\|------\|----------\|-------------\| \| tasks \| array \| Yes \| Array of task update objects \| Each task object: \| Field \| Type \| Required \| Description \| \|-------\|------\|----------\|-------------\| \| id \| UUID \| Yes \| Task identifier \| \| title \| string \| No \| New title \| \| description \| string \| No \| New summary/description \| \| status \| enum \| No \| New status (pending, in_progress, completed, cancelled, deferred) \| \| priority \| enum \| No \| New priority (high, medium, low) \| \| complexity \| integer \| No \| New complexity (1-10) \| \| featureId \| UUID \| No \| New feature association \| \| tags \| string \| No \| New comma-separated tags \| ## Response Format ### Success Response ```json { "success": true, "message": "5 tasks updated successfully", "data": { "updated": 5, "failed": 0, "items": [ { "id": "task-uuid", "status": "completed", "modifiedAt": "2025-10-12T18:45:00Z" } ] } } ``` ### Partial Failure Response ```json { "success": true, "message": "3 tasks updated successfully, 1 failed", "data": { "updated": 3, "failed": 1, "items": [ {"id": "task-1", "status": "completed", "modifiedAt": "2025-10-12T18:45:00Z"} ], "failures": [ { "index": 3, "id": "bad-uuid", "error": { "code": "RESOURCE_NOT_FOUND", "details": "Task not found: bad-uuid" } } ] } } ``` ## Validation Rules 1. Array: At least one task required, maximum 100 tasks 2. Per Task: `id` required, at least one update field 3. UUIDs: Valid format for `id` and `featureId` 4. Enums: Valid values for `status` and `priority` 5. Range: `complexity` must be 1-10 ## Error Responses - VALIDATION_ERROR (400): Invalid input format or values - RESOURCE_NOT_FOUND (404): One or more tasks don't exist - OPERATION_FAILED (500): All tasks failed to update - INTERNAL_ERROR (500): Unexpected system error ## Performance Notes - Network: 1 round-trip vs N round-trips (80-99% reduction) - Database: Single atomic transaction - Tokens: 70-92% reduction vs individual updates - Response: Minimal format (id, status, modifiedAt only) ## Comparison with Individual Updates \| Scenario \| Tasks \| Individual \| Bulk \| Savings \| \|----------\|-------\|------------\|------\|---------\| \| Sprint completion \| 10 \| 2,500 tokens \| 350 tokens \| 86% \| \| Feature migration \| 25 \| 7,000 tokens \| 650 tokens \| 91% \| \| Priority adjustment \| 50 \| 12,500 tokens \| 1,000 tokens \| 92% \| ## Best Practices 1. Use for 2+ tasks: Single task? Use `update_task` instead 2. Partial updates only: Only send fields that changed 3. Batch related changes: Group related updates (same status, same feature) 4. Check failures: Review `failures` array for partial success 5. Limit batch size: Keep under 100 tasks per request ## Related Tools - `update_task`: Update single task (use for 1 task) - `bulk_create_sections`: Efficient section creation - `bulk_update_sections`: Efficient section updates - `get_overview`: Check current state before bulk updates
`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

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

bulk_update_tasks

Updates multiple tasks in a single operation. ⚡ **EFFICIENCY**: This tool reduces token usage by 70-90% compared to individual updates! ## Purpose Efficiently update multiple tasks in a single API call with atomic transaction guarantees. This tool is **CRITICAL for token optimization** when working with multiple tasks. ## When to Use bulk_update_tasks **ALWAYS PREFER** for multi-task operations: - Sprint completion: Mark 10+ tasks as completed (86% token savings) - Feature migration: Move tasks between features (78-91% savings) - Priority adjustments: Bulk reprioritization (80-92% savings) - Status updates: Bulk workflow transitions (70-90% savings) **Performance Benefits**: - Single network round-trip instead of N calls - Atomic database transaction (all succeed or detailed failures) - 70-90% token reduction for typical scenarios - Consistent state across all task updates ## Token Savings Examples **Sprint Completion (10 tasks)**: - Individual updates: ~2,500 tokens - Bulk update: ~350 tokens - **Savings: 86%** (2,150 tokens) **Feature Reassignment (25 tasks)**: - Individual updates: ~7,000 tokens - Bulk update: ~650 tokens - **Savings: 91%** (6,350 tokens) **Priority Adjustment (50 tasks)**: - Individual updates: ~12,500 tokens - Bulk update: ~1,000 tokens - **Savings: 92%** (11,500 tokens) ## Partial Updates ⚡ **CRITICAL**: Only send fields you're changing! Each task only needs `id` + changed fields. ❌ **INEFFICIENT** (sends unchanged data): ```json { "tasks": [ { "id": "task-uuid", "title": "Long unchanged title...", "summary": "Long unchanged summary...", "status": "completed", "priority": "medium", "complexity": 5, "tags": "unchanged,tags" } ] } ``` ✅ **EFFICIENT** (only changed field): ```json { "tasks": [ {"id": "task-uuid", "status": "completed"} ] } ``` ## Common Use Cases **1. Sprint Completion**: ```json { "tasks": [ {"id": "task-1-uuid", "status": "completed"}, {"id": "task-2-uuid", "status": "completed"}, {"id": "task-3-uuid", "status": "completed"} ] } ``` **2. Emergency Reprioritization**: ```json { "tasks": [ {"id": "critical-1", "priority": "high", "status": "in_progress"}, {"id": "critical-2", "priority": "high"}, {"id": "normal-1", "priority": "low", "status": "deferred"} ] } ``` **3. Feature Migration**: ```json { "tasks": [ {"id": "task-a", "featureId": "new-feature-uuid"}, {"id": "task-b", "featureId": "new-feature-uuid"}, {"id": "task-c", "featureId": "new-feature-uuid"} ] } ``` **4. Mixed Updates**: ```json { "tasks": [ {"id": "task-1", "status": "in_progress", "priority": "high"}, {"id": "task-2", "complexity": 8}, {"id": "task-3", "tags": "urgent,backend"} ] } ``` ## Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tasks | array | Yes | Array of task update objects | Each task object: | Field | Type | Required | Description | |-------|------|----------|-------------| | id | UUID | Yes | Task identifier | | title | string | No | New title | | description | string | No | New summary/description | | status | enum | No | New status (pending, in_progress, completed, cancelled, deferred) | | priority | enum | No | New priority (high, medium, low) | | complexity | integer | No | New complexity (1-10) | | featureId | UUID | No | New feature association | | tags | string | No | New comma-separated tags | ## Response Format ### Success Response ```json { "success": true, "message": "5 tasks updated successfully", "data": { "updated": 5, "failed": 0, "items": [ { "id": "task-uuid", "status": "completed", "modifiedAt": "2025-10-12T18:45:00Z" } ] } } ``` ### Partial Failure Response ```json { "success": true, "message": "3 tasks updated successfully, 1 failed", "data": { "updated": 3, "failed": 1, "items": [ {"id": "task-1", "status": "completed", "modifiedAt": "2025-10-12T18:45:00Z"} ], "failures": [ { "index": 3, "id": "bad-uuid", "error": { "code": "RESOURCE_NOT_FOUND", "details": "Task not found: bad-uuid" } } ] } } ``` ## Validation Rules 1. **Array**: At least one task required, maximum 100 tasks 2. **Per Task**: `id` required, at least one update field 3. **UUIDs**: Valid format for `id` and `featureId` 4. **Enums**: Valid values for `status` and `priority` 5. **Range**: `complexity` must be 1-10 ## Error Responses - VALIDATION_ERROR (400): Invalid input format or values - RESOURCE_NOT_FOUND (404): One or more tasks don't exist - OPERATION_FAILED (500): All tasks failed to update - INTERNAL_ERROR (500): Unexpected system error ## Performance Notes - **Network**: 1 round-trip vs N round-trips (80-99% reduction) - **Database**: Single atomic transaction - **Tokens**: 70-92% reduction vs individual updates - **Response**: Minimal format (id, status, modifiedAt only) ## Comparison with Individual Updates | Scenario | Tasks | Individual | Bulk | Savings | |----------|-------|------------|------|---------| | Sprint completion | 10 | 2,500 tokens | 350 tokens | 86% | | Feature migration | 25 | 7,000 tokens | 650 tokens | 91% | | Priority adjustment | 50 | 12,500 tokens | 1,000 tokens | 92% | ## Best Practices 1. **Use for 2+ tasks**: Single task? Use `update_task` instead 2. **Partial updates only**: Only send fields that changed 3. **Batch related changes**: Group related updates (same status, same feature) 4. **Check failures**: Review `failures` array for partial success 5. **Limit batch size**: Keep under 100 tasks per request ## Related Tools - `update_task`: Update single task (use for 1 task) - `bulk_create_sections`: Efficient section creation - `bulk_update_sections`: Efficient section updates - `get_overview`: Check current state before bulk updates

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

Task orchestrator

Related servers

Dappier Remote MCP Server

Elevenlabs MCP

Hugging Face

LLM Text