atlas-mcp-server
CLAUDE.md477 starsChanged 18 months agoApache-2.0View on GitHub
ATLAS is an MCP (Model Context Protocol) server with a three-tier Neo4j-backed architecture: Transport Layer (src/mcp/transports/): MCP Layer (src/mcp/): Data Layer (src/services/neo4j/): Three-Tier Data Model: Environment variables are validated via Zod schema in src/config/index.ts. Key settings: Database: NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD Transport: MCP_TRANSPORT_TYPE (stdio/http), MCP_HTTP_PORT (3010) Logging: MCP_LOG_LEVEL (debug), LOGS_DIR (./logs) Backup: BACKUP_FILE_DIR (./atlas-backups), BACKUP_MAX_COUNT (10) Neo4j constraints and indexes are auto-created on startup. Core node types: No formal test framework detected. Use:
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 73
All tools support both single and bulk operations via mode parameter
- Distinctive: line 92
No formal test framework detected.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Essential Development Commands
Build and Development
npm run build- Build the TypeScript project and make executablenpm run dev- Watch mode for TypeScript compilationnpm run rebuild- Clean and rebuild project completelynpm run format- Format code with Prettier
Database Operations
npm run db:backup- Create database backup with timestamped directorynpm run db:import <backup_path>- Restore database from backup (destructive)docker-compose up -d- Start Neo4j databasedocker-compose down- Stop Neo4j database
Running the Server
npm run start:stdio- Run with stdio transport (default for MCP clients)npm run start:http- Run with HTTP transport on localhost:3010npm run inspector- Run MCP inspector for debugging
Testing and Quality
npm run webui- Open basic web UI for viewing datanpm run tree- Generate project structure documentation
Core Architecture
ATLAS is an MCP (Model Context Protocol) server with a three-tier Neo4j-backed architecture:
Transport Layer (src/mcp/transports/):
stdioTransport.ts- Direct stdio communication (default)httpTransport.ts- HTTP server with authentication/rate limiting
MCP Layer (src/mcp/):
server.ts- Main MCP server setup, tool/resource registrationtools/- MCP tool implementations (15 total tools)resources/- MCP resource handlers for direct data access
Data Layer (src/services/neo4j/):
- Core services:
projectService.ts,taskService.ts,knowledgeService.ts searchService.ts- Unified search across all entitiesbackupRestoreService.ts- Database backup/restore operations
Three-Tier Data Model:
PROJECT (top-level containers)
├── TASK (actionable items within projects)
├── KNOWLEDGE (information/context for projects)
└── DEPENDENCIES (relationships between entities)Configuration
Environment variables are validated via Zod schema in src/config/index.ts. Key settings:
Database: NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD
Transport: MCP_TRANSPORT_TYPE (stdio/http), MCP_HTTP_PORT (3010)
Logging: MCP_LOG_LEVEL (debug), LOGS_DIR (./logs)
Backup: BACKUP_FILE_DIR (./atlas-backups), BACKUP_MAX_COUNT (10)
Key Implementation Notes
- All tools support both single and bulk operations via
modeparameter - Comprehensive input validation using Zod schemas per tool
- Request context tracking for operations (
src/utils/internal/requestContext.ts) - Structured logging with Winston (
src/utils/internal/logger.ts) - Backup/restore creates timestamped directories with JSON exports
- Rate limiting and authentication available for HTTP transport
- LLM provider integration available via OpenRouter (
src/services/llm-providers/)
Database Schema
Neo4j constraints and indexes are auto-created on startup. Core node types:
Projectnodes withidproperty (unique constraint)Tasknodes withidproperty, linked to projects viaBELONGS_TOKnowledgenodes withidproperty, linked to projects viaBELONGS_TODEPENDS_ONrelationships for dependency tracking
Testing & Development
No formal test framework detected. Use:
npm run inspectorfor MCP protocol testing- Manual testing via stdio/HTTP transports
- Database backup/restore for data safety during development
- Web UI for visual data verification
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

