ATLAS: Aufgabenmanagementsystem

ATLAS (Adaptive Task & Logic Automation System) ist ein Projekt-, Wissens- und Aufgabenmanagementsystem für LLM-Agenten.

Basiert auf einer dreistufigen Architektur:

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

ATLAS wird als Model Context Protocol (MCP)-Server implementiert und ermöglicht LLM-Agenten die Interaktion mit einer Projektmanagementdatenbank, sodass sie Projekte, Aufgaben und Wissenselemente verwalten können.

Wichtiger Versionshinweis : Version 1.5.4 ist die letzte Version, die SQLite als Datenbank verwendet. Ab Version 2.0 wurde die Verwendung von Neo4j vollständig neu geschrieben. Dies erfordert entweder:

• Selbsthosting mit Docker (Docker-Compose im Repository enthalten)

• Verwenden des Neo4j AuraDB-Clouddienstes: https://neo4j.com/product/auradb/

Version 2.5.0 führt ein neues 3-Knoten-System (Projekte, Aufgaben, Wissen) ein, das die vorherige Struktur ersetzt.

Inhaltsverzeichnis

• Überblick

• Merkmale

• Installation

• Ausführen des Servers

• Web-Benutzeroberfläche (experimentell)

• Konfiguration

• Projektstruktur

• Werkzeuge

• Ressourcen

• Datenbanksicherung und -wiederherstellung

• Beispiele

• Lizenz

Related MCP server: Apollo.io MCP Server

Überblick

ATLAS implementiert das Model Context Protocol (MCP) und ermöglicht so eine standardisierte Kommunikation zwischen LLMs und externen Systemen durch:

• Clients : Claude Desktop, IDEs und andere MCP-kompatible Clients

• Server : Tools und Ressourcen für Projekt-, Aufgaben- und Wissensmanagement

• LLM-Agenten : KI-Modelle, die die Verwaltungsfunktionen des Servers nutzen

Systemintegration

Die Atlas-Plattform integriert diese Komponenten in ein zusammenhängendes System:

• Projekt-Aufgaben-Beziehung : Projekte enthalten Aufgaben, die die notwendigen Schritte zum Erreichen der Projektziele darstellen. Aufgaben übernehmen den Kontext ihres übergeordneten Projekts und ermöglichen gleichzeitig eine detaillierte Nachverfolgung einzelner Arbeitselemente.

• Wissensintegration : Sowohl Projekte als auch Aufgaben können mit Wissenselementen angereichert werden, wodurch Teammitglieder mit den erforderlichen Informationen und dem Kontext versorgt werden.

• Abhängigkeitsverwaltung : Sowohl Projekte als auch Aufgaben unterstützen Abhängigkeitsbeziehungen und ermöglichen so komplexe Arbeitsabläufe mit Voraussetzungen und Anforderungen an die sequenzielle Ausführung.

• Einheitliche Suche : Die Plattform bietet entitätsübergreifende Suchfunktionen, mit denen Benutzer relevante Projekte, Aufgaben oder Kenntnisse anhand verschiedener Kriterien finden können.

Merkmale

Projektmanagement

• Umfassende Nachverfolgung: Verwalten Sie Projektmetadaten, Status und umfangreiche Inhalte (Notizen, Links usw.) mit integrierter Unterstützung für Massenvorgänge.

• Handhabung von Abhängigkeiten und Beziehungen: Automatische Validierung und Verfolgung von Abhängigkeiten zwischen Projekten.

Aufgabenverwaltung

• Aufgaben-Lebenszyklus-Management: Erstellen, verfolgen und aktualisieren Sie Aufgaben während ihres gesamten Lebenszyklus.

• Priorisierung und Kategorisierung: Weisen Sie Prioritätsstufen zu und kategorisieren Sie Aufgaben mit Tags für eine bessere Organisation.

• Abhängigkeitsverfolgung: Legen Sie Aufgabenabhängigkeiten fest, um strukturierte Arbeitsabläufe zu erstellen.

Wissensmanagement

• Strukturiertes Wissensrepository: Pflegen Sie ein durchsuchbares Repository mit projektbezogenen Informationen.

• Domänenkategorisierung: Organisieren Sie Wissen nach Domänen und Tags, um es leicht wiederzufinden.

• Zitatunterstützung: Verfolgen Sie Quellen und Referenzen für Wissenselemente.

Graphdatenbankintegration

• Natives Beziehungsmanagement: Nutzen Sie die ACID-konformen Transaktionen und optimierten Abfragen von Neo4j für robuste Datenintegrität.

• Erweiterte Suche und Skalierbarkeit: Führen Sie eigenschaftsbasierte Suchen mit Fuzzy-Matching und Platzhaltern durch und behalten Sie dabei die hohe Leistung bei.

Einheitliche Suche

• Entitätsübergreifende Suche: Finden Sie relevante Projekte, Aufgaben oder Wissen basierend auf Inhalten, Metadaten oder Beziehungen.

• Flexible Abfrageoptionen: Unterstützung für Groß- und Kleinschreibung, unscharfe und erweiterte Filteroptionen.

Installation

1. Klonen Sie das Repository:

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

2. Installieren Sie Abhängigkeiten:

   npm install

3. Neo4j konfigurieren: Stellen Sie sicher, dass eine Neo4j-Instanz läuft und zugänglich ist. Sie können eine solche mit der bereitgestellten Docker-Konfiguration starten:

   docker-compose up -d

   Aktualisieren Sie Ihre .env Datei mit den Neo4j-Verbindungsdetails (siehe Konfiguration ).

4. Erstellen Sie das Projekt:

   npm run build

Ausführen des Servers

Die meisten MCP-Clients führen den Server automatisch aus, Sie können ihn jedoch auch manuell zu Test- oder Entwicklungszwecken mit den folgenden Befehlen ausführen.

ATLAS MCP Server unterstützt mehrere Transportmechanismen für die Kommunikation:

• Standard-E/A (stdio): Dies ist der Standardmodus und wird normalerweise für die direkte Integration mit lokalen MCP-Clients (wie IDE-Erweiterungen) verwendet.

  npm run start:stdio

  Dies verwendet die Einstellung MCP_TRANSPORT_TYPE=stdio .

• Streamable HTTP: Dieser Modus ermöglicht dem Server, auf MCP-Anfragen über HTTP zu warten, geeignet für Remote-Clients oder webbasierte Integrationen.

  npm run start:http

  Dies verwendet die Einstellung MCP_TRANSPORT_TYPE=http . Der Server überwacht den in Ihrer .env Datei definierten Host und Port (z. B. MCP_HTTP_HOST und MCP_HTTP_PORT , standardmäßig 127.0.0.1:3010 ). Stellen Sie sicher, dass Ihre Firewall Verbindungen bei Remote-Zugriffen zulässt.

Web-Benutzeroberfläche (experimentell)

Zum Anzeigen von Projekt-, Aufgaben- und Wissensdetails steht eine einfache Web-Benutzeroberfläche zur Verfügung.

• Öffnen der Benutzeroberfläche :

  • Um die Benutzeroberfläche direkt in Ihrem Browser zu öffnen, führen Sie den folgenden Befehl in Ihrem Terminal aus:

    npm run webui

• Funktionalität :

  • Einen Beispiel-Screenshot der Web-Benutzeroberfläche können Sie hier sehen.

Konfiguration

Umgebungsvariablen

Umgebungsvariablen sollten in der Clientkonfiguration in Ihrem MCP-Client oder in einer .env Datei im Projektstamm für die lokale Entwicklung festgelegt werden.

# 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".

# OpenRouter LLM Configuration (Optional - additional parameters present in `src/config/index.ts`)
# OPENROUTER_API_KEY=your_openrouter_api_key # API key for OpenRouter services.
LLM_DEFAULT_MODEL="google/gemini-2.5-flash-preview:thinking" # Default LLM model.

Alle verfügbaren Umgebungsvariablen, ihre Beschreibungen und Standardwerte finden Sie in src/config/index.ts .

MCP-Client-Einstellungen

Die Konfiguration Ihres MCP-Clients hängt vom Client selbst und dem gewählten Transporttyp ab. Eine mcp.json Datei im Projektstamm kann von einigen Clients (z. B. mcp-inspector ) zur Definition von Serverkonfigurationen verwendet werden. Aktualisieren Sie diese bei Bedarf.

Für Stdio-Transport (Beispielkonfiguration):

{
  "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": "production",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Für Streamable HTTP (Beispielkonfiguration): Wenn Ihr Client die Verbindung zu einem MCP-Server über Streamable HTTP unterstützt, geben Sie den Endpunkt des Servers (z. B. http://localhost:3010/mcp ) in Ihrer Clientkonfiguration an.

{
  "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": "production",
        "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
      }
    }
  }
}

Hinweis: Verwenden Sie bei der Konfiguration von Client-Befehlen immer absolute Pfade für args , wenn sich der Server nicht im unmittelbaren Arbeitsverzeichnis des Clients befindet. Der MCP_AUTH_SECRET_KEY im env des Clients dient lediglich der Veranschaulichung; die tatsächliche Token-Verarbeitung für die Client-Server-Kommunikation hängt von den Fähigkeiten des Clients und dem Authentifizierungsmechanismus des Servers ab (z. B. Senden eines JWT in einem Authorization ).

Projektstruktur

Die Codebasis folgt einer modularen Struktur:

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
│   ├── llm-providers/ # LLM provider integrations (e.g., OpenRouter)
│   └── 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)

Werkzeuge

ATLAS bietet eine umfassende Suite von Tools für Projekt-, Aufgaben- und Wissensmanagement, die über das Model Context Protocol aufrufbar sind.

Projektbetrieb

Aufgabenvorgänge

Wissensoperationen

Suchvorgänge

Forschungsbetrieb

Datenbankoperationen

Ressourcen

ATLAS stellt Projekt-, Aufgaben- und Wissensdaten über standardmäßige MCP-Ressourcenendpunkte bereit.

Direkte Ressourcen

Ressourcenvorlagen

Datenbanksicherung und -wiederherstellung

ATLAS bietet Funktionen zum Sichern und Wiederherstellen des Neo4j-Datenbankinhalts. Die Kernlogik befindet sich in src/services/neo4j/backupRestoreService.ts .

Backup-Prozess

• Mechanismus : Der Sicherungsvorgang exportiert alle Project , Task und Knowledge sowie deren Beziehungen in separate JSON-Dateien. Außerdem wird eine Datei full-export.json mit allen Daten erstellt.

• Ausgabe : Jedes Backup erstellt ein mit einem Zeitstempel versehenes Verzeichnis (z. B. atlas-backup-YYYYMMDDHHMMSS ) innerhalb des konfigurierten Backup-Pfades (Standard: ./atlas-backups/ ). Dieses Verzeichnis enthält projects.json , tasks.json , knowledge.json , relationships.json und full-export.json .

• Manuelle Sicherung : Sie können mit dem bereitgestellten Skript eine manuelle Sicherung auslösen:

  npm run db:backup

  Dieser Befehl führt scripts/db-backup.ts aus, wodurch die Funktion exportDatabase aufgerufen wird.

Wiederherstellungsprozess

• Mechanismus : Der Wiederherstellungsprozess löscht zunächst die vorhandene Neo4j-Datenbank vollständig. Anschließend importiert er Knoten und Beziehungen aus den JSON-Dateien im angegebenen Sicherungsverzeichnis. Sofern verfügbar, wird full-export.json priorisiert.

• Warnung : Die Wiederherstellung aus einer Sicherung ist ein destruktiver Vorgang. Alle aktuellen Daten in Ihrer Neo4j-Datenbank werden überschrieben.

• Manuelle Wiederherstellung : Um die Datenbank aus einem Sicherungsverzeichnis wiederherzustellen, verwenden Sie das Importskript:

  npm run db:import <path_to_backup_directory>

  Ersetzen Sie <path_to_backup_directory> durch den tatsächlichen Pfad zum Sicherungsordner (z. B. ./atlas-backups/atlas-backup-20250326120000 ). Dieser Befehl führt scripts/db-import.ts aus, wodurch die Funktion importDatabase aufgerufen wird.

• Beziehungsbehandlung : Der Importvorgang versucht, Beziehungen basierend auf den während des Exports in den Knoten gespeicherten id -Eigenschaften wiederherzustellen. Stellen Sie sicher, dass Ihre Knoten über konsistente id -Eigenschaften verfügen, damit die Beziehungen korrekt wiederhergestellt werden können.

Beispiele

Das Verzeichnis examples/ enthält praktische Beispiele, die verschiedene Funktionen des ATLAS MCP-Servers demonstrieren.

• Backup-Beispiel : Dieses Beispiel befindet sich unter examples/backup-example/ und zeigt die Struktur und das Format der JSON-Dateien, die vom Befehl npm run db:backup generiert werden. Weitere Informationen finden Sie in der README-Datei der Beispiele .

• Beispiel für eine intensive Recherche : Dieses Beispiel befindet sich unter examples/deep-research-example/ und demonstriert die vom Tool atlas_deep_research generierte Ausgabe und Struktur. Es enthält eine Markdown-Datei ( covington_community_grant_research.md ) mit einer Zusammenfassung des Forschungsplans und eine JSON-Datei ( full-export.json ) mit den Rohdaten, die nach der Erstellung des Forschungsplans aus der Datenbank exportiert wurden. Weitere Informationen finden Sie in der README-Datei der Beispiele .

Lizenz

Apache-Lizenz 2.0