ATLAS: Sistema de gestión de tareas

ATLAS (Adaptive Task & Logic Automation System) es un sistema de gestión de tareas para agentes LLM.

Construido sobre una arquitectura de tres niveles:

                  +------------------------------------------+
                  |                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                | |                                  |
+----------------------------------+ +----------------------------------+

Implementado como un servidor de Protocolo de Contexto de Modelo (MCP), ATLAS permite a los agentes LLM interactuar con la base de datos de gestión de proyectos, lo que permite gestionar proyectos, tareas y elementos de conocimiento.

Nota importante sobre la versión : La versión 1.5.4 es la última que utiliza SQLite como base de datos. A partir de la versión 2.0, se ha reescrito completamente para usar Neo4j, lo que requiere:
Autohospedaje mediante Docker (docker-compose incluido en el repositorio)
Uso del servicio en la nube AuraDB de Neo4j: https://neo4j.com/product/auradb/
La versión 2.5.0 introduce un nuevo sistema de 3 nodos (Proyectos, Tareas, Conocimiento) que reemplaza la estructura anterior.

Tabla de contenido

Descripción general
Características
Instalación
Configuración
Estructura del proyecto
Herramientas
Recursos
Copia de seguridad y restauración de bases de datos
Ejemplos
Contribuyendo
Licencia

Descripción general

ATLAS implementa el Protocolo de Contexto de Modelo (MCP), lo que permite una comunicación estandarizada entre LLM y sistemas externos a través de:

Clientes : Claude Desktop, IDE y otros clientes compatibles con MCP
Servidores : herramientas y recursos para la gestión de proyectos, tareas y conocimientos
Agentes LLM : modelos de IA que aprovechan las capacidades de gestión del servidor

Integración de sistemas

La Plataforma Atlas integra estos componentes en un sistema cohesivo:

Relación proyecto-tarea : Los proyectos contienen tareas que representan pasos prácticos necesarios para alcanzar los objetivos del proyecto. Las tareas heredan el contexto de su proyecto principal y, al mismo tiempo, proporcionan un seguimiento detallado de cada elemento de trabajo.
Integración de conocimientos : tanto los proyectos como las tareas pueden enriquecerse con elementos de conocimiento, proporcionando a los miembros del equipo la información y el contexto necesarios.
Gestión de dependencias : tanto los proyectos como las tareas admiten relaciones de dependencia, lo que permite flujos de trabajo complejos con prerrequisitos y requisitos de ejecución secuencial.
Búsqueda unificada : la plataforma ofrece capacidades de búsqueda entre entidades, lo que permite a los usuarios encontrar proyectos, tareas o conocimientos relevantes según diversos criterios.

Características

Gestión de proyectos

Seguimiento integral: administre metadatos del proyecto, estados y contenido enriquecido (notas, enlaces, etc.) con soporte integrado para operaciones masivas.
Manejo de dependencias y relaciones: valide y realice un seguimiento automático de las dependencias entre proyectos.

Gestión de tareas

Gestión del ciclo de vida de las tareas: cree, realice un seguimiento y actualice tareas durante todo su ciclo de vida.
Priorización y categorización: asigne niveles de prioridad y categorice las tareas con etiquetas para una mejor organización.
Seguimiento de dependencias: establezca dependencias de tareas para crear flujos de trabajo estructurados.

Gestión del conocimiento

Repositorio de conocimiento estructurado: mantener un repositorio de búsqueda de información relacionada con el proyecto.
Categorización de dominios: organice el conocimiento por dominio y etiquetas para una fácil recuperación.
Soporte de citas: realice un seguimiento de las fuentes y referencias de elementos de conocimiento.

Integración de bases de datos gráficas

Gestión de relaciones nativas: aproveche las transacciones compatibles con ACID y las consultas optimizadas de Neo4j para lograr una integridad de datos sólida.
Búsqueda avanzada y escalabilidad: realice búsquedas basadas en propiedades con coincidencias aproximadas y comodines manteniendo un alto rendimiento.

Búsqueda unificada

Búsqueda entre entidades: encuentre proyectos, tareas o conocimientos relevantes según el contenido, los metadatos o las relaciones.
Opciones de consulta flexibles: compatibilidad con opciones de filtrado avanzado, difuso y sin distinción entre mayúsculas y minúsculas.

Instalación

Clonar el repositorio:

git clone https://github.com/cyanheads/atlas-mcp-server.git
cd atlas-mcp-server

Instalar dependencias:

npm install

Configurar Neo4j:

# Start Neo4j using Docker
docker-compose up -d

Construir el proyecto:

npm run build

Configuración

Variables de entorno

Cree un archivo .env basado en .env.example :

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password2

# Application Configuration
LOG_LEVEL=info # debug, info, warn, error
NODE_ENV=development # development, production

Configuración del cliente MCP

Añade a la configuración de tu cliente MCP:

{
  "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"
      }
    }
  }
}

Estructura del proyecto

El código base sigue una estructura modular:

src/
├── config/          # Configuration management (index.ts)
├── index.ts         # Main server entry point
├── mcp/             # MCP server implementation (server.ts)
│   ├── resources/   # MCP resource handlers (index.ts, types.ts, knowledge/, projects/, tasks/)
│   └── tools/       # MCP tool handlers (individual tool directories)
├── services/        # Core application services
│   └── neo4j/       # Neo4j database services (index.ts, driver.ts, backupRestoreService.ts, etc.)
├── types/           # Shared TypeScript type definitions (errors.ts, mcp.ts, tool.ts)
└── utils/           # Utility functions (logger.ts, errorHandler.ts, etc.)

Nota: La lógica de generación de ID se encuentra principalmente en src/services/neo4j/helpers.ts .

Herramientas

ATLAS proporciona un conjunto integral de herramientas para la gestión de proyectos, tareas y conocimientos, a las que se puede acceder a través del Protocolo de Contexto de Modelo.

Operaciones del proyecto

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_project_create`	Crea nuevos proyectos (individuales/masivos).	`mode` ('único'/'masivo'), detalles del proyecto ( `name` , `description` , `status` , `urls` , `completionRequirements` , `dependencies` , `outputFormat` , `taskType` ), `responseFormat` ('formateado'/'json', opcional).
`atlas_project_list`	Enumera proyectos (todos/detalles).	`mode` ('todos'/'detalles'), `id` (para detalles), filtros ( `status` , `taskType` ), paginación ( `page` , `limit` ), incluye ( `includeKnowledge` , `includeTasks` ), `responseFormat` ('formateado'/'json', opcional).
`atlas_project_update`	Actualiza proyectos existentes (individuales/masivos).	`mode` ('single'/'bulk'), `id` , objeto `updates` , `responseFormat` ('formatted'/'json', opcional). El modo masivo usa la matriz `projects` .
`atlas_project_delete`	Elimina proyectos (individuales/en masa).	`mode` ('único'/'masivo'), `id` (único) o matriz `projectIds` (masivo), `responseFormat` ('formateado'/'json', opcional).

Operaciones de tareas

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_task_create`	Crea nuevas tareas (individuales/masivas).	`mode` ('único'/'masivo'), `projectId` , detalles de la tarea ( `title` , `description` , `priority` , `status` , `assignedTo` , `tags` , `completionRequirements` , `dependencies` , `outputFormat` , `taskType` ), `responseFormat` ('formateado'/'json', opcional).
`atlas_task_update`	Actualiza tareas existentes (individuales/masivas).	`mode` ('single'/'bulk'), `id` , objeto `updates` , `responseFormat` ('formatted'/'json', opcional). El modo masivo usa la matriz `tasks` .
`atlas_task_delete`	Elimina tareas (individuales/masivas).	`mode` ('único'/'masivo'), `id` (único) o matriz `taskIds` (masivo), `responseFormat` ('formateado'/'json', opcional).
`atlas_task_list`	Enumera las tareas para un proyecto específico.	`projectId` (obligatorio), filtros ( `status` , `assignedTo` , `priority` , `tags` , `taskType` ), clasificación ( `sortBy` , `sortDirection` ), paginación ( `page` , `limit` ), `responseFormat` ('formateado'/'json', opcional).

Operaciones de conocimiento

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_knowledge_add`	Agrega nuevos elementos de conocimiento (individuales/en masa).	`mode` ('single'/'bulk'), `projectId` , detalles de conocimiento ( `text` , `tags` , `domain` , `citations` ), `responseFormat` ('formateado'/'json', opcional). El modo masivo usa una matriz `knowledge` .
`atlas_knowledge_delete`	Elimina elementos de conocimiento (individuales o en masa).	`mode` ('único'/'masivo'), `id` (único) o matriz `knowledgeIds` (masivo), `responseFormat` ('formateado'/'json', opcional).
`atlas_knowledge_list`	Enumera elementos de conocimiento para un proyecto específico.	`projectId` (obligatorio), filtros ( `tags` , `domain` , `search` ), paginación ( `page` , `limit` ), `responseFormat` ('formateado'/'json', opcional).

Operaciones de búsqueda

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_unified_search`	Realiza una búsqueda unificada entre entidades.	`value` (término de búsqueda), `property` (opcional), filtros ( `entityTypes` , `taskType` ), opciones ( `caseInsensitive` , `fuzzy` ), paginación ( `page` , `limit` ), `responseFormat` ('formatted'/'json', opcional).

Operaciones de investigación

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_deep_research`	Inicia un proceso de investigación profunda estructurado mediante la creación de un plan jerárquico dentro de la base de conocimiento del Atlas.	`projectId` (obligatorio), `researchTopic` (obligatorio), `researchGoal` (obligatorio), `scopeDefinition` (opcional), `subTopics` (matriz obligatoria con preguntas y consultas de búsqueda), `researchDomain` (opcional), `initialTags` (opcional), `planNodeId` (opcional), `responseFormat` (opcional).

Operaciones de base de datos

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_database_clean`	Destructivo: restablece completamente la base de datos, eliminando todos los proyectos, tareas y conocimientos.	`acknowledgement` (debe establecerse como `true` para confirmar), `responseFormat` ('formatted'/'json', opcional).

Recursos

ATLAS expone datos de proyectos, tareas y conocimientos a través de puntos finales de recursos MCP estándar.

Recursos directos

Nombre del recurso	Descripción
`atlas://projects`	Lista de todos los proyectos en la plataforma Atlas con soporte de paginación.
`atlas://tasks`	Listado de todas las tareas en la plataforma Atlas con soporte de paginación y filtrado.
`atlas://knowledge`	Lista de todos los elementos de conocimiento en la plataforma Atlas con soporte de paginación y filtrado.

Plantillas de recursos

Nombre del recurso	Descripción
`atlas://projects/{projectId}`	Recupera un solo proyecto por su identificador único ( `projectId` ).
`atlas://tasks/{taskId}`	Recupera una sola tarea por su identificador único ( `taskId` ).
`atlas://projects/{projectId}/tasks`	Recupera todas las tareas que pertenecen a un proyecto específico ( `projectId` ).
`atlas://knowledge/{knowledgeId}`	Recupera un único elemento de conocimiento mediante su identificador único ( `knowledgeId` ).
`atlas://projects/{projectId}/knowledge`	Recupera todos los elementos de conocimiento que pertenecen a un proyecto específico ( `projectId` ).

Copia de seguridad y restauración de bases de datos

ATLAS ofrece funciones para realizar copias de seguridad y restaurar el contenido de la base de datos de Neo4j. La lógica principal reside en src/services/neo4j/backupRestoreService.ts .

Copias de seguridad automáticas (Nota)

Importante: La función de copia de seguridad automática se ha eliminado debido a su ineficiencia. La llamada a triggerBackgroundBackup en src/services/neo4j/driver.ts está comentada con una nota que indica que se ha eliminado. Utilice el proceso de copia de seguridad manual que se describe a continuación para proteger sus datos.

Proceso de copia de seguridad

Mecanismo : El proceso de copia de seguridad exporta todos los nodos Project , Task y Knowledge , junto con sus relaciones, en archivos JSON separados.
Salida : Cada copia de seguridad crea un directorio con marca de tiempo (p. ej., atlas-backup-YYYYMMDDHHMMSS ) dentro de la ruta de copia de seguridad configurada (predeterminado: ./atlas-backups/ ). Este directorio contiene projects.json , tasks.json , knowledge.json y relationships.json .
Copia de seguridad manual : puede activar una copia de seguridad manual mediante el script proporcionado:
npm run db:backup
Este comando ejecuta scripts/db-backup.ts , que llama a la función exportDatabase .

Proceso de restauración

Mecanismo : El proceso de restauración primero borra por completo la base de datos de Neo4j existente. A continuación, importa los nodos y las relaciones desde los archivos JSON ubicados en el directorio de respaldo especificado.
Advertencia : Restaurar desde una copia de seguridad es una operación destructiva. Sobrescribirá todos los datos actuales de su base de datos Neo4j.
Restauración manual : para restaurar la base de datos desde un directorio de respaldo, utilice el script de importación:
npm run db:import <path_to_backup_directory>
Reemplace <path_to_backup_directory> con la ruta real a la carpeta de respaldo (p. ej., ./atlas-backups/atlas-backup-20250326120000 ). Este comando ejecuta scripts/db-import.ts , que llama a la función importDatabase .
Manejo de relaciones : El proceso de importación intenta recrear las relaciones basándose en las propiedades id almacenadas en los nodos durante la exportación. Asegúrese de que sus nodos tengan propiedades id consistentes para que las relaciones se restablezcan correctamente.

Ejemplos

El directorio examples/ contiene ejemplos prácticos que demuestran varias características del servidor ATLAS MCP.

Ejemplo de copia de seguridad : Ubicado en examples/backup-example/ , muestra la estructura y el formato de los archivos JSON generados por el comando npm run db:backup . Consulte el archivo README de ejemplos para obtener más información.
Ejemplo de investigación profunda : Ubicado en examples/deep-research-example/ , este ejemplo muestra el resultado y la estructura generados por la herramienta atlas_deep_research . Incluye un archivo Markdown ( covington_community_grant_research.md ) que resume el plan de investigación y un archivo JSON ( full-export.json ) que contiene los datos sin procesar exportados desde la base de datos tras la creación del plan. Consulte el archivo README de ejemplos para obtener más información.

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Confirme sus cambios con un mensaje descriptivo
Empujar hacia la rama
Crear una solicitud de extracción

Para errores y solicitudes de funciones, cree un problema.

Licencia

Licencia Apache 2.0

atlas-mcp-server

Integrations