{"id":24941933,"url":"https://github.com/cyanheads/atlas-mcp-server","last_synced_at":"2025-04-07T06:04:22.954Z","repository":{"id":268338556,"uuid":"904031977","full_name":"cyanheads/atlas-mcp-server","owner":"cyanheads","description":"A Model Context Protocol (MCP) server for ATLAS, a Neo4j-powered task management system for LLM Agents - implementing a three-tier architecture (Projects, Tasks, Knowledge) to manage complex workflows.","archived":false,"fork":false,"pushed_at":"2025-03-27T11:54:44.000Z","size":2554,"stargazers_count":111,"open_issues_count":4,"forks_count":18,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-31T05:02:15.516Z","etag":null,"topics":["agents","ai","graph-database","llm","llm-agent","mcp","modelcontextprotocol","neo4j","projects-tasks-knowledge","task-management"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/atlas-mcp-server","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyanheads.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-16T05:55:30.000Z","updated_at":"2025-03-28T10:01:58.000Z","dependencies_parsed_at":"2025-01-10T06:15:32.985Z","dependency_job_id":"c2b93a34-5ab1-47fd-8545-f05c05f0e09e","html_url":"https://github.com/cyanheads/atlas-mcp-server","commit_stats":null,"previous_names":["cyanheads/atlas-mcp-server"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fatlas-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fatlas-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fatlas-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Fatlas-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyanheads","download_url":"https://codeload.github.com/cyanheads/atlas-mcp-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601447,"owners_count":20964864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","graph-database","llm","llm-agent","mcp","modelcontextprotocol","neo4j","projects-tasks-knowledge","task-management"],"created_at":"2025-02-02T18:57:22.727Z","updated_at":"2025-04-07T06:04:22.946Z","avatar_url":"https://github.com/cyanheads.png","language":"TypeScript","funding_links":[],"categories":["Task and Project Management","📚 Projects (1974 total)","Other Tools and Integrations","🤖 AI/ML","TypeScript","\u003ca name=\"TypeScript\"\u003e\u003c/a\u003eTypeScript","Project Management Mcp Servers","MCP Servers"],"sub_categories":["MCP Servers","How to Submit","Knowledge \u0026 Memory"],"readme":"# ATLAS: Task Management System\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.2-blue.svg)](https://www.typescriptlang.org/)\n[![Model Context Protocol](https://img.shields.io/badge/MCP-1.8.0-green.svg)](https://modelcontextprotocol.io/)\n[![Version](https://img.shields.io/badge/Version-2.7.0-blue.svg)](https://github.com/cyanheads/atlas-mcp-server/releases)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Status](https://img.shields.io/badge/Status-Stable-green.svg)]()\n[![GitHub](https://img.shields.io/github/stars/cyanheads/atlas-mcp-server?style=social)](https://github.com/cyanheads/atlas-mcp-server)\n\nATLAS (Adaptive Task \u0026 Logic Automation System) is a task management system for LLM Agents.\n\nBuilt on a three-tier architecture:\n\n```\n                  +------------------------------------------+\n                  |                PROJECT                   |\n                  |------------------------------------------|\n                  | id: string                               |\n                  | name: string                             |\n                  | description: string                      |\n                  | status: string                           |\n                  | urls?: Array\u003c{title: string, url: string}\u003e|\n                  | completionRequirements: string           |\n                  | outputFormat: string                     |\n                  | taskType: string                         |\n                  | createdAt: string                        |\n                  | updatedAt: string                        |\n                  +----------------+-------------------------+\n                            |                    |\n                            |                    |\n                            v                    v\n+----------------------------------+ +----------------------------------+\n|               TASK               | |            KNOWLEDGE             |\n|----------------------------------| |----------------------------------|\n| id: string                       | | id: string                       |\n| projectId: string                | | projectId: string                |\n| title: string                    | | text: string                     |\n| description: string              | | tags?: string[]                  |\n| priority: string                 | | domain: string                   |\n| status: string                   | | citations?: string[]             |\n| assignedTo?: string              | | createdAt: string                |\n| urls?: Array\u003c{title: string,     | |                                  |\n|   url: string}\u003e                  | | updatedAt: string                |\n| tags?: string[]                  | |                                  |\n| completionRequirements: string   | |                                  |\n| outputFormat: string             | |                                  |\n| taskType: string                 | |                                  |\n| createdAt: string                | |                                  |\n| updatedAt: string                | |                                  |\n+----------------------------------+ +----------------------------------+\n```\n\nImplemented as a Model Context Protocol (MCP) server, ATLAS allows LLM agents to interact with project management database, enabling managing projects, tasks, and knowledge items.\n\n\u003e **Important Version Note**: [Version 1.5.4](https://github.com/cyanheads/atlas-mcp-server/releases/tag/v1.5.4) is the last version that uses SQLite as the database. Version 2.0 and onwards has been completely rewritten to use Neo4j, which requires either:\n\u003e\n\u003e - Self-hosting using Docker (docker-compose included in repository)\n\u003e - Using Neo4j AuraDB cloud service: https://neo4j.com/product/auradb/\n\u003e\n\u003e Version 2.5.0 introduces a new 3-node system (Projects, Tasks, Knowledge) that replaces the previous structure.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Project Structure](#project-structure)\n- [Tools](#tools)\n- [Resources](#resources)\n- [Database Backup and Restore](#database-backup-and-restore)\n- [Examples](#examples)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nATLAS implements the Model Context Protocol (MCP), enabling standardized communication between LLMs and external systems through:\n\n- **Clients**: Claude Desktop, IDEs, and other MCP-compatible clients\n- **Servers**: Tools and resources for project, task, and knowledge management\n- **LLM Agents**: AI models that leverage the server's management capabilities\n\n### System Integration\n\nThe Atlas Platform integrates these components into a cohesive system:\n\n- **Project-Task Relationship**: Projects contain tasks that represent actionable steps needed to achieve project goals. Tasks inherit context from their parent project while providing granular tracking of individual work items.\n- **Knowledge Integration**: Both projects and tasks can be enriched with knowledge items, providing team members with necessary information and context.\n- **Dependency Management**: Both projects and tasks support dependency relationships, allowing for complex workflows with prerequisites and sequential execution requirements.\n- **Unified Search**: The platform provides cross-entity search capabilities, allowing users to find relevant projects, tasks, or knowledge based on various criteria.\n\n## Features\n\n### Project Management\n\n- **Comprehensive Tracking:** Manage project metadata, statuses, and rich content (notes, links, etc.) with built-in support for bulk operations.\n- **Dependency \u0026 Relationship Handling:** Automatically validate and track inter-project dependencies.\n\n### Task Management\n\n- **Task Lifecycle Management:** Create, track, and update tasks through their entire lifecycle.\n- **Prioritization \u0026 Categorization:** Assign priority levels and categorize tasks with tags for better organization.\n- **Dependency Tracking:** Establish task dependencies to create structured workflows.\n\n### Knowledge Management\n\n- **Structured Knowledge Repository:** Maintain a searchable repository of project-related information.\n- **Domain Categorization:** Organize knowledge by domain and tags for easy retrieval.\n- **Citation Support:** Track sources and references for knowledge items.\n\n### Graph Database Integration\n\n- **Native Relationship Management:** Leverage Neo4j's ACID-compliant transactions and optimized queries for robust data integrity.\n- **Advanced Search \u0026 Scalability:** Perform property-based searches with fuzzy matching and wildcards while maintaining high performance.\n\n### Unified Search\n\n- **Cross-Entity Search:** Find relevant projects, tasks, or knowledge based on content, metadata, or relationships.\n- **Flexible Query Options:** Support for case-insensitive, fuzzy, and advanced filtering options.\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/cyanheads/atlas-mcp-server.git\ncd atlas-mcp-server\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Configure Neo4j:\n\n```bash\n# Start Neo4j using Docker\ndocker-compose up -d\n```\n\n4. Build the project:\n\n```bash\nnpm run build\n```\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file based on `.env.example`:\n\n```bash\n# Neo4j Configuration\nNEO4J_URI=bolt://localhost:7687\nNEO4J_USER=neo4j\nNEO4J_PASSWORD=password2\n\n# Application Configuration\nLOG_LEVEL=info # debug, info, warn, error\nNODE_ENV=development # development, production\n```\n\n### MCP Client Settings\n\nAdd to your MCP client settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"atlas\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/atlas-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"NEO4J_URI\": \"bolt://localhost:7687\",\n        \"NEO4J_USER\": \"neo4j\",\n        \"NEO4J_PASSWORD\": \"password2\",\n        \"LOG_LEVEL\": \"info\",\n        \"NODE_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\n## Project Structure\n\nThe codebase follows a modular structure:\n\n```\nsrc/\n├── config/          # Configuration management (index.ts)\n├── index.ts         # Main server entry point\n├── mcp/             # MCP server implementation (server.ts)\n│   ├── resources/   # MCP resource handlers (index.ts, types.ts, knowledge/, projects/, tasks/)\n│   └── tools/       # MCP tool handlers (individual tool directories)\n├── services/        # Core application services\n│   └── neo4j/       # Neo4j database services (index.ts, driver.ts, backupRestoreService.ts, etc.)\n├── types/           # Shared TypeScript type definitions (errors.ts, mcp.ts, tool.ts)\n└── utils/           # Utility functions (logger.ts, errorHandler.ts, etc.)\n```\n\n_Note: ID generation logic is primarily located in `src/services/neo4j/helpers.ts`._\n\n## Tools\n\nATLAS provides a comprehensive suite of tools for project, task, and knowledge management, callable via the Model Context Protocol.\n\n### Project Operations\n\n| Tool Name              | Description                              | Key Arguments                                                                                                                                                                                               |\n| :--------------------- | :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `atlas_project_create` | Creates new projects (single/bulk).      | `mode` ('single'/'bulk'), project details (`name`, `description`, `status`, `urls`, `completionRequirements`, `dependencies`, `outputFormat`, `taskType`), `responseFormat` ('formatted'/'json', optional). |\n| `atlas_project_list`   | Lists projects (all/details).            | `mode` ('all'/'details'), `id` (for details), filters (`status`, `taskType`), pagination (`page`, `limit`), includes (`includeKnowledge`, `includeTasks`), `responseFormat` ('formatted'/'json', optional). |\n| `atlas_project_update` | Updates existing projects (single/bulk). | `mode` ('single'/'bulk'), `id`, `updates` object, `responseFormat` ('formatted'/'json', optional). Bulk mode uses `projects` array.                                                                         |\n| `atlas_project_delete` | Deletes projects (single/bulk).          | `mode` ('single'/'bulk'), `id` (single) or `projectIds` array (bulk), `responseFormat` ('formatted'/'json', optional).                                                                                      |\n\n### Task Operations\n\n| Tool Name           | Description                           | Key Arguments                                                                                                                                                                                                                                    |\n| :------------------ | :------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `atlas_task_create` | Creates new tasks (single/bulk).      | `mode` ('single'/'bulk'), `projectId`, task details (`title`, `description`, `priority`, `status`, `assignedTo`, `tags`, `completionRequirements`, `dependencies`, `outputFormat`, `taskType`), `responseFormat` ('formatted'/'json', optional). |\n| `atlas_task_update` | Updates existing tasks (single/bulk). | `mode` ('single'/'bulk'), `id`, `updates` object, `responseFormat` ('formatted'/'json', optional). Bulk mode uses `tasks` array.                                                                                                                 |\n| `atlas_task_delete` | Deletes tasks (single/bulk).          | `mode` ('single'/'bulk'), `id` (single) or `taskIds` array (bulk), `responseFormat` ('formatted'/'json', optional).                                                                                                                              |\n| `atlas_task_list`   | Lists tasks for a specific project.   | `projectId` (required), filters (`status`, `assignedTo`, `priority`, `tags`, `taskType`), sorting (`sortBy`, `sortDirection`), pagination (`page`, `limit`), `responseFormat` ('formatted'/'json', optional).                                    |\n\n### Knowledge Operations\n\n| Tool Name                | Description                                   | Key Arguments                                                                                                                                                                        |\n| :----------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `atlas_knowledge_add`    | Adds new knowledge items (single/bulk).       | `mode` ('single'/'bulk'), `projectId`, knowledge details (`text`, `tags`, `domain`, `citations`), `responseFormat` ('formatted'/'json', optional). Bulk mode uses `knowledge` array. |\n| `atlas_knowledge_delete` | Deletes knowledge items (single/bulk).        | `mode` ('single'/'bulk'), `id` (single) or `knowledgeIds` array (bulk), `responseFormat` ('formatted'/'json', optional).                                                             |\n| `atlas_knowledge_list`   | Lists knowledge items for a specific project. | `projectId` (required), filters (`tags`, `domain`, `search`), pagination (`page`, `limit`), `responseFormat` ('formatted'/'json', optional).                                         |\n\n### Search Operations\n\n| Tool Name              | Description                              | Key Arguments                                                                                                                                                                                           |\n| :--------------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `atlas_unified_search` | Performs unified search across entities. | `value` (search term), `property` (optional), filters (`entityTypes`, `taskType`), options (`caseInsensitive`, `fuzzy`), pagination (`page`, `limit`), `responseFormat` ('formatted'/'json', optional). |\n\n### Research Operations\n\n| Tool Name             | Description                                                                                                   | Key Arguments                                                                                                                                                                                                                                                                             |\n| :-------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `atlas_deep_research` | Initiates a structured deep research process by creating a hierarchical plan within the Atlas knowledge base. | `projectId` (required), `researchTopic` (required), `researchGoal` (required), `scopeDefinition` (optional), `subTopics` (required array with questions and search queries), `researchDomain` (optional), `initialTags` (optional), `planNodeId` (optional), `responseFormat` (optional). |\n\n### Database Operations\n\n| Tool Name              | Description                                                                                   | Key Arguments                                                                                          |\n| :--------------------- | :-------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |\n| `atlas_database_clean` | **Destructive:** Completely resets the database, removing all projects, tasks, and knowledge. | `acknowledgement` (must be set to `true` to confirm), `responseFormat` ('formatted'/'json', optional). |\n\n## Resources\n\nATLAS exposes project, task, and knowledge data through standard MCP resource endpoints.\n\n### Direct Resources\n\n| Resource Name       | Description                                                                              |\n| :------------------ | :--------------------------------------------------------------------------------------- |\n| `atlas://projects`  | List of all projects in the Atlas platform with pagination support.                      |\n| `atlas://tasks`     | List of all tasks in the Atlas platform with pagination and filtering support.           |\n| `atlas://knowledge` | List of all knowledge items in the Atlas platform with pagination and filtering support. |\n\n### Resource Templates\n\n| Resource Name                            | Description                                                                  |\n| :--------------------------------------- | :--------------------------------------------------------------------------- |\n| `atlas://projects/{projectId}`           | Retrieves a single project by its unique identifier (`projectId`).           |\n| `atlas://tasks/{taskId}`                 | Retrieves a single task by its unique identifier (`taskId`).                 |\n| `atlas://projects/{projectId}/tasks`     | Retrieves all tasks belonging to a specific project (`projectId`).           |\n| `atlas://knowledge/{knowledgeId}`        | Retrieves a single knowledge item by its unique identifier (`knowledgeId`).  |\n| `atlas://projects/{projectId}/knowledge` | Retrieves all knowledge items belonging to a specific project (`projectId`). |\n\n## Database Backup and Restore\n\nATLAS provides functionality to back up and restore the Neo4j database content. The core logic resides in `src/services/neo4j/backupRestoreService.ts`.\n\n### Automatic Backups (Note)\n\n**Important:** The automatic backup functionality has been removed due to inefficiency. The call to `triggerBackgroundBackup` in `src/services/neo4j/driver.ts` is commented out with a note indicating it was removed. Please use the manual backup process described below to protect your data.\n\n### Backup Process\n\n- **Mechanism**: The backup process exports all `Project`, `Task`, and `Knowledge` nodes, along with their relationships, into separate JSON files.\n- **Output**: Each backup creates a timestamped directory (e.g., `atlas-backup-YYYYMMDDHHMMSS`) within the configured backup path (default: `./atlas-backups/`). This directory contains `projects.json`, `tasks.json`, `knowledge.json`, and `relationships.json`.\n- **Manual Backup**: You can trigger a manual backup using the provided script:\n  ```bash\n  npm run db:backup\n  ```\n  This command executes `scripts/db-backup.ts`, which calls the `exportDatabase` function.\n\n### Restore Process\n\n- **Mechanism**: The restore process first completely clears the existing Neo4j database. Then, it imports nodes and relationships from the JSON files located in the specified backup directory.\n- **Warning**: Restoring from a backup is a destructive operation. **It will overwrite all current data in your Neo4j database.**\n- **Manual Restore**: To restore the database from a backup directory, use the import script:\n  ```bash\n  npm run db:import \u003cpath_to_backup_directory\u003e\n  ```\n  Replace `\u003cpath_to_backup_directory\u003e` with the actual path to the backup folder (e.g., `./atlas-backups/atlas-backup-20250326120000`). This command executes `scripts/db-import.ts`, which calls the `importDatabase` function.\n- **Relationship Handling**: The import process attempts to recreate relationships based on the `id` properties stored within the nodes during export. Ensure your nodes have consistent `id` properties for relationships to be restored correctly.\n\n## Examples\n\nThe `examples/` directory contains practical examples demonstrating various features of the ATLAS MCP Server.\n\n- **Backup Example**: Located in `examples/backup-example/`, this shows the structure and format of the JSON files generated by the `npm run db:backup` command. See the [Examples README](./examples/README.md) for more details.\n- **Deep Research Example**: Located in `examples/deep-research-example/`, this demonstrates the output and structure generated by the `atlas_deep_research` tool. It includes a markdown file (`covington_community_grant_research.md`) summarizing the research plan and a JSON file (`full-export.json`) containing the raw data exported from the database after the research plan was created. See the [Examples README](./examples/README.md) for more details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes with a descriptive message\n4. Push to the branch\n5. Create a Pull Request\n\nFor bugs and feature requests, please create an issue.\n\n## License\n\nApache License 2.0\n\n---\n\n\u003cdiv align=\"center\"\u003e\nBuilt with the Model Context Protocol\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyanheads%2Fatlas-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyanheads%2Fatlas-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyanheads%2Fatlas-mcp-server/lists"}