Xurgo Atlas

Xurgo Atlas is a standalone, local-first documentation and project-context service for AI-assisted development. It gives developers and MCP-capable AI clients a governed way to read project docs, find context, and propose documentation changes with an audit trail.

Atlas complements your repository. It does not replace Git, your source tree, your issue tracker, or your AI client.

Quick Start

Install Xurgo Atlas globally for the normal CLI workflow:

npm install -g xurgo-atlas

Verify the CLI, initialize a project, start the local daemon, and print JSON config for MCP clients:

xurgo-atlas --version
xurgo-atlas --help
xurgo-atlas init --project-id my-project
xurgo-atlas daemon start
xurgo-atlas mcp-config --json

If you want to try Atlas without installing it first, use npx xurgo-atlas .... For project-local automation, install it as a dev dependency with npm install -D xurgo-atlas.

init creates or preserves a local .xurgo-atlas/project.json marker for the project folder. After that, normal commands can run from the project root or a nested subdirectory without repeating --project-id or --project-root.

xurgo-atlas doctor provides a bounded, read-only diagnostic snapshot of the current Atlas setup.

Optional init templates can create missing starter docs for common project types:

xurgo-atlas init --templates
xurgo-atlas init --template mcp-server --project-id my-project

Templates are documentation templates, not application scaffolds, and existing docs are preserved.

What Atlas Helps With

Atlas helps an AI client or developer:

• discover the docs and artifacts Atlas manages for a project
• read focused sections or context packs instead of opening every file
• search Atlas-managed docs with local lexical search
• inspect which project folder Atlas is currently bound to before writing
• propose, preview, commit, and export governed documentation changes
• register approved project artifacts through guarded proposal and commit flows
• keep a documented history of managed-doc and artifact-registration changes

Atlas is optional. Use it when a project wants governed docs and durable project context through a CLI or MCP server.

What Atlas Is Not

Atlas is not:

• an agent runtime
• a required dependency for another product
• a workspace manager
• a session or run store
• a general memory database
• a semantic or vector retrieval service today
• a lock server today
• a replacement for Git or repository truth

MCP Client Setup

The current preferred MCP workflow is the local daemon HTTP endpoint:

xurgo-atlas daemon start
xurgo-atlas mcp-config --json

The JSON output tells MCP clients how to connect to http://127.0.0.1:3737/mcp by default and includes safety information about the project folder Atlas is bound to. For humans, xurgo-atlas mcp-config prints a readable setup summary.

After connecting, trust the tools available from the connected Atlas server through live MCP discovery, especially tools/list. Static docs and local source can drift from an already-running daemon.

xurgo-atlas server remains available for legacy or direct stdio integrations, but HTTP daemon mode is the normal path for MCP clients.

How It Works

Atlas keeps its stored documentation and audit history outside your project tree, using configurable local data directories. Your repository remains the source of truth for code and normal Git history.

Managed documentation changes follow a guarded lifecycle:

read -> propose -> preview -> commit -> export