ATLAS: Task Management System

ATLAS：タスク管理システム

ATLAS（Adaptive Task & Logic Automation System）は、LLM エージェント向けのプロジェクト、ナレッジ、タスク管理システムです。

3ノードアーキテクチャを基盤としています。

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

Model Context Protocol（MCP）サーバーとして実装された ATLAS を使うと、LLM エージェントはプロジェクト管理データベースとやり取りし、プロジェクト、タスク、ナレッジ項目を管理できます。

バージョンに関する重要なお知らせ：Version 1.5.4は、データベースとして SQLite を使用する最後のバージョンです。Version 2.0以降は Neo4j を使用するように全面的に書き換えられており、次のいずれかが必要です。

• Docker を使ったセルフホスト（リポジトリに docker-compose が含まれています）
• Neo4j AuraDB クラウドサービスの利用：https://neo4j.com/product/auradb/

Version 2.5.0では、従来の構造に代わる新しい3ノードシステム（Projects、Tasks、Knowledge）が導入されました。

目次

• 概要
• 機能
• インストール
• サーバーの起動
• Web UI（実験的）
• 設定
• プロジェクト構成
• ツール
• リソース
• データベースのバックアップと復元
• 使用例
• ライセンス

概要

ATLAS は Model Context Protocol（MCP）を実装しており、次の要素を通じて LLM と外部システム間の標準化された通信を可能にします。

• クライアント：Claude Desktop、IDE、その他の MCP 互換クライアント
• サーバー：プロジェクト、タスク、ナレッジ管理のためのツールとリソース
• LLM エージェント：サーバーの管理機能を活用する AI モデル

システム統合

Atlas Platform は、以下のコンポーネントを統合して一貫性のあるシステムを構築します。

• プロジェクトとタスクの関係：プロジェクトには、目標の達成に必要な実行可能な手順を表すタスクが含まれます。タスクは親プロジェクトからコンテキストを引き継ぎながら、個々の作業項目を詳細に追跡できます。
• ナレッジの統合：プロジェクトとタスクの両方にナレッジ項目を追加し、チームメンバーに必要な情報とコンテキストを提供できます。
• 依存関係の管理：プロジェクトとタスクの両方で依存関係を設定でき、前提条件や順次実行の要件を伴う複雑なワークフローに対応できます。
• 統合検索：プラットフォームは複数のエンティティを横断して検索でき、さまざまな条件に基づいて関連するプロジェクト、タスク、ナレッジを見つけられます。

機能

機能分野	主な機能
プロジェクト管理	- 包括的な追跡：一括操作のサポートが組み込まれており、プロジェクトのメタデータ、ステータス、リッチコンテンツ（メモ、リンクなど）を管理できます。 - 依存関係と関連性の管理：プロジェクト間の依存関係を自動的に検証し、追跡します。
タスク管理	- タスクのライフサイクル管理：ライフサイクル全体を通じて、タスクの作成、追跡、更新ができます。 - 優先順位付けと分類：優先度を割り当て、タグでタスクを分類して整理しやすくします。 - 依存関係の追跡：タスクの依存関係を設定し、構造化されたワークフローを作成します。
ナレッジ管理	- 構造化されたナレッジリポジトリ：プロジェクト関連情報を検索可能なリポジトリで管理します。 - ドメイン別の分類：ドメインとタグでナレッジを整理し、簡単に検索できるようにします。 - 引用のサポート：ナレッジ項目の出典と参照を追跡します。
グラフデータベースとの連携	- ネイティブな関連性管理：Neo4j の ACID 準拠トランザクションと最適化されたクエリを活用し、堅牢なデータ整合性を実現します。 - 高度な検索とスケーラビリティ：高いパフォーマンスを維持しながら、ファジーマッチングとワイルドカードを使ったプロパティベースの検索を実行します。
統合検索	- エンティティ横断検索：コンテンツ、メタデータ、関連性に基づいて、関連するプロジェクト、タスク、ナレッジを検索します。 - 柔軟なクエリオプション：大文字と小文字を区別しない検索、ファジー検索、高度なフィルタリングオプションをサポートします。

インストール

1. リポジトリをクローンします：

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

2. 依存関係をインストールします：

   npm install
   

3. Neo4j を設定します： Neo4j インスタンスが稼働しており、アクセス可能であることを確認してください。付属の Docker 設定を使用して、次のように起動できます。

   docker-compose up -d
   

   .env ファイルを Neo4j の接続情報で更新します（設定を参照）。

4. プロジェクトをビルドします：

   npm run build
   

サーバーの実行

ほとんどの MCP クライアントはサーバーを自動的に実行しますが、テストや開発の目的で、次のコマンドを使って手動で実行することもできます。

ATLAS MCP Server は、通信に複数のトランスポート方式をサポートしています。

• 標準入出力（stdio）： これはデフォルトのモードで、通常、ローカルの MCP クライアント（IDE 拡張機能など）との直接連携に使用されます。

  npm run start:stdio
  

  これは MCP_TRANSPORT_TYPE=stdio 設定を使用します。

• ストリーム可能 HTTP： このモードでは、サーバーが HTTP 経由で MCP リクエストを待ち受けるため、リモートクライアントやウェブベースの連携に適しています。

  npm run start:http
  

  これは MCP_TRANSPORT_TYPE=http 設定を使用します。サーバーは .env ファイルで定義されたホストとポート（例：MCP_HTTP_HOST と MCP_HTTP_PORT。デフォルトは 127.0.0.1:3010）で待ち受けます。リモートからアクセスする場合は、ファイアウォールで接続が許可されていることを確認してください。

Web UI（実験的）

プロジェクト、タスク、ナレッジの詳細を表示するための基本的な Web UI を利用できます。

• UI を開く：

  • ブラウザーで UI を直接開くには、ターミナルで次のコマンドを実行します。

    npm run webui
    

• 機能：

  • Web UI のスクリーンショット例はこちらで確認できます。

設定

環境変数

環境変数は、MCP クライアントのクライアント設定、またはローカル開発の場合はプロジェクトルートの .env ファイルで設定してください。

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

利用可能な環境変数、その説明、デフォルト値については src/config/index.ts を参照してください。

MCP クライアントの設定

MCP クライアントの設定方法は、クライアント自体と選択したトランスポートの種類によって異なります。プロジェクトルートにある mcp.json ファイルを使って、mcp-inspector など一部のクライアントのサーバー設定を定義できます。必要に応じて更新してください。

Stdio トランスポート（設定例）：

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

Streamable HTTP（設定例）： クライアントが Streamable HTTP 経由で MCP サーバーに接続できる場合は、クライアント設定でサーバーのエンドポイント（例：http://localhost:3010/mcp）を指定します。

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

注： サーバーがクライアントの現在の作業ディレクトリにない場合は、クライアントコマンドの設定で args に必ず絶対パスを使用してください。クライアントの env ブロックにある MCP_AUTH_SECRET_KEY は説明用のものです。クライアントとサーバー間の実際のトークン処理は、クライアントの機能とサーバーの認証メカニズム（例：Authorization ヘッダーでの JWT の送信）によって異なります。

プロジェクト構成

コードベースはモジュール構造になっています。

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)

ツール

ATLAS は、Model Context Protocol 経由で呼び出せる、プロジェクト、タスク、ナレッジ管理のための包括的なツール群を提供します。

プロジェクト操作

ツール名	説明	主な引数
atlas_project_create	新しいプロジェクトを作成します（単一／一括）。	mode（'single'／'bulk'）、id（単一モードでクライアントが生成する任意のID）、プロジェクトの詳細（name、description、status、urls、completionRequirements、dependencies、outputFormat、taskType）。一括モードでは、projects（プロジェクトオブジェクトの配列）を使用します。responseFormat（'formatted'／'json'、任意、デフォルト：'formatted'）。
atlas_project_list	プロジェクトを一覧表示します（すべて／詳細）。	mode（'all'／'details'、デフォルト：'all'）、id（詳細モード用）、フィルター（status、taskType）、ページネーション（page、limit）、含める項目（includeKnowledge、includeTasks）、responseFormat（'formatted'／'json'、任意、デフォルト：'formatted'）。
atlas_project_update	既存のプロジェクトを更新します（単一／一括）。	mode（'single'／'bulk'）、id（単一モード用）、updatesオブジェクト。一括モードでは、projects（それぞれにidとupdatesを含むオブジェクトの配列）を使用します。responseFormat（'formatted'／'json'、任意、デフォルト：'formatted'）。
atlas_project_delete	プロジェクトを削除します（単一／一括）。	mode（'single'／'bulk'）、id（単一モード用）、またはprojectIds（一括モード用の配列）。responseFormat（'formatted'／'json'、任意、デフォルト：'formatted'）。

タスク操作

ツール名	説明	主な引数
atlas_task_create	新しいタスクを作成します（単一／一括）。	mode（'single'／'bulk'）、id（省略可能なクライアント生成 ID）、projectId、タスクの詳細（title、description、priority、status、assignedTo、urls、tags、completionRequirements、dependencies、outputFormat、taskType）。一括モードでは、tasks（タスクオブジェクトの配列）を使用します。responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。
atlas_task_update	既存のタスクを更新します（単一／一括）。	mode（'single'／'bulk'）、id（単一モードの場合）、updates オブジェクト。一括モードでは、tasks（それぞれ id と updates を含むオブジェクトの配列）を使用します。responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。
atlas_task_delete	タスクを削除します（単一／一括）。	mode（'single'／'bulk'）、id（単一モードの場合）または taskIds（一括モードの場合の配列）。responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。
atlas_task_list	特定のプロジェクトのタスクを一覧表示します。	projectId（必須）、フィルター（status、assignedTo、priority、tags、taskType）、並べ替え（sortBy、sortDirection）、ページネーション（page、limit）、responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。

ナレッジ操作

ツール名	説明	主な引数
atlas_knowledge_add	ナレッジ項目を追加します（単一／一括）。	mode（'single'／'bulk'）、id（省略可能なクライアント生成 ID）、projectId、ナレッジの詳細（text、tags、domain、citations）。一括モードでは、knowledge（ナレッジオブジェクトの配列）を使用します。responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。
atlas_knowledge_delete	ナレッジ項目を削除します（単一／一括）。	mode（'single'／'bulk'）、id（単一モードの場合）またはknowledgeIds（一括モードの場合の配列）。responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。
atlas_knowledge_list	特定のプロジェクトのナレッジ項目を一覧表示します。	projectId（必須）、フィルター（tags、domain、search）、ページネーション（page、limit）、responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。

検索操作

ツール名	説明	主な引数
atlas_unified_search	エンティティを横断して統合検索を実行します。	value（検索語、必須）、property（省略可能：指定するとこのプロパティを正規表現で検索し、省略すると全文検索を実行）、フィルター（entityTypes、taskType、assignedToUserId）、オプション（caseInsensitive（デフォルト：true、正規表現の場合）、fuzzy（デフォルト：false、正規表現の「contains」または全文検索の Lucene ファジー検索の場合））、ページネーション（page、limit）、responseFormat（'formatted'／'json'、省略可能、デフォルト：'formatted'）。

リサーチ業務

ツール名	説明	主な引数
atlas_deep_research	Atlas ナレッジベース内に階層型の計画を作成し、体系的な詳細リサーチプロセスを開始します。	projectId（必須）、researchTopic（必須）、researchGoal（必須）、scopeDefinition（任意）、subTopics（必須のオブジェクト配列。各オブジェクトには、question（必須）、initialSearchQueries（任意の配列）、nodeId（任意）、priority（任意）、assignedTo（任意）、initialStatus（任意、デフォルト：'todo'）を指定します）、researchDomain（任意）、initialTags（任意）、planNodeId（任意）、createTasks（任意、デフォルト：true）、responseFormat（'formatted'/'json'、任意、デフォルト：'formatted'）。

データベース操作

ツール名	説明	主な引数
atlas_database_clean	破壊的操作： データベースを完全にリセットし、すべてのプロジェクト、タスク、ナレッジを削除します。	acknowledgement（確認するにはtrueに設定する必要があります。必須）、responseFormat（'formatted'/'json'、任意、デフォルト：'formatted'）。

リソース

ATLAS は、標準の MCP リソースエンドポイントを通じてプロジェクト、タスク、ナレッジのデータを公開します。

直接リソース

リソース名	説明
atlas://projects	Atlas プラットフォーム内の全プロジェクトの一覧。ページネーションに対応しています。
atlas://tasks	Atlas プラットフォーム内の全タスクの一覧。ページネーションとフィルタリングに対応しています。
atlas://knowledge	Atlas プラットフォーム内の全ナレッジ項目の一覧。ページネーションとフィルタリングに対応しています。

リソーステンプレート

リソース名	説明
atlas://projects/{projectId}	一意の識別子（projectId）で単一のプロジェクトを取得します。
atlas://tasks/{taskId}	一意の識別子（taskId）で単一のタスクを取得します。
atlas://projects/{projectId}/tasks	特定のプロジェクト（projectId）に属するすべてのタスクを取得します。
atlas://knowledge/{knowledgeId}	一意の識別子（knowledgeId）で単一のナレッジ項目を取得します。
atlas://projects/{projectId}/knowledge	特定のプロジェクト（projectId）に属するすべてのナレッジ項目を取得します。

データベースのバックアップと復元

ATLAS は、Neo4j データベースの内容をバックアップおよび復元する機能を提供します。中核となるロジックは src/services/neo4j/backupRestoreService.ts にあります。

バックアッププロセス

• 仕組み：バックアッププロセスでは、すべての Project、Task、Knowledge ノードとその関係を個別の JSON ファイルにエクスポートします。すべてのデータを含む full-export.json も作成されます。
• 出力：バックアップごとに、設定されたバックアップパス（デフォルト：./atlas-backups/）内にタイムスタンプ付きのディレクトリ（例：atlas-backup-YYYYMMDDHHMMSS）が作成されます。このディレクトリには projects.json、tasks.json、knowledge.json、relationships.json、full-export.json が含まれます。
• 手動バックアップ：次のスクリプトを使用して、手動でバックアップを実行できます。

  npm run db:backup
  

  このコマンドは src/services/neo4j/backupRestoreService/scripts/db-backup.ts を実行し、exportDatabase 関数を呼び出します。

復元プロセス

• 仕組み：復元プロセスでは、まず既存の Neo4j データベースを完全に消去します。次に、指定したバックアップディレクトリにある JSON ファイルからノードと関係をインポートします。full-export.json がある場合は、そちらが優先されます。
• 警告：バックアップからの復元は破壊的な操作です。Neo4j データベースの現在のデータはすべて上書きされます。
• 手動復元：バックアップディレクトリからデータベースを復元するには、インポートスクリプトを使用します。

  npm run db:import <path_to_backup_directory>
  

  <path_to_backup_directory> をバックアップフォルダーの実際のパス（例：./atlas-backups/atlas-backup-20250326120000）に置き換えてください。このコマンドは src/services/neo4j/backupRestoreService/scripts/db-import.ts を実行し、importDatabase 関数を呼び出します。
• 関係の処理：インポートプロセスでは、エクスポート時にノードに保存された id プロパティに基づいて、関係の再作成を試みます。関係を正しく復元できるよう、ノードの id プロパティに一貫性があることを確認してください。

例

examples/ ディレクトリには、ATLAS MCP Server のさまざまな機能を紹介する実践的な例が含まれています。

• バックアップの例：examples/backup-example/ にあり、npm run db:backup コマンドで生成される JSON ファイルの構造と形式を示しています。詳細については、例の README を参照してください。
• ディープリサーチの例：examples/deep-research-example/ にあり、atlas_deep_research ツールで生成される出力と構造を示しています。調査計画をまとめた Markdown ファイル（covington_community_grant_research.md）と、調査計画の作成後にデータベースからエクスポートされた生データを含む JSON ファイル（full-export.json）が含まれています。詳細については、例の README を参照してください。

ライセンス

Apache License 2.0

---