atlas-mcp-server

Implements a three-tier data model where Projects contain Tasks and Knowledge entities as distinct node types in Neo4j, with relationship edges defining containment and dependency chains. Uses Cypher query language for traversal and aggregation across the hierarchy, enabling agents to structure complex workflows with nested task dependencies and associated knowledge artifacts without flattening the organizational structure.

Exposes project, task, and knowledge management operations as MCP tools with standardized input schemas and response formatting. Each tool (create, read, update, delete, list) maps to Neo4j service methods that validate inputs via Zod schemas, execute Cypher mutations/queries, and return structured JSON responses. Tools are discoverable by MCP clients and include detailed descriptions for LLM agent planning.

Implements consistent error handling with typed error classes (ValidationError, NotFoundError, DatabaseError, etc.) and structured logging using Winston or Pino. All errors include context (request ID, operation type, entity ID) and are logged with appropriate severity levels. HTTP responses include error codes and messages; MCP responses include error details in the response object.

Uses Zod to validate and parse environment variables at startup, ensuring all required configuration is present and correctly typed before the server starts. Supports configuration for database connection, server ports, authentication secrets, logging levels, and feature flags. Provides clear error messages if configuration is invalid or missing.

Provides a single search interface that queries across all three entity types (Projects, Tasks, Knowledge) using Neo4j full-text indexes and optional semantic search via embeddings. Accepts a search query string, executes Cypher queries against indexed properties, and returns ranked results grouped by entity type with relevance scores. Supports filtering by project, status, and other metadata.

Implements a research workflow where an LLM agent iteratively formulates research questions, searches the knowledge base and external sources, synthesizes findings, and refines queries based on results. The tool manages conversation history, tracks research progress, and stores findings back into the Knowledge tier. Uses chain-of-thought reasoning to decompose complex research goals into sub-questions.

Exposes projects, tasks, and knowledge items as MCP resources (read-only data endpoints) that clients can subscribe to for real-time updates or fetch on-demand. Resources are formatted as text or JSON and include metadata about the entity, relationships, and child entities. Enables agents to maintain context about the current project/task state without invoking tools.

Maintains a request context (trace ID, agent ID, operation type) throughout the lifecycle of MCP operations, enabling correlation of related database mutations and tool invocations. Uses Node.js AsyncLocalStorage to propagate context without explicit parameter passing. Logs all operations with context metadata for debugging and audit trails.

All MCP tools and database operations use Zod schemas to validate and parse inputs before execution. Schemas define required fields, types, constraints (min/max length, enum values), and transformations. Validation failures return structured error messages with field-level details. Enables type-safe operations and prevents invalid data from reaching the database.

Implements the MCP server specification with two transport mechanisms: stdio for local clients (IDE extensions, local agents) and HTTP for remote clients (web applications, cloud agents). Stdio transport uses JSON-RPC over stdin/stdout; HTTP transport uses REST-like endpoints with JWT authentication. Single server instance can serve both transports simultaneously.

Provides a browser-based interface for viewing and managing projects, tasks, and knowledge items. Displays the hierarchical structure as a tree or graph, allows drag-and-drop task organization, and provides forms for creating/editing entities. UI communicates with the ATLAS server via HTTP transport and MCP tools. Includes real-time updates via WebSocket subscriptions.

Provides database setup scripts that create the Neo4j schema (node labels, relationship types, indexes, constraints) required by ATLAS. Includes migration scripts for schema updates and database reset utilities for development. Scripts are idempotent and can be run multiple times without side effects. Supports both local Neo4j instances and cloud deployments (Neo4j Aura).