ATLAS: Task Management System

Un sistema de gestión de t

Documentación

ATLAS: Sistema de Gestión de Tareas

ATLAS (Sistema Adaptativo de Automatización de Tareas y Lógica) es un sistema de gestión de proyectos, conocimiento y tareas para Agentes LLM.

Construido sobre una arquitectura de 3 nodos:

                  +-------------------------------------------+
                  |                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 una base de datos de gestión de proyectos, permitiéndoles gestionar proyectos, tareas y elementos de conocimiento.

Nota Importante de Versión: Versión 1.5.4 es la última versión que utiliza SQLite como base de datos. La versión 2.0 y posteriores ha sido completamente reescrita para usar Neo4j, lo que requiere:

Auto-alojamiento usando Docker (docker-compose incluido en el repositorio)

Usar el servicio en la nube Neo4j AuraDB: 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 Contenidos

Descripción General
Características
Instalación
Ejecución del Servidor
Interfaz Web (Experimental)
Configuración
Estructura del Proyecto
Herramientas
Recursos
Respaldo y Restauración de la Base de Datos
Ejemplos
Licencia

Descripción General

ATLAS implementa el Protocolo de Contexto de Modelo (MCP), permitiendo comunicación estandarizada entre LLMs y sistemas externos a través de:

Clientes: Claude Desktop, IDEs y otros clientes compatibles con MCP
Servidores: Herramientas y recursos para la gestión de proyectos, tareas y conocimiento
Agentes LLM: Modelos de IA que aprovechan las capacidades de gestión del servidor

Integración del Sistema

La Plataforma Atlas integra estos componentes en un sistema cohesivo:

Relación Proyecto-Tarea: Los proyectos contienen tareas que representan pasos accionables necesarios para lograr los objetivos del proyecto. Las tareas heredan contexto de su proyecto padre mientras proporcionan seguimiento granular de elementos de trabajo individuales.
Integración de Conocimiento: Tanto proyectos como 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 proyectos como tareas soportan relaciones de dependencia, permitiendo flujos de trabajo complejos con requisitos previos y requisitos de ejecución secuencial.
Búsqueda Unificada: La plataforma proporciona capacidades de búsqueda entre entidades, permitiendo a los usuarios encontrar proyectos, tareas o conocimiento relevantes basados en varios criterios.

Características

Área de Características	Capacidades Clave
Gestión de Proyectos	- Seguimiento Integral: Gestione metadatos de proyectos, estados y contenido enriquecido (notas, enlaces, etc.) con soporte integrado para operaciones masivas. - Manejo de Dependencias y Relaciones: Valide y rastree automáticamente dependencias entre proyectos.
Gestión de Tareas	- Gestión del Ciclo de Vida de Tareas: Cree, rastree y actualice tareas a través de todo su ciclo de vida. - Priorización y Categorización: Asigne niveles de prioridad y categorice tareas con etiquetas para mejor organización. - Seguimiento de Dependencias: Establezca dependencias de tareas para crear flujos de trabajo estructurados.
Gestión de Conocimiento	- Repositorio de Conocimiento Estructurado: Mantenga un repositorio buscable de información relacionada con proyectos. - Categorización por Dominio: Organice conocimiento por dominio y etiquetas para fácil recuperación. - Soporte de Citas: Rastree fuentes y referencias para elementos de conocimiento.
Integración de Base de Datos de Grafos	- Gestión Nativa de Relaciones: Aproveche las transacciones compatibles con ACID de Neo4j y consultas optimizadas para robusta integridad de datos. - Búsqueda Avanzada y Escalabilidad: Realice búsquedas basadas en propiedades con coincidencia difusa y comodines manteniendo alto rendimiento.
Búsqueda Unificada	- Búsqueda entre Entidades: Encuentre proyectos, tareas o conocimiento relevantes basados en contenido, metadatos o relaciones. - Opciones de Consulta Flexibles: Soporte para opciones de filtrado avanzado, difuso y sin distinción de mayúsculas/minúsculas.

Instalación

Clone el repositorio:

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

Instale las dependencias:
```
npm install
```
Configure Neo4j: Asegúrese de tener una instancia de Neo4j ejecutándose y accesible. Puede iniciar una usando la configuración de Docker proporcionada:
```
docker-compose up -d
```
Actualice su archivo .env con los detalles de conexión de Neo4j (ver Configuración).
Construya el proyecto:
```
npm run build
```

Ejecución del Servidor

La mayoría de los Clientes MCP ejecutan el servidor automáticamente, pero también puede ejecutarlo manualmente para pruebas o desarrollo usando los siguientes comandos.

El Servidor MCP de ATLAS soporta múltiples mecanismos de transporte para comunicación:

Entrada/Salida Estándar (stdio): Este es el modo predeterminado y se usa típicamente para integración directa con clientes MCP locales (como extensiones de IDE).
```
npm run start:stdio
```
Esto usa la configuración MCP_TRANSPORT_TYPE=stdio.
HTTP Transmisible (Streamable HTTP): Este modo permite al servidor escuchar solicitudes MCP a través de HTTP, adecuado para clientes remotos o integraciones basadas en web.
```
npm run start:http
```
Esto usa la configuración MCP_TRANSPORT_TYPE=http. El servidor escuchará en el host y puerto definidos en su archivo .env (ej., MCP_HTTP_HOST y MCP_HTTP_PORT, con valores predeterminados de 127.0.0.1:3010). Asegúrese de que su firewall permita conexiones si accede de forma remota.

Interfaz Web (Experimental)

Una Interfaz Web básica está disponible para ver detalles de Proyectos, Tareas y Conocimiento.

Abrir la Interfaz:
- Para abrir la interfaz directamente en su navegador, ejecute el siguiente comando en su terminal:
```
npm run webui
```
Funcionalidad:
- Puede ver una captura de pantalla de ejemplo de la Interfaz Web aquí.

Configuración

Variables de Entorno

Las variables de entorno deben establecerse en la configuración del cliente en su Cliente MCP, o en un archivo .env en la raíz del proyecto para desarrollo local.

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

# Application Configuration
MCP_LOG_LEVEL=debug # Minimum logging level. Options: emerg, alert, crit, error, warning, notice, info, debug. Default: "debug".
LOGS_DIR=./logs # Directory for log files. Default: "./logs" in project root.
NODE_ENV=development # 'development' or 'production'. Default: "development".

# MCP Transport Configuration
MCP_TRANSPORT_TYPE=stdio # 'stdio' or 'http'. Default: "stdio".
MCP_HTTP_HOST=127.0.0.1 # Host for HTTP transport. Default: "127.0.0.1".
MCP_HTTP_PORT=3010 # Port for HTTP transport. Default: 3010.
# MCP_ALLOWED_ORIGINS=http://localhost:someport,https://your-client.com # Optional: Comma-separated list of allowed origins for HTTP CORS.

# MCP Security Configuration
# MCP_AUTH_SECRET_KEY=your_very_long_and_secure_secret_key_min_32_chars # Optional: Secret key (min 32 chars) for JWT authentication if HTTP transport is used. CRITICAL for production. *Note: Production environment use has not been tested yet.*
MCP_RATE_LIMIT_WINDOW_MS=60000 # Rate limit window in milliseconds. Default: 60000 (1 minute).
MCP_RATE_LIMIT_MAX_REQUESTS=100 # Max requests per window per IP for HTTP transport. Default: 100.

# Database Backup Configuration
BACKUP_MAX_COUNT=10 # Maximum number of backup sets to keep. Default: 10.
BACKUP_FILE_DIR=./atlas-backups # Directory where backup files will be stored (relative to project root). Default: "./atlas-backups".

Consulte src/config/index.ts para todas las variables de entorno disponibles, sus descripciones y valores predeterminados.

Configuración del Cliente MCP

Cómo configure su cliente MCP depende del propio cliente y del tipo de transporte elegido. Un archivo mcp.json en la raíz del proyecto puede ser usado por algunos clientes (como mcp-inspector) para definir configuraciones de servidor; actualícelo según sea necesario.

Para Transporte Stdio (Configuración de Ejemplo):

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

Para HTTP Transmisible (Configuración de Ejemplo): Si su cliente soporta conectarse a un servidor MCP a través de HTTP Transmisible, proporcione el endpoint del servidor (ej., http://localhost:3010/mcp) en su configuración de cliente.

{
  "mcpServers": {
    "atlas-mcp-server-http": {
      "command": "node",
      "args": ["/full/path/to/atlas-mcp-server/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password2",
        "MCP_LOG_LEVEL": "info",
        "NODE_ENV": "development",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3010",
        "MCP_HTTP_HOST": "127.0.0.1"
        // "MCP_AUTH_SECRET_KEY": "your-secure-token" // If authentication is enabled on the server
      }
    }
  }
}

Nota: Siempre use rutas absolutas para args al configurar comandos de cliente si el servidor no está en el directorio de trabajo inmediato del cliente. El MCP_AUTH_SECRET_KEY en el bloque env del cliente es ilustrativo; el manejo real de tokens para comunicación cliente-servidor dependería de las capacidades del cliente y el mecanismo de autenticación del servidor (ej., enviando un JWT en un encabezado Authorization).

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 and internal services (e.g., logger, errorHandler, sanitization)

Herramientas

ATLAS proporciona un conjunto integral de herramientas para la gestión de proyectos, tareas y conocimiento, invocables a través del Protocolo de Contexto de Modelo.

Operaciones de Proyecto

Nombre de Herramienta	Descripción	Argumentos Clave
`atlas_project_create`	Crea nuevos proyectos (individual/masivo).	`mode` ('single'/'bulk'), `id` (ID opcional generado por cliente para modo individual), detalles del proyecto (`name`, `description`, `status`, `urls`, `completionRequirements`, `dependencies`, `outputFormat`, `taskType`). Para modo masivo, use `projects` (array de objetos de proyecto). `responseFormat` ('formatted'/'json', opcional, predeterminado: 'formatted').
`atlas_project_list`	Lista proyectos (todos/detalles).	`mode` ('all'/'details', predeterminado: 'all'), `id` (para modo detalles), filtros (`status`, `taskType`), paginación (`page`, `limit`), inclusiones (`includeKnowledge`, `includeTasks`), `responseFormat` ('formatted'/'json', opcional, predeterminado: 'formatted').
`atlas_project_update`	Actualiza proyectos existentes (individual/masivo).	`mode` ('single'/'bulk'), `id` (para modo individual), objeto `updates`. Para modo masivo, use `projects` (array de objetos, cada uno con `id` y `updates`). `responseFormat` ('formatted'/'json', opcional, predeterminado: 'formatted').
`atlas_project_delete`	Elimina proyectos (individual/masivo).	`mode` ('single'/'bulk'), `id` (para modo individual) o `projectIds` (array para modo masivo). `responseFormat` ('formatted'/'json', opcional, predeterminado: 'formatted').

Operaciones de Tarea

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_task_create`	Crea nuevas tareas (individuales/masivas).	`mode` ('single'/'bulk'), `id` (ID opcional generado por el cliente), `projectId`, detalles de la tarea (`title`, `description`, `priority`, `status`, `assignedTo`, `urls`, `tags`, `completionRequirements`, `dependencies`, `outputFormat`, `taskType`). Para modo masivo, use `tasks` (arreglo de objetos de tarea). `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').
`atlas_task_update`	Actualiza tareas existentes (individuales/masivas).	`mode` ('single'/'bulk'), `id` (para modo individual), objeto `updates`. Para modo masivo, use `tasks` (arreglo de objetos, cada uno con `id` y `updates`). `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').
`atlas_task_delete`	Elimina tareas (individuales/masivas).	`mode` ('single'/'bulk'), `id` (para modo individual) o `taskIds` (arreglo para modo masivo). `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').
`atlas_task_list`	Lista tareas para un proyecto específico.	`projectId` (requerido), filtros (`status`, `assignedTo`, `priority`, `tags`, `taskType`), ordenamiento (`sortBy`, `sortDirection`), paginación (`page`, `limit`), `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').

Operaciones de Conocimiento

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_knowledge_add`	Agrega nuevos elementos de conocimiento (individuales/masivos).	`mode` ('single'/'bulk'), `id` (ID opcional generado por el cliente), `projectId`, detalles del conocimiento (`text`, `tags`, `domain`, `citations`). Para modo masivo, use `knowledge` (arreglo de objetos de conocimiento). `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').
`atlas_knowledge_delete`	Elimina elementos de conocimiento (individuales/masivos).	`mode` ('single'/'bulk'), `id` (para modo individual) o `knowledgeIds` (arreglo para modo masivo). `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').
`atlas_knowledge_list`	Lista elementos de conocimiento para un proyecto específico.	`projectId` (requerido), filtros (`tags`, `domain`, `search`), paginación (`page`, `limit`), `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').

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, requerido), `property` (opcional: si se especifica, realiza búsqueda regex en esta propiedad; si se omite, realiza búsqueda de texto completo), filtros (`entityTypes`, `taskType`, `assignedToUserId`), opciones (`caseInsensitive` (por defecto: true, para regex), `fuzzy` (por defecto: false, para regex 'contains' o búsqueda difusa de Lucene de texto completo)), paginación (`page`, `limit`), `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').

Operaciones de Investigación

Nombre de la herramienta	Descripción	Argumentos clave
`atlas_deep_research`	Inicia un proceso de investigación profunda estructurada mediante la creación de un plan jerárquico dentro de la base de conocimiento de Atlas.	`projectId` (requerido), `researchTopic` (requerido), `researchGoal` (requerido), `scopeDefinition` (opcional), `subTopics` (arreglo requerido de objetos, cada uno con `question` (requerido), `initialSearchQueries` (arreglo opcional), `nodeId` (opcional), `priority` (opcional), `assignedTo` (opcional), `initialStatus` (opcional, por defecto: 'todo')), `researchDomain` (opcional), `initialTags` (opcional), `planNodeId` (opcional), `createTasks` (opcional, por defecto: true), `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').

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 conocimiento.	`acknowledgement` (debe establecerse en `true` para confirmar, requerido), `responseFormat` ('formatted'/'json', opcional, por defecto: 'formatted').

Recursos

ATLAS expone datos de proyectos, tareas y conocimiento a través de endpoints 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`	Lista 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 proyecto individual por su identificador único (`projectId`).
`atlas://tasks/{taskId}`	Recupera una tarea individual por su identificador único (`taskId`).
`atlas://projects/{projectId}/tasks`	Recupera todas las tareas pertenecientes a un proyecto específico (`projectId`).
`atlas://knowledge/{knowledgeId}`	Recupera un elemento de conocimiento individual por su identificador único (`knowledgeId`).
`atlas://projects/{projectId}/knowledge`	Recupera todos los elementos de conocimiento pertenecientes a un proyecto específico (`projectId`).

Respaldo y Restauración de Base de Datos

ATLAS proporciona funcionalidad para respaldar y restaurar el contenido de la base de datos Neo4j. La lógica central reside en src/services/neo4j/backupRestoreService.ts.

Proceso de Respaldo

Mecanismo: El proceso de respaldo exporta todos los nodos Project, Task y Knowledge, junto con sus relaciones, en archivos JSON separados. También se crea un full-export.json que contiene todos los datos.
Salida: Cada respaldo crea un directorio con marca de tiempo (por ejemplo, atlas-backup-YYYYMMDDHHMMSS) dentro de la ruta de respaldo configurada (por defecto: ./atlas-backups/). Este directorio contiene projects.json, tasks.json, knowledge.json, relationships.json y full-export.json.
Respaldo Manual: Puede activar un respaldo manual usando el script proporcionado:
```
npm run db:backup
```
Este comando ejecuta src/services/neo4j/backupRestoreService/scripts/db-backup.ts, que llama a la función exportDatabase.

Proceso de Restauración

Mecanismo: El proceso de restauración primero limpia por completo la base de datos Neo4j existente. Luego, importa nodos y relaciones desde los archivos JSON ubicados en el directorio de respaldo especificado. Prioriza full-export.json si está disponible.
Advertencia: Restaurar desde una copia de seguridad es una operación destructiva. Sobrescribirá todos los datos actuales en su base de datos Neo4j.
Restauración manual: Para restaurar la base de datos desde un directorio de respaldo, use 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 (por ejemplo, ./atlas-backups/atlas-backup-20250326120000). Este comando ejecuta src/services/neo4j/backupRestoreService/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 dentro de los nodos durante la exportación. Asegúrese de que sus nodos tengan propiedades id consistentes para que las relaciones se restauren correctamente.

Ejemplos

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

Ejemplo de respaldo: 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 README de ejemplos para más detalles.
Ejemplo de investigación profunda: Ubicado en examples/deep-research-example/, demuestra la salida y la estructura generadas 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 de la base de datos después de que se creó el plan de investigación. Consulte el README de ejemplos para más detalles.

Licencia

Apache License 2.0

Construido con el Model Context Protocol