Astrograph is a local MCP server for AI agents.
You add it to a repo, run one command to generate MCP config, and let your IDE consume query_code, find_files, and related retrieval tools.

Why this exists

So your AI tools can inspect the right file, the right symbol, and the right context — fast and with clear freshness signals.

Quick start (recommended)

1) Install

Use dependency-based setup if you want astrograph in package scripts:

npm install -D @mortenbroesby/astrograph

Or install globally:

npm install -g @mortenbroesby/astrograph

2) Configure MCP (default: Copilot)

astrograph init

Want control over what gets installed? Pick one profile:

astrograph init --ide codex --mode full
astrograph init --ide codex --mode some
astrograph init --ide codex --mode barebones

Profiles:

| Profile | Tools included | What you get | Trade-off | |---|---|---|---| | full | All (query_code, indexing, diagnostics) | Batteries included, broadest capabilities | Highest surface area and config size | | some | Core query/discovery + suggestion tools | Most useful features for daily agent work | Reduced introspection and admin surface | | barebones | Query + tree/outline tools only | Fastest onboarding and smallest permissions | Less automation and diagnostics |

Default is full.

If you need non-interactive install:

npx @mortenbroesby/astrograph init --yes --repo /absolute/path/to/repo

If you are not using a global install:

npx @mortenbroesby/astrograph init

3) Start your IDE session and use your agent tools.

Your tooling reads the generated MCP config and you are done.

IDE Setup

Astrograph can configure MCP settings for Codex, GitHub Copilot, and GitHub Copilot CLI. Non-interactive default is --ide copilot. If a newer Astrograph release is published, init prints a short update hint: npm install @mortenbroesby/astrograph@latest.

astrograph init

Codex (.codex/config.toml):

astrograph init --yes --ide codex --repo /absolute/path/to/repo

GitHub Copilot (.vscode/mcp.json):

astrograph init --yes --ide copilot --repo /absolute/path/to/repo

GitHub Copilot CLI (.mcp.json):

astrograph init --yes --ide copilot-cli --repo /absolute/path/to/repo

The installer resolves the repo root and preserves unrelated IDE config.

To configure multiple agent clients in one pass:

astrograph init --yes --ide all --repo /absolute/path/to/repo
astrograph init --yes --ide codex,copilot --repo /absolute/path/to/repo

Documentation

• Use this for command details: CLI reference
• Performance workflow
• Contributing
• Release and publishing

Install details

• Node target: >=24
• Entry commands:
  • astrograph (preferred)
  • ai-context-engine (compatibility alias)

License

MIT. See LICENSE.

Acknowledgements

• pnpm, Turborepo, Vite, React, and Vitest for the core workspace foundation

Author

Morten Broesby-Olsen (mortenbroesby)

• GitHub: @mortenbroesby
• LinkedIn: mortenbroesby