📌Overview

Purpose: ATLAS aims to streamline task management for LLM agents by providing an efficient system for organizing and automating project tasks and knowledge.

Overview: ATLAS is built on the Model Context Protocol (MCP) to facilitate seamless interaction between LLMs and project management tasks. It adopts a three-tier architecture that organizes details into Projects, Tasks, and Knowledge components, allowing for comprehensive management of project workflows and dependencies.

Key Features:

Project Management: Provides tools for tracking project metadata, handling dependencies, and managing project statuses and content through bulk operations.
Task Management: Enables the creation, tracking, and updating of tasks with lifecycle management, prioritization, categorization, and dependency tracking to ensure structured workflows.
Knowledge Management: Features a searchable repository for project-related information, organized by domain and tags, supporting citation tracking for knowledge items.
Graph Database Integration: Utilizes Neo4j for robust data integrity, advanced search capabilities, and optimized query performance, ensuring scalability and efficient management of relationships.
Unified Search: Offers cross-entity search across projects, tasks, and knowledge for easily retrieving relevant information based on various criteria and filtering options.

ATLAS: Task Management System

ATLAS (Adaptive Task & Logic Automation System) is a project, knowledge, and task management system for LLM Agents.

Architecture

ATLAS is built on a three-tier architecture:

                  +------------------------------------------+
                  |                PROJECT                   |
                  |------------------------------------------|
                  | id: string                               |
                  | name: string                             |
                  | description: string                      |
                  | status: string                           |
                  | urls?: Array<{title: string, url: string}>|
                  | completionRequirements: string           |
                  | outputFormat: string                     |
                  | taskType: string                         |
                  | createdAt: string                        |
                  | updatedAt: string                        |
                  +----------------+-------------------------+
                            |                    |
                            |                    |
                            v                    v
+----------------------------------+ +----------------------------------+
|               TASK               | |            KNOWLEDGE             |
|----------------------------------| |----------------------------------|
| id: string                       | | id: string                       |
| projectId: string                | | projectId: string                |
| title: string                   | | text: string                     |
| description: string              | | tags?: string[]                  |
| priority: string                | | domain: string                   |
| status: string                  | | citations?: string[]             |
| assignedTo?: string             | | createdAt: string                |
| urls?: Array<{title: string,     | |                                  |
|   url: string}>                 | | updatedAt: string                |
| tags?: string[]                 | |                                  |
| completionRequirements: string  | |                                  |
| outputFormat: string            | |                                  |
| taskType: string                | |                                  |
| createdAt: string               | |                                  |
| updatedAt: string               | |                                  |
+----------------------------------+ +----------------------------------+

Implemented as a Model Context Protocol (MCP) server, ATLAS allows LLM agents to manage projects, tasks, and knowledge items.

Version Note: Version 1.5.4 uses SQLite. Versions 2.0+ use Neo4j, requiring:

Self-hosting with Docker (docker-compose included)

Neo4j AuraDB cloud service: https://neo4j.com/product/auradb/

Version 2.5.0 introduces the 3-node system (Projects, Tasks, Knowledge).

Overview
Features
Installation
Configuration
Project Structure
Tools
Resources
Database Backup and Restore
Examples
Contributing
License

Overview

ATLAS implements the Model Context Protocol (MCP) to enable standardized communication between LLMs and external systems.

Clients: Claude Desktop, IDEs, other MCP-compatible clients
Servers: Manage projects, tasks, and knowledge
LLM Agents: Use server's management capabilities

System Integration

Project-Task Relationship: Projects contain tasks representing actionable steps.
Knowledge Integration: Projects and tasks can include knowledge items.
Dependency Management: Supports dependencies for workflows.
Unified Search: Cross-entity searching for projects, tasks, knowledge.

Features

Project Management

Comprehensive tracking of metadata, statuses, content (notes, links).
Validates and tracks dependencies.

Task Management

Full lifecycle management of tasks.
Prioritization, categorization with tags.
Dependency tracking.

Knowledge Management

Searchable repository.
Domain categorization and tags.
Citation support.

Graph Database Integration

Leverages Neo4j for native relationship management.
Supports advanced searches, fuzzy matching, high performance.

Unified Search

Cross-entity search (projects, tasks, knowledge).
Case-insensitive, fuzzy, and filtering options.

Installation

git clone https://github.com/cyanheads/atlas-mcp-server.git
cd atlas-mcp-server
npm install
docker-compose up -d   # Start Neo4j using Docker
npm run build

Configuration

Environment Variables

Create a .env file from .env.example:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password2

LOG_LEVEL=info
NODE_ENV=development

MCP Client Settings

Add to your MCP client:

{
  "mcpServers": {
    "atlas": {
      "command": "node",
      "args": ["/path/to/atlas-mcp-server/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password2",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Project Structure

src/
├── config/          # Configuration management
├── index.ts         # Main server entry point
├── mcp/             # MCP server implementation
│   ├── resources/   # MCP resource handlers
│   └── tools/       # MCP tool handlers
├── services/        # Core application services
│   └── neo4j/       # Neo4j database services
├── types/           # TypeScript type definitions
└── utils/           # Utilities

ID generation logic is mainly in src/services/neo4j/helpers.ts.

Tools

ATLAS provides tools callable via MCP for project, task, knowledge, search, research, and database operations.

Project Operations

Tool Name	Description	Key Arguments
atlas_project_create	Create projects (single/bulk)	mode, project details (name, description, status, urls, completionRequirements, dependencies, outputFormat, taskType), responseFormat (optional)
atlas_project_list	List projects	mode, id (for details), filters (status, taskType), pagination, includes (knowledge, tasks), responseFormat (optional)
atlas_project_update	Update projects (single/bulk)	mode, id, updates, responseFormat (optional)
atlas_project_delete	Delete projects (single/bulk)	mode, id or projectIds, responseFormat (optional)

Task Operations

Tool Name	Description	Key Arguments
atlas_task_create	Create tasks (single/bulk)	mode, projectId, task details (title, description, priority, status, assignedTo, tags, completionRequirements, dependencies, outputFormat, taskType), responseFormat (optional)
atlas_task_update	Update tasks (single/bulk)	mode, id, updates, responseFormat (optional)
atlas_task_delete	Delete tasks (single/bulk)	mode, id or taskIds, responseFormat (optional)
atlas_task_list	List tasks for project	projectId (required), filters (status, assignedTo, priority, tags, taskType), sorting, pagination, responseFormat (optional)

Knowledge Operations

Tool Name	Description	Key Arguments
atlas_knowledge_add	Add knowledge items (single/bulk)	mode, projectId, knowledge details (text, tags, domain, citations), responseFormat (optional)
atlas_knowledge_delete	Delete knowledge (single/bulk)	mode, id or knowledgeIds, responseFormat (optional)
atlas_knowledge_list	List knowledge for project	projectId (required), filters (tags, domain, search), pagination, responseFormat (optional)

Search Operations

Tool Name	Description	Key Arguments
atlas_unified_search	Unified search across entities	value (search term), property (optional), filters (entityTypes, taskType), options (caseInsensitive, fuzzy), pagination, responseFormat (optional)

Research Operations

Tool Name	Description	Key Arguments
atlas_deep_research	Initiate structured deep research within knowledge base	projectId, researchTopic, researchGoal, scopeDefinition (optional), subTopics (array), researchDomain (optional), initialTags (optional), planNodeId (optional), responseFormat (optional)

Database Operations

Tool Name	Description	Key Arguments
atlas_database_clean	Destructive: Resets database, removes all data	acknowledgement (true to confirm), responseFormat (optional)

Resources

ATLAS exposes data via MCP resource endpoints.

Direct Resources

Resource Name	Description
atlas://projects	List all projects with pagination
atlas://tasks	List all tasks with pagination and filtering
atlas://knowledge	List all knowledge items with pagination and filtering

Resource Templates

Resource Name	Description
atlas://projects/{projectId}	Get single project by ID
atlas://tasks/{taskId}	Get single task by ID
atlas://projects/{projectId}/tasks	Get all tasks of a project
atlas://knowledge/{knowledgeId}	Get single knowledge item by ID
atlas://projects/{projectId}/knowledge	Get all knowledge items of a project

Database Backup and Restore

ATLAS supports backing up and restoring Neo4j database content.

Notes

Automatic backups have been removed due to inefficiency.
Use manual backup/restore commands.

Backup Process

Exports all Project, Task, and Knowledge nodes with relationships as JSON files.
Creates timestamped backup directories (e.g., atlas-backup-YYYYMMDDHHMMSS) in ./atlas-backups/ by default.
Trigger manual backup:

npm run db:backup

Restore Process

Completely clears current Neo4j database before importing.
Warning: restoring overwrites all current data.
Restore from backup:

npm run db:import <path_to_backup_directory>

Relationships are recreated based on id properties of nodes; ensure IDs are consistent.

Examples

The examples/ directory provides practical demonstrations:

Backup Example: Shows structure and format of backup JSON files created by npm run db:backup.
Deep Research Example: Demonstrates the output of atlas_deep_research tool, including markdown research plans and raw JSON export.

Contributing

Fork the repository
Create a feature branch
Commit changes with descriptive messages
Push branch
Create a Pull Request

Report bugs and feature requests via issues.

License

Apache License 2.0

Built with the Model Context Protocol

atlas-mcp-server