ATLAS: Task Management System

Um sistema de gerenciamento de tarefas para agentes LLM gerenciarem projetos, tarefas e conhecimento usando um banco de dados Neo4j para automação de fluxos de trabalho complexos.

GitHub

478

Experimente este MCPPatrocinado

Documentação

ATLAS: Task Management System

O ATLAS (Adaptive Task & Logic Automation System) é um sistema de gerenciamento de projetos, conhecimento e tarefas para Agentes LLM.

Construído sobre uma arquitetura de 3 nós:

                  +-------------------------------------------+
                  |                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 um servidor Model Context Protocol (MCP), o ATLAS permite que agentes LLM interajam com um banco de dados de gerenciamento de projetos, permitindo que eles gerenciem projetos, tarefas e itens de conhecimento.

Nota Importante sobre Versões: Versão 1.5.4 é a última versão que usa SQLite como banco de dados. A versão 2.0 em diante foi completamente reescrita para usar Neo4j, o que requer uma das seguintes opções:

Hospedagem própria usando Docker (docker-compose incluído no repositório)

Usando o serviço em nuvem Neo4j AuraDB: https://neo4j.com/product/auradb/

A versão 2.5.0 introduz um novo sistema de 3 nós (Projetos, Tarefas, Conhecimento) que substitui a estrutura anterior.

Visão Geral

O ATLAS implementa o Model Context Protocol (MCP), permitindo comunicação padronizada entre LLMs e sistemas externos por meio de:

Clientes: Claude Desktop, IDEs e outros clientes compatíveis com MCP
Servidores: Ferramentas e recursos para gerenciamento de projetos, tarefas e conhecimento
Agentes LLM: Modelos de IA que aproveitam as capacidades de gerenciamento do servidor

Integração do Sistema

A Plataforma Atlas integra esses componentes em um sistema coeso:

Relação Projeto-Tarefa: Projetos contêm tarefas que representam etapas acionáveis necessárias para atingir os objetivos do projeto. As tarefas herdam contexto do projeto pai, ao mesmo tempo em que fornecem acompanhamento granular de itens de trabalho individuais.
Integração de Conhecimento: Tanto projetos quanto tarefas podem ser enriquecidos com itens de conhecimento, fornecendo aos membros da equipe informações e contexto necessários.
Gerenciamento de Dependências: Tanto projetos quanto tarefas suportam relações de dependência, permitindo fluxos de trabalho complexos com pré-requisitos e requisitos de execução sequencial.
Busca Unificada: A plataforma fornece capacidades de busca entre entidades, permitindo que os usuários encontrem projetos, tarefas ou conhecimentos relevantes com base em vários critérios.

Recursos

Área de Recurso	Principais Capacidades
Gerenciamento de Projetos	- Acompanhamento Abrangente: Gerencie metadados de projetos, status e conteúdo rico (notas, links, etc.) com suporte integrado para operações em lote. - Tratamento de Dependências e Relações: Valide e acompanhe automaticamente dependências entre projetos.
Gerenciamento de Tarefas	- Gerenciamento do Ciclo de Vida de Tarefas: Crie, acompanhe e atualize tarefas ao longo de todo o seu ciclo de vida. - Priorização e Categorização: Atribua níveis de prioridade e categorize tarefas com tags para melhor organização. - Acompanhamento de Dependências: Estabeleça dependências entre tarefas para criar fluxos de trabalho estruturados.
Gerenciamento de Conhecimento	- Repositório Estruturado de Conhecimento: Mantenha um repositório pesquisável de informações relacionadas ao projeto. - Categorização por Domínio: Organize o conhecimento por domínio e tags para fácil recuperação. - Suporte a Citações: Acompanhe fontes e referências para itens de conhecimento.
Integração com Banco de Dados de Grafos	- Gerenciamento Nativo de Relações: Aproveite as transações compatíveis com ACID do Neo4j e consultas otimizadas para integridade robusta dos dados. - Busca Avançada e Escalabilidade: Realize buscas baseadas em propriedades com correspondência difusa e curingas, mantendo alto desempenho.
Busca Unificada	- Busca entre Entidades: Encontre projetos, tarefas ou conhecimentos relevantes com base em conteúdo, metadados ou relações. - Opções Flexíveis de Consulta: Suporte para opções de filtragem sem distinção de maiúsculas/minúsculas, difusas e avançadas.

Instalação

Clone o repositório:

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

Instale as dependências:
```
npm install
```
Configure o Neo4j: Certifique-se de ter uma instância do Neo4j em execução e acessível. Você pode iniciar uma usando a configuração Docker fornecida:
```
docker-compose up -d
```
Atualize seu arquivo .env com os detalhes de conexão do Neo4j (veja Configuração).
Compile o projeto:
```
npm run build
```

Executando o Servidor

A maioria dos clientes MCP executa o servidor automaticamente, mas você também pode executá-lo manualmente para fins de teste ou desenvolvimento usando os seguintes comandos.

O servidor MCP ATLAS suporta múltiplos mecanismos de transporte para comunicação:

Entrada/Saída Padrão (stdio): Este é o modo padrão e é tipicamente usado para integração direta com clientes MCP locais (como extensões de IDE).
```
npm run start:stdio
```
Isso usa a configuração MCP_TRANSPORT_TYPE=stdio.
Streamable HTTP: Este modo permite que o servidor escute solicitações MCP via HTTP, adequado para clientes remotos ou integrações baseadas na web.
```
npm run start:http
```
Isso usa a configuração MCP_TRANSPORT_TYPE=http. O servidor escutará no host e porta definidos no seu arquivo .env (por exemplo, MCP_HTTP_HOST e MCP_HTTP_PORT, com padrão em 127.0.0.1:3010). Certifique-se de que seu firewall permita conexões se estiver acessando remotamente.

Web UI (Experimental)

Uma Web UI básica está disponível para visualizar detalhes de Projetos, Tarefas e Conhecimento.

Abrindo a UI:
- Para abrir a UI diretamente no seu navegador, execute o seguinte comando no seu terminal:
```
npm run webui
```
Funcionalidade:
- Você pode ver um exemplo de captura de tela da Web UI aqui.

Configuração

Variáveis de Ambiente

As variáveis de ambiente devem ser definidas na configuração do cliente no seu MCP Client, ou em um arquivo .env na raiz do projeto para desenvolvimento 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 as variáveis de ambiente disponíveis, suas descrições e valores padrão.

Configurações do Cliente MCP

A forma como você configura seu cliente MCP depende do próprio cliente e do tipo de transporte escolhido. Um arquivo mcp.json na raiz do projeto pode ser usado por alguns clientes (como mcp-inspector) para definir configurações do servidor; atualize conforme necessário.

Para Transporte Stdio (Exemplo de Configuração):

{
  "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 Streamable HTTP (Exemplo de Configuração): Se o seu cliente suporta conexão a um servidor MCP via Streamable HTTP, você fornece o endpoint do servidor (por exemplo, http://localhost:3010/mcp) na configuração do seu 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: Sempre use caminhos absolutos para args ao configurar comandos do cliente se o servidor não estiver no diretório de trabalho imediato do cliente. O MCP_AUTH_SECRET_KEY no bloco env do cliente é ilustrativo; o tratamento real de tokens para comunicação cliente-servidor dependeria das capacidades do cliente e do mecanismo de autenticação do servidor (por exemplo, enviar um JWT em um cabeçalho Authorization).

Estrutura do Projeto

O código-fonte segue uma estrutura 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)

Ferramentas

O ATLAS fornece um conjunto abrangente de ferramentas para gerenciamento de projetos, tarefas e conhecimento, acionáveis via Model Context Protocol.

Operações de Projeto

Nome da Ferramenta	Descrição	Argumentos Principais
`atlas_project_create`	Cria novos projetos (único/em lote).	`mode` ('single'/'bulk'), `id` (ID gerado pelo cliente, opcional, para modo único), detalhes do projeto (`name`, `description`, `status`, `urls`, `completionRequirements`, `dependencies`, `outputFormat`, `taskType`). Para modo em lote, use `projects` (array de objetos de projeto). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_project_list`	Lista projetos (todos/detalhes).	`mode` ('all'/'details', padrão: 'all'), `id` (para modo detalhes), filtros (`status`, `taskType`), paginação (`page`, `limit`), inclusões (`includeKnowledge`, `includeTasks`), `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_project_update`	Atualiza projetos existentes (único/em lote).	`mode` ('single'/'bulk'), `id` (para modo único), objeto `updates`. Para modo em lote, use `projects` (array de objetos, cada um com `id` e `updates`). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_project_delete`	Exclui projetos (único/em lote).	`mode` ('single'/'bulk'), `id` (para modo único) ou `projectIds` (array para modo em lote). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').

Operações de Tarefa

Nome da Ferramenta	Descrição	Argumentos-chave
`atlas_task_create`	Cria novas tarefas (única/em lote).	`mode` ('single'/'bulk'), `id` (ID opcional gerado pelo cliente), `projectId`, detalhes da tarefa (`title`, `description`, `priority`, `status`, `assignedTo`, `urls`, `tags`, `completionRequirements`, `dependencies`, `outputFormat`, `taskType`). Para modo em lote, use `tasks` (array de objetos de tarefa). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_task_update`	Atualiza tarefas existentes (única/em lote).	`mode` ('single'/'bulk'), `id` (para modo único), objeto `updates`. Para modo em lote, use `tasks` (array de objetos, cada um com `id` e `updates`). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_task_delete`	Exclui tarefas (única/em lote).	`mode` ('single'/'bulk'), `id` (para modo único) ou `taskIds` (array para modo em lote). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_task_list`	Lista tarefas de um projeto específico.	`projectId` (obrigatório), filtros (`status`, `assignedTo`, `priority`, `tags`, `taskType`), ordenação (`sortBy`, `sortDirection`), paginação (`page`, `limit`), `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').

Operações de Conhecimento

Nome da Ferramenta	Descrição	Argumentos-chave
`atlas_knowledge_add`	Adiciona novos itens de conhecimento (único/em lote).	`mode` ('single'/'bulk'), `id` (ID opcional gerado pelo cliente), `projectId`, detalhes do conhecimento (`text`, `tags`, `domain`, `citations`). Para modo em lote, use `knowledge` (array de objetos de conhecimento). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_knowledge_delete`	Exclui itens de conhecimento (único/em lote).	`mode` ('single'/'bulk'), `id` (para modo único) ou `knowledgeIds` (array para modo em lote). `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').
`atlas_knowledge_list`	Lista itens de conhecimento de um projeto específico.	`projectId` (obrigatório), filtros (`tags`, `domain`, `search`), paginação (`page`, `limit`), `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').

Operações de Busca

Nome da Ferramenta	Descrição	Argumentos-chave
`atlas_unified_search`	Realiza busca unificada entre entidades.	`value` (termo de busca, obrigatório), `property` (opcional: se especificado, realiza busca regex nesta propriedade; se omitido, realiza busca de texto completo), filtros (`entityTypes`, `taskType`, `assignedToUserId`), opções (`caseInsensitive` (padrão: true, para regex), `fuzzy` (padrão: false, para regex 'contains' ou busca difusa Lucene de texto completo)), paginação (`page`, `limit`), `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').

Operações de Pesquisa

Nome da Ferramenta	Descrição	Argumentos-chave
`atlas_deep_research`	Inicia um processo estruturado de pesquisa aprofundada criando um plano hierárquico na base de conhecimento do Atlas.	`projectId` (obrigatório), `researchTopic` (obrigatório), `researchGoal` (obrigatório), `scopeDefinition` (opcional), `subTopics` (array obrigatório de objetos, cada um com `question` (obrigatório), `initialSearchQueries` (array opcional), `nodeId` (opcional), `priority` (opcional), `assignedTo` (opcional), `initialStatus` (opcional, padrão: 'todo')), `researchDomain` (opcional), `initialTags` (opcional), `planNodeId` (opcional), `createTasks` (opcional, padrão: true), `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').

Operações de Banco de Dados

Nome da Ferramenta	Descrição	Argumentos-chave
`atlas_database_clean`	Destrutivo: Redefine completamente o banco de dados, removendo todos os projetos, tarefas e conhecimentos.	`acknowledgement` (deve ser definido como `true` para confirmar, obrigatório), `responseFormat` ('formatted'/'json', opcional, padrão: 'formatted').

Recursos

O ATLAS expõe dados de projetos, tarefas e conhecimento por meio de endpoints de recursos MCP padrão.

Recursos Diretos

Nome do Recurso	Descrição
`atlas://projects`	Lista de todos os projetos na plataforma Atlas com suporte a paginação.
`atlas://tasks`	Lista de todas as tarefas na plataforma Atlas com suporte a paginação e filtragem.
`atlas://knowledge`	Lista de todos os itens de conhecimento na plataforma Atlas com suporte a paginação e filtragem.

Modelos de Recursos

Nome do Recurso	Descrição
`atlas://projects/{projectId}`	Recupera um único projeto pelo seu identificador único (`projectId`).
`atlas://tasks/{taskId}`	Recupera uma única tarefa pelo seu identificador único (`taskId`).
`atlas://projects/{projectId}/tasks`	Recupera todas as tarefas pertencentes a um projeto específico (`projectId`).
`atlas://knowledge/{knowledgeId}`	Recupera um único item de conhecimento pelo seu identificador único (`knowledgeId`).
`atlas://projects/{projectId}/knowledge`	Recupera todos os itens de conhecimento pertencentes a um projeto específico (`projectId`).

Backup e Restauração do Banco de Dados

O ATLAS fornece funcionalidade para fazer backup e restaurar o conteúdo do banco de dados Neo4j. A lógica principal reside em src/services/neo4j/backupRestoreService.ts.

Processo de Backup

Mecanismo: O processo de backup exporta todos os nós Project, Task e Knowledge, juntamente com seus relacionamentos, para arquivos JSON separados. Um full-export.json contendo todos os dados também é criado.
Saída: Cada backup cria um diretório com carimbo de data/hora (por exemplo, atlas-backup-YYYYMMDDHHMMSS) dentro do caminho de backup configurado (padrão: ./atlas-backups/). Este diretório contém projects.json, tasks.json, knowledge.json, relationships.json e full-export.json.
Backup Manual: Você pode acionar um backup manual usando o script fornecido:
```
npm run db:backup
```
Este comando executa src/services/neo4j/backupRestoreService/scripts/db-backup.ts, que chama a função exportDatabase.

Processo de Restauração

Mecanismo: O processo de restauração primeiro limpa completamente o banco de dados Neo4j existente. Em seguida, importa nós e relacionamentos dos arquivos JSON localizados no diretório de backup especificado. Ele prioriza full-export.json se disponível.
Aviso: Restaurar a partir de um backup é uma operação destrutiva. Isso sobrescreverá todos os dados atuais no seu banco de dados Neo4j.
Restauração Manual: Para restaurar o banco de dados a partir de um diretório de backup, use o script de importação:
```
npm run db:import <path_to_backup_directory>
```
Substitua <path_to_backup_directory> pelo caminho real para a pasta de backup (por exemplo, ./atlas-backups/atlas-backup-20250326120000). Este comando executa src/services/neo4j/backupRestoreService/scripts/db-import.ts, que chama a função importDatabase.
Tratamento de Relacionamentos: O processo de importação tenta recriar relacionamentos com base nas propriedades id armazenadas nos nós durante a exportação. Garanta que seus nós tenham propriedades id consistentes para que os relacionamentos sejam restaurados corretamente.

Exemplos

O diretório examples/ contém exemplos práticos que demonstram vários recursos do ATLAS MCP Server.

Exemplo de Backup: Localizado em examples/backup-example/, mostra a estrutura e o formato dos arquivos JSON gerados pelo comando npm run db:backup. Consulte o README de Exemplos para mais detalhes.
Exemplo de Pesquisa Aprofundada: Localizado em examples/deep-research-example/, demonstra a saída e a estrutura geradas pela ferramenta atlas_deep_research. Inclui um arquivo markdown (covington_community_grant_research.md) resumindo o plano de pesquisa e um arquivo JSON (full-export.json) contendo os dados brutos exportados do banco de dados após a criação do plano de pesquisa. Consulte o README de Exemplos para mais detalhes.

Licença

Apache License 2.0

Construído com o Model Context Protocol