Atlas-MCP-Server

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
Konfiguration
Projektstruktur
Werkzeuge
Ressourcen
Datenbanksicherung und -wiederherstellung
Beispiele
Lizenz

Ü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 ignorierende, unscharfe und erweiterte Filteroptionen.

Installation

Klonen Sie das Repository:
git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server
Installieren Sie Abhängigkeiten:
npm install
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 ).
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.

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
LOG_LEVEL=info # Log level for the server (corresponds to MCP_LOG_LEVEL). Options: emerg, alert, crit, error, warning, notice, info, debug.
NODE_ENV=development # 'development' or 'production'.

# 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 for JWT authentication if HTTP transport is used.
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: ./backups.

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

MCP-Client-Einstellungen

Wie Sie Ihren MCP-Client konfigurieren, hängt vom Client selbst und dem gewählten Transporttyp ab.

Für Stdio-Transport: Normalerweise konfigurieren Sie den Client so, dass er das Startskript des Servers ausführt.

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

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

Wenn Ihr Client den Server für den HTTP-Modus startet:

{
  "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",
        "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
│   └── 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

Werkzeugname	Beschreibung	Hauptargumente
`atlas_project_create`	Erstellt neue Projekte (einzeln/in großen Mengen).	`mode` („Einzeln“/„Massen“), `id` (optionale vom Client generierte ID für Einzelmodus), Projektdetails ( `name` , `description` , `status` , `urls` , `completionRequirements` , `dependencies` , `outputFormat` , `taskType` ). Verwenden Sie für den Massenmodus `projects` (Array von Projektobjekten). `responseFormat` („formatiert“/„JSON“, optional, Standard: „formatiert“).
`atlas_project_list`	Listet Projekte auf (alle/Details).	`mode` („alle“/„Details“, Standard: „alle“), `id` (für Detailmodus), Filter ( `status` , `taskType` ), Paginierung ( `page` , `limit` ), Includes ( `includeKnowledge` , `includeTasks` ), `responseFormat` („formatiert“/„json“, optional, Standard: „formatiert“).
`atlas_project_update`	Aktualisiert vorhandene Projekte (einzeln/massenhaft).	`mode` ('Einzel'/'Bulk'), `id` (für Einzelmodus), `updates` . Verwenden Sie für den Bulk-Modus `projects` (Array von Objekten, jedes mit `id` und `updates` ). `responseFormat` ('formatiert'/'json', optional, Standard: 'formatiert').
`atlas_project_delete`	Löscht Projekte (einzeln/in großen Mengen).	`mode` (,Einzel‘/,Bulk‘), `id` (für Einzelmodus) oder `projectIds` (Array für Bulk-Modus). `responseFormat` (,formatiert‘/,JSON‘, optional, Standard: ,formatiert‘).

Aufgabenvorgänge

Werkzeugname	Beschreibung	Hauptargumente
`atlas_task_create`	Erstellt neue Aufgaben (einzeln/massenweise).	`mode` („Einzeln“/„Massen“), `id` (optionale vom Client generierte ID), `projectId` , Aufgabendetails ( `title` , `description` , `priority` , `status` , `assignedTo` , `urls` , `tags` , `completionRequirements` , `dependencies` , `outputFormat` , `taskType` ). Verwenden Sie für den Massenmodus `tasks` (Array von Aufgabenobjekten). `responseFormat` („formatiert“/„JSON“, optional, Standard: „formatiert“).
`atlas_task_update`	Aktualisiert vorhandene Aufgaben (einzeln/massenhaft).	`mode` ('single'/'bulk'), `id` (für Einzelmodus), `updates` . Verwenden Sie für den Massenmodus `tasks` (Array von Objekten, jedes mit `id` und `updates` ). `responseFormat` ('formatted'/'json', optional, Standard: 'formatted').
`atlas_task_delete`	Löscht Aufgaben (einzeln/massenweise).	`mode` (,Einzel‘/,Bulk‘), `id` (für Einzelmodus) oder `taskIds` (Array für Bulk-Modus). `responseFormat` (,formatiert‘/,JSON‘, optional, Standard: ,formatiert‘).
`atlas_task_list`	Listet Aufgaben für ein bestimmtes Projekt auf.	`projectId` (erforderlich), Filter ( `status` , `assignedTo` , `priority` , `tags` , `taskType` ), Sortierung ( `sortBy` , `sortDirection` ), Paginierung ( `page` , `limit` ), `responseFormat` (,formatiert‘/,json‘, optional, Standard: ,formatiert‘).

Wissensoperationen

Werkzeugname	Beschreibung	Hauptargumente
`atlas_knowledge_add`	Fügt neue Wissenselemente hinzu (einzeln/in großen Mengen).	`mode` (,Einzel‘/,Bulk‘), `id` (optionale vom Client generierte ID), `projectId` , Wissensdetails ( `text` , `tags` , `domain` , `citations` ). Verwenden Sie für den Bulk-Modus „ `knowledge` (Array von Wissensobjekten). `responseFormat` (,formatiert‘/,JSON‘, optional, Standard: ,formatiert‘).
`atlas_knowledge_delete`	Löscht Wissenselemente (einzeln/in großen Mengen).	`mode` (,Einzel‘/,Bulk‘), `id` (für Einzelmodus) oder `knowledgeIds` (Array für Bulk-Modus). `responseFormat` (,formatiert‘/,JSON‘, optional, Standard: ,formatiert‘).
`atlas_knowledge_list`	Listet Wissenselemente für ein bestimmtes Projekt auf.	`projectId` (erforderlich), Filter ( `tags` , `domain` , `search` ), Paginierung ( `page` , `limit` ), `responseFormat` ('formatiert'/'json', optional, Standard: 'formatiert').

Suchvorgänge

Werkzeugname	Beschreibung	Hauptargumente
`atlas_unified_search`	Führt eine einheitliche Suche über alle Entitäten hinweg durch.	`value` (Suchbegriff, erforderlich), `property` (optional), Filter ( `entityTypes` , `taskType` ), Optionen ( `caseInsensitive` (Standard: true), `fuzzy` (Standard: false)), Paginierung ( `page` , `limit` ), `responseFormat` (,formatiert‘/,json‘, optional, Standard: ,formatiert‘).

Forschungsbetrieb

Werkzeugname	Beschreibung	Hauptargumente
`atlas_deep_research`	Initiiert einen strukturierten, gründlichen Forschungsprozess durch die Erstellung eines hierarchischen Plans innerhalb der Atlas-Wissensdatenbank.	`projectId` (erforderlich), `researchTopic` (erforderlich), `researchGoal` (erforderlich), `scopeDefinition` (optional), `subTopics` (erforderliches Array von Objekten, jedes mit `question` (erforderlich), `initialSearchQueries` (optionales Array), `nodeId` (optional), `priority` (optional), `assignedTo` (optional), `initialStatus` (optional, Standard: ‚todo‘)), `researchDomain` (optional), `initialTags` (optional), `planNodeId` (optional), `createTasks` (optional, Standard: true), `responseFormat` (‚formatted‘/‚json‘, optional, Standard: ‚formatted‘).

Datenbankoperationen

Werkzeugname	Beschreibung	Hauptargumente
`atlas_database_clean`	Destruktiv: Setzt die Datenbank vollständig zurück und entfernt alle Projekte, Aufgaben und Kenntnisse.	`acknowledgement` (muss zur Bestätigung auf `true` gesetzt werden, erforderlich), `responseFormat` („formatiert“/„json“, optional, Standard: „formatiert“).

Ressourcen

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

Direkte Ressourcen

Ressourcenname	Beschreibung
`atlas://projects`	Liste aller Projekte in der Atlas-Plattform mit Paginierungsunterstützung.
`atlas://tasks`	Liste aller Aufgaben in der Atlas-Plattform mit Unterstützung für Paginierung und Filterung.
`atlas://knowledge`	Liste aller Wissenselemente in der Atlas-Plattform mit Unterstützung für Seitennummerierung und Filterung.

Ressourcenvorlagen

Ressourcenname	Beschreibung
`atlas://projects/{projectId}`	Ruft ein einzelnes Projekt anhand seiner eindeutigen Kennung ( `projectId` ) ab.
`atlas://tasks/{taskId}`	Ruft eine einzelne Aufgabe anhand ihrer eindeutigen Kennung ( `taskId` ) ab.
`atlas://projects/{projectId}/tasks`	Ruft alle Aufgaben ab, die zu einem bestimmten Projekt ( `projectId` ) gehören.
`atlas://knowledge/{knowledgeId}`	Ruft ein einzelnes Wissenselement anhand seiner eindeutigen Kennung ( `knowledgeId` ) ab.
`atlas://projects/{projectId}/knowledge`	Ruft alle Wissenselemente ab, die zu einem bestimmten Projekt ( `projectId` ) gehören.

Datenbanksicherung und -wiederherstellung

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

Automatische Backups (Hinweis)

Wichtig: Die automatische Sicherungsfunktion wurde aufgrund von Ineffizienz entfernt. Bitte verwenden Sie den unten beschriebenen manuellen Sicherungsvorgang, um Ihre Daten zu schützen.

Backup-Prozess

Mechanismus : Der Sicherungsvorgang exportiert alle Project , Task und Knowledge zusammen mit ihren Beziehungen in separate JSON-Dateien.
Ausgabe : Jedes Backup erstellt ein mit einem Zeitstempel versehenes Verzeichnis (z. B. atlas-backup-YYYYMMDDHHMMSS ) innerhalb des konfigurierten Backup-Pfades (Standard: ./backups/ ). Dieses Verzeichnis enthält projects.json , tasks.json , knowledge.json und relationships.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.
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. ./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

Integrations