📖 NakshAstraMCP User Guide

Master your workflow: Deep analysis, multi-client connectivity, and visualization.

Vision: Empower AI agents with high-fidelity local code context at zero infrastructure cost.

📋 Prerequisites

OS: Windows 10+ (tested on v11), macOS 12+, or Linux (glibc 2.31+).
Hardware: See the Hardware Tiers section for recommended specifications.

🚀 Getting Started

1. Installation

Ensure uv is installed, then install the universal wheel:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install https://github.com/vijaytank/NakshAstraMCP-Docs/releases/download/3.0.0/nakshastramcp-3.10.1-cp313-cp313-win_amd64.whl --force

2. Configuration for AI Clients

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "nakshastramcp": {
      "command": "nakshastramcp",
      "args": ["start"]
    }
  }
}

Cursor IDE

Open Settings -> Models -> MCP.
Add New MCP Server.
Name: NakshAstra.
Command: nakshastramcp.
Arguments: start, --transport, stdio.

Antigravity (mcp_config.json)

Add the following to your mcp_config.json:

{
  "mcpServers": {
    "nakshastramcp": {
      "command": "nakshastramcp",
      "args": [
        "start",
        "--transport",
        "stdio"
      ],
      "type": "stdio",
      "disabled": false
    }
  }
}

🌉 Multi-Client Connectivity (Dual Transport Bridge)

NakshAstraMCP introduces a Dual Transport Bridge, allowing one host instance to serve multiple clients simultaneously.

Use Case

You are working in Antigravity (Host) while also using VS Code (Follower) for specific extensions. Both can connect to the same NakshAstraMCP instance.

Configuration for Follower Applications

When the host is active, other tools can connect to the bridge:

Type: streamable-http
URL: http://127.0.0.1:2102/mcp

💻 Hardware Tiers

NakshAstraMCP automatically adapts its engine capabilities based on your available hardware:

Tier	Specs	Capabilities
Minimal	2 cores / 4 GB RAM	Core search engine, aggressive memory management
Recommended	4 cores / 8 GB RAM	+ Semantic reranking + High-performance indexing
Optimal	8+ cores / 16 GB RAM	Full graph analysis + Deep reranking
Massive Repo	8+ cores / 16 GB+ RAM	Optimized for repositories with 50k+ files

Performance SLA: p95 query latency under 500ms on a 10,000-file repository.

🩺 Surgical Intelligence Tools

NakshAstraMCP v3.10.1 introduces high-precision tools designed for minimal token usage and maximum accuracy.

`search_codebase`

Performs a hybrid search (Tantivy BM25 + FlashRank Reranking) across your registered repositories.

When workspace_path is omitted, all registered workspaces are searched and results are merged by score.
Usage: “Find where the authentication logic is handled.”

`deep_context`

Analyzes cross-file relationships and provides structural snippets with 2-hop graph expansion.

Supports multi-workspace search — results are merged and sorted by relevance score.
Usage: “Explain how the DataManager class is initialized.”

Precision Retrieval Tools

read_file: Read precise line ranges of a file. AI agents use this to avoid dumping entire large files.
find_symbol: Locate exactly where a class, function, or method is defined across all registered workspaces.
find_references: Trace every usage of a symbol to understand the impact of potential changes.
server_status: Returns internal health metrics, memory usage, and indexing status.

🛠️ Important Commands

Category	Action	Command
Lifecycle	Start	`nakshastramcp start --workspace <path>`
	Stop	`nakshastramcp stop`
	Restart	`nakshastramcp restart`
Diagnostics	Health Check	`nakshastramcp doctor`
	Logs	`nakshastramcp logs [--follow]`
	Status	`nakshastramcp status`
Advanced	Visual UI	`nakshastramcp ui`
	Provision	`nakshastramcp provision --lang <name> --lib <path>`
	Cleanup	`nakshastramcp gc`

🔄 Background vs. CLI Management

NakshAstraMCP is designed to be a “Set it and Forget it” tool:

Background Management (Daily Use): When configured in an IDE like Antigravity, Cursor, or VS Code, the server is managed automatically. The IDE spawns the process when it starts and terminates it when it closes. You do not need to manage the server manually.
CLI Management (Advanced Use): For debugging, health checks, or manual workspace registration, use the commands listed above. The CLI is optional and provided for advanced users.

🚫 `.mcpignore` Configuration

Control which files and directories are excluded from indexing by placing a .mcpignore file in your workspace root. The syntax is identical to .gitignore:

# Exclude build artifacts
dist/
build/
node_modules/

# Exclude large data files
*.csv
*.parquet
*.sqlite

# Exclude specific directories
vendor/
__pycache__/
.git/

Tip: Changes to .mcpignore take effect immediately — the real-time watcher picks them up automatically.

🧩 Adding New Language Support (Addons)

NakshAstraMCP supports Tree-sitter grammars. While popular languages like Python, JS/TS, Java, and Kotlin are built-in, you can add any other language at runtime.

Provisioning a Language

Obtain a compiled grammar (.dll for Windows, .so for Linux/macOS).

Provision the language:

nakshastramcp provision --lang go --lib ./tree_sitter_go.dll

Verify: The server will validate the binary and copy it to its internal store. No restart is required for the indexing engine to pick up the new file types.

⚙️ Environment Variables

Variable	Default	Description
`NAKSH_TRANSPORT`	`streamable-http`	Override transport mode (`stdio` or `streamable-http`)
`NAKSH_MEM_THRESHOLD_MB`	`1024`	Memory guard threshold in MB
`NAKSH_SNIPPET_LIMIT`	`10`	Max results per search query
`NAKSH_LOG_LEVEL`	`INFO`	Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`)

🛡 Security & Privacy

Local-Only: Your code never leaves your machine.
Secret Detection: Automatically prevents indexing of API keys and sensitive strings.
Access Control: The server is locked to the workspace roots you’ve explicitly registered.
Zero Telemetry: No data collection. Fully local execution.

🏠 Home | 🚀 Setup Guide | 🛠 Troubleshooting