ATLAS MCP Server

repository·main·Indexed 19 days ago

https://github.com/cyanheads/atlas-mcp-server

Adaptive Task & Logic Automation System (ATLAS) is an MCP server that enables LLM agents to manage projects, tasks, and knowledge using a Neo4j-backed three-tier architecture. It provides tools for project and task operations, knowledge management, unified search, and deep research, supporting both stdio and HTTP transport mechanisms.

Tokens
29.9K
Snippets
84
Records
114
Agent score
66%

What's inside atlas-mcp-server

  1. Overview of ATLAS Architecture

    main

    ATLAS (Adaptive Task & Logic Automation System) is a project, knowledge, and task management system designed for LLM Agents. It is implemented as a Model Context Protocol (MCP) server, allowing AI models to manage structured data through a 3-node architecture.

    The 3-Node Model

    • Project: The top-level container for metadata, status, completion requirements, and output formats.
    • Task: Actionable steps belonging to a project. Tasks inherit project context and support priority, status, and dependency tracking.
    • Knowledge: A searchable repository of information linked to projects or tasks, supporting domain categorization and citations.

    System Integration

    • Relationships: Projects contain tasks; both projects and tasks can be enriched with knowledge items.
    • Dependencies: Both projects and tasks support dependency relationships for complex workflows.
    • Search: A unified search capability allows finding projects, tasks, or knowledge via content, metadata, or relationships.
    +-------------------------------------------+
                      |                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                 | |                                  |
    +----------------------------------+ +----------------------------------+
  2. Understand the Atlas MCP Server backup file structure

    main

    The backup process generates JSON files that capture the state of your project. The exported data typically includes:

    • tasks.json: A collection of all project tasks, including their metadata, status, and requirements.
    • Knowledge Data: Information regarding project knowledge, including associated context and relationships.
    • Project Configuration: The settings and configuration information used by the server.
  3. Understand the ATLAS Project Structure

    main

    The ATLAS codebase is organized into several functional modules:

    • src/config/: Manages configuration via index.ts.
    • src/index.ts: The main server entry point.
    • src/mcp/: Contains the MCP server implementation, including resources/ (handlers for knowledge, projects, and tasks) and tools/ (individual tool handlers).
    • src/services/: Core application logic, including neo4j/ for database operations and backups.
    • src/types/: Shared TypeScript definitions for errors, MCP, and tools.
    • src/utils/: Internal utilities like logging, error handling, and sanitization.
  4. Run the ATLAS MCP Server

    main

    ATLAS supports multiple transport mechanisms for communication with MCP clients:

    Standard I/O (stdio)

    This is the default mode for local integration (e.g., with IDE extensions or Claude Desktop). It uses the MCP_TRANSPORT_TYPE=stdio setting.

    npm run start:stdio

    Streamable HTTP

    This mode allows the server to listen for requests over HTTP, suitable for remote clients or web-based integrations. It uses the MCP_TRANSPORT_TYPE=http setting. The server listens on the host and port defined in your .env file (defaults to 127.0.0.1:3010).

    npm run start:http
    npm run start:stdio
    # or
    npm run start:http
  5. Perform deep research using atlas_deep_research

    main

    You can use the atlas_deep_research tool to conduct comprehensive research tasks. This tool is designed to gather information from various sources, including government programs, private foundations, and community organizations.

    When prompting for deep research, you should specify:

    • The specific scope of the research (e.g., grant opportunities for a specific region or project type).
    • Priority criteria (e.g., application deadlines, eligibility requirements, funding amounts).
    • Preferred tools for augmentation (e.g., using perplexity for search-augmented generation or firecrawl for web scraping).
    • Instructions for database management (e.g., clearing the database before starting or keeping it up to date).
    • The desired output location for the final report.

    Example prompt structure:

    # Research Task: [Topic]
    
    Conduct research on [Subject] using atlas_deep_research. Focus on [Specific Details].
    
    Research should prioritize:
    - [Priority 1]
    - [Priority 2]
    
    Use the perplexity search tool for LLM augmented searching and firecrawl tools for web scraping. Keep the atlas db completely up to date. 
    
    Start by clearing the db.
    # Grant Research Task: Covington, KY Community Projects
    
    Conduct comprehensive research on publicly available grants for solo-owned community projects in Covington, Kentucky using atlas_deep_research to gather information. Focus on funding opportunities specifically suitable for individual owners of community gardens and similar local initiatives. Identify grant programs from government sources (federal, state, and local), private foundations, and community organizations that support urban agriculture and neighborhood improvement projects.
    
    Research should prioritize:
    
    - Current open application periods and upcoming deadlines
    - Grant amounts and funding cycles
    - Eligibility requirements specific to individual applicants rather than organizations
    - Any special programs targeting the Covington area or Northern Kentucky region
    - Application processes and documentation requirements
    - Past successful community garden projects in the area
    
    Include information on matching grant opportunities and any technical assistance programs available to support the application process.
    
    Perform extensive research and provide a detailed report on your findings in /Users/casey/Developer/github/atlas-mcp-agent/workspace.
    
    Use the perplexity search tool for LLM augmented searching (search-augmented-generation); use the firecrawl tools for web scraping when necessary. Keep the atlas db completely up to date with all details.
    
    Perform extensive research. Include specific details about the grants. Include details on how to apply for the grants.
    
    Start by clearing the db.
  6. Configure MCP Client for Stdio Transport

    main

    To use the ATLAS MCP server via stdio transport, configure your client (e.g., mcp-inspector) with a command pointing to the server's entry point. Ensure you use absolute paths for the args and provide the necessary environment variables in the env block.

    {
      "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"
          }
        }
      }
    }
  7. Configure MCP Client for HTTP Transport

    main

    To use the ATLAS MCP server via http transport, set MCP_TRANSPORT_TYPE to http and provide the host and port. If authentication is enabled on the server, you may need to provide an MCP_AUTH_SECRET_KEY in the client's environment block, though actual token handling depends on your client's ability to send headers (e.g., JWT in Authorization).

    {
      "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" 
          }
        }
      }
    }
  8. Restore the Neo4j database from a backup

    main

    ⚠️ Warning

    Restoring from a backup is a destructive operation. It will completely clear the existing Neo4j database and overwrite all current data with the contents of the backup.

    Process

    The restore process imports nodes and relationships from the JSON files in the specified directory, prioritizing full-export.json if it exists. It attempts to recreate relationships using the id properties stored in the nodes.

    To restore the database, use the import script and provide the path to your backup directory:

    npm run db:import <path_to_backup_directory>

    Example:

    npm run db:import ./atlas-backups/atlas-backup-20250326120000
  9. Explore ATLAS feature examples

    main

    The examples/ directory provides practical implementations of ATLAS features:

    • Backup Example (examples/backup-example/): Demonstrates the structure and format of the JSON files generated during a database backup.
    • Deep Research Example (examples/deep-research-example/): Shows the output of the atlas_deep_research tool, including a generated markdown research summary and the resulting full-export.json data.
  10. Install and Build ATLAS MCP Server

    main

    Follow these steps to set up the ATLAS MCP server locally:

    1. Clone the repository:
      git clone https://github.com/cyanheads/atlas-mcp-server.git
      cd atlas-mcp-server
    2. Install dependencies:
      npm install
    3. Configure Neo4j: ATLAS v2.0+ requires a Neo4j instance. You can use the included Docker configuration:
      docker-compose up -d
      Ensure you update your .env file with the correct Neo4j connection details.
    4. Build the project:
      npm run build
    git clone https://github.com/cyanheads/atlas-mcp-server.git
    cd atlas-mcp-server
    npm install
    docker-compose up -d
    npm run build
  11. Backup Atlas MCP Server data

    main

    You can export your project's knowledge, tasks, and configuration into JSON format for external storage, sharing, or analysis. This is useful for data portability, disaster recovery, or migration.

    To perform a backup, navigate to your Atlas MCP Server project root directory and execute the backup script via npm.

    npm run db:backup