Converts codebases into a queryable SQLite knowledge graph to help AI agents inspect relationships and assess code changes.
Also known as Nodesify/astria, @nodesify/astria
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.6.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is Astria MCP?
Astria converts codebases into a queryable SQLite knowledge graph to help AI agents inspect relationships and assess code changes.
Summary generated from the project's README
About Astria MCP server
Astria transforms codebases into a queryable SQLite knowledge graph to assist AI agents in understanding complex software structures. By using deterministic Rust and tree-sitter extraction, it maps relationships between symbols and modules. This tool is designed for developers who need to provide AI clients with deep structural context, allowing them to inspect implementations and assess the impact of code changes before making edits.
The server runs locally and requires Node.js version 22 or higher. While structural analysis functions without any API keys, users can optionally enable local embeddings or remote semantic enrichment for enhanced retrieval. The system uses a local .astria directory to store graphs and reports, utilizing extraction caches to speed up updates. Certain hardware configurations, such as Intel Macs or specific Linux builds, may have limitations regarding local embeddings due to ONNX Runtime requirements.
What you can do with it
- 1Locate specific implementationsAsk the AI to find where a particular logic, such as authentication, is handled within the codebase.
- 2Analyze code change impactDetermine which parts of the system are reachable or affected by a proposed modification to a specific node.
- 3Trace relationship pathsFollow the connections between a caller and a callee to understand execution flow.
- 4Inspect symbol detailsGet a detailed explanation of a specific symbol returned by a graph query.
Written from the project's README. Every use case is checked against a quote from it.
How to install Astria MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Astria MCP in Claude Code
$ claude mcp add astria -- npx -y @nodesify/astriaInstall Astria MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"astria": {
"command": "npx",
"args": [
"-y",
"@nodesify/astria"
]
}
}
}Install Astria MCP in VS Code
.vscode/mcp.json
{
"servers": {
"astria": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@nodesify/astria"
]
}
}
}Install Astria MCP in VS Code CLI
$ code --add-mcp '{"name":"astria","type":"stdio","command":"npx","args":["-y","@nodesify/astria"]}'Install Astria MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"astria": {
"command": "npx",
"args": [
"-y",
"@nodesify/astria"
]
}
}
}Install Astria MCP in Codex
$ codex mcp add astria -- npx -y @nodesify/astriaInstall Astria MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.astria] command = "npx" args = ["-y", "@nodesify/astria"]
Install Astria MCP in Gemini CLI
$ gemini mcp add -s user astria npx -- -y @nodesify/astriaInstall Astria MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"astria": {
"command": "npx",
"args": [
"-y",
"@nodesify/astria"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenodesify/astria is public and reachablegithub.com/nodesify/astria ↗Pass
- Package names this repository as its source@nodesify/astria names nodesify/astria as sourcenpmjs.com/package/@nodesify/astria ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @nodesify/astrianpmjs.com/package/@nodesify/astria/v/1.6.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/nodesify/astria ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @nodesify/astriaPass
- No critical advisory in the package or its dependencies9 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubastria
Knowledge graph builder for codebases
Docs | Getting started | CLI Reference | Architecture | Worked examples | Changelog | Release notes | Security
Built by Nodesify
Find an implementation, inspect its relationships, and assess a change before editing. Astria builds a local SQLite knowledge graph with deterministic Rust/tree-sitter extraction. CLI and MCP queries use the same retrieval engine; source locations and evidence classes make results inspectable. Structural analysis needs no API key. Local embeddings and remote semantic enrichment are optional.
Install
npm install -g @nodesify/astria
Node.js >= 22 is required. Prebuilt native binaries ship with the package; installation needs no Rust toolchain. macOS/Linux can also use brew install nodesify/tap/astria (tap).
Intel Mac (darwin-x64), musl Linux and windows-arm64 builds omit local embeddings because ONNX Runtime has no prebuilt runtime there. Structural analysis works; run --embed reports that embeddings are unsupported. Check astria stats --json for embeddingsSupported.
Use the graph
astria run . # build .astria/
astria map # orient by source modules
astria query "where is request authentication implemented"
astria explain <node-id> # inspect a returned symbol
astria path <caller-id> <callee-id> # follow relationships
astria affected <node-id> # assess a proposed change
astria update . # refresh after editing
Use node IDs returned by the graph. Confirm important results against the linked source: name-derived call/import bindings are RESOLVED, and ambiguous targets remain INFERRED. --detail high restricts traversal to EXTRACTED/DECLARED facts. affected reports graph reachability; it cannot prove runtime behavior.
Exclude files with .astriaignore (gitignore syntax). Graphs and reports live under .astria/; read graph_report.md for orientation. Unchanged source reuses extraction caches, while updates reconcile references across the current corpus. After upgrading, run astria update . to refresh cached extraction for qualified call targets.
Guides and evidence
- Install and first graph
- Agent integration, MCP, skills and hooks
- Wiki and exports, semantic enrichment, memory and learning
- CLI reference, graph model, troubleshooting
- Worked examples and retrieval validation, including known limitations
The evaluation harness separates file and declaration retrieval, delivered tokens, search/read cost and graph build time. Historical comparisons used tiny, exercised external sets and a single-pass search floor. New Requests and Commander questions are source-grounded, agent-authored, reserved and unexercised until their first explicit evaluation. No result establishes broad superiority or savings over a complete agent task.
Architecture and languages
Rust workspace with 20 crates plus a Node.js CLI. Uses 42 registered language configurations; exact parser coverage and optional lang-* build features are described in language support. See ARCHITECTURE.md for pipeline, caching and evidence contracts.
Astria is an independent implementation inspired by Graphify, and is not affiliated with or endorsed by that project.
Build from source
# Build Rust core
cargo build --release
# Copy the native library for the source CLI (Linux)
mkdir -p packages/astria-cli/dist
cp target/release/libastria_napi.so packages/astria-cli/dist/astria.node
# Build Node.js CLI
cd packages/astria-cli && npm ci && npm run build
See Contributing for macOS and Windows native artifact paths.
Requires Rust 1.88+ (declared as rust-version in the workspace) and Node.js >= 22.
License
MIT — see LICENSE.
Contributions are welcome and accepted under the Contributor License Agreement — see CONTRIBUTING.md to get started.
Installation defaults to project scope: astria install --platform codex --scope project. Use --scope user explicitly for user-wide integrations. Run astria doctor after setup or upgrades. See the installation lifecycle guide for supported platforms, upgrade, backup/restore and complete removal.
Astria MCP questions
How do I add Astria MCP to Claude Code?
Run claude mcp add astria -- npx -y @nodesify/astria in your terminal. Add --scope user to make it available in every project.
How do I add Astria MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Astria require an API key for structural analysis?
No, structural analysis is performed locally and requires no API key.
How do I exclude specific files from the graph?
You can exclude files using .astriaignore, which follows gitignore syntax.
What are the system requirements for installation?
Node.js version 22 or higher is required.