Cyanheads Atlas MCP Server

🚀 ATLAS Documentation

ATLAS is a task management tool built on the model context protocol, aiming to help teams efficiently organize and track project tasks. It offers functions for creating, updating, querying, and maintaining tasks, and supports batch operations and database optimization.

🚀 Quick Start

This section provides a high - level overview of how to start using ATLAS for task management.

✨ Features

• Comprehensive Task Management: Supports creating, updating, querying, and maintaining tasks, with batch operation capabilities.
• Database Optimization: Tools are available to optimize database performance and update statistics.
• Flexible Query Modes: Allows querying tasks by status or path patterns.

📦 Installation

1. Clone the repository: git clone https://github.com/atlas-project.git
2. Install dependencies: make install - deps
3. Compile the project: make build

💻 Usage Examples

Basic Usage

Task Creation

When creating a new task using create_task, you need to follow the path naming rules and ensure correct dependencies:

{
  "path": "project/backend", // Follow the path naming convention
  "name": "Backend Development",
  "type": "GROUP",
  "description": "Implement the core backend services",
  "metadata": {
    "priority": "high",
    "tags": ["backend", "api"]
  }
}

Task Update

When updating an existing task using update_task, pay attention to status changes and dependency verification:

{
  "path": "project/backend/api",
  "updates": {
    "status": "IN_PROGRESS", // Verify dependencies
    "dependencies": ["project/backend/database"],
    "metadata": {
      "progress": 50,
      "assignee": "Team Member"
    }
  }
}

Batch Task Operations

Perform atomic operations using bulk_task_operations to ensure consistency in multiple task changes:

{
  "operations": [
    {
      "type": "create",
      "path": "project/frontend",
      "data": {
        "name": "Frontend Development",
        "type": "GROUP"
      }
    },
    {
      "type": "update",
      "path": "project/backend",
      "data": {
        "status": "COMPLETED"
      }
    }
  ]
}

Task Query

Query by Status

Use get_tasks_by_status to retrieve tasks based on their execution status:

{
  "status": "IN_PROGRESS"
}

Query by Path Pattern

Search for tasks using wildcard patterns with get_tasks_by_path:

{
  "pattern": "project/backend/**"
}

Database Maintenance

Database Optimization

Use the vacuum_database tool to optimize database performance and update statistics:

{
  "analyze": true // Update statistics simultaneously
}

Relationship Repair

Use repair_relationships to fix inconsistencies in task relationships:

{
  "dryRun": true, // Preview changes
  "pathPattern": "project/**"
}

Clear All Tasks

Completely reset the database using clear_all_tasks (confirmation required):

{
  "confirm": true
}

📚 Documentation

Best Practices

Task Management

• Use descriptive path names to reflect the hierarchy.
• Set appropriate task types (GROUP, TASK).
• Include detailed descriptions to provide context.
• Use metadata to store custom fields.
• Handle dependencies with caution.
• Maintain clean parent - child relationships.

Path Naming

• Use letters, numbers, hyphens, and underscores.
• Keep paths short and meaningful.
• Start paths with a valid project name.
• Avoid using special characters.
• Use forward slashes for separation.
• Limit the hierarchy to no more than 5 levels.

Performance Optimization

• Use batch operations to handle multiple changes.
• Ensure query patterns are concise and efficient.
• Regularly perform database maintenance tasks.
• Monitor system performance metrics.

Known Issues

1. Insufficient Path Depth Verification: The current version does not fully verify path depth, which may lead to complex management of deeply nested tasks.
2. Cascade Delete Limitation: Cascade delete functionality is not implemented. When manually deleting a parent task, you need to handle child tasks with caution.

Development Guide

Project Structure

• src/main.c: Main program entry point.
• include/atlas.h: Core library interface.
• lib/: Third - party dependency libraries.
• doc/: Documentation and examples.

Contribution Guide

• Submit an ISSUE to report problems or suggestions.
• Send a PR to fix bugs or add features.
• Participate in community discussions.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for specific terms.

With the above tools and best practices, ATLAS helps teams efficiently manage tasks in complex projects and improve collaboration efficiency.