@nockdev/hsa

HSA — Hierarchical Semantic Analysis MCP Server for AI Code Agents

Token-optimized context management with BM25 search, Merkle tree change detection, and semantic caching.

Quick Start

# Run as MCP server (stdio)
npx -y @nockdev/hsa@latest

# Or install as nock-cli plugin
nock plugins install @nockdev/hsa
nock hsa start

Features

• 🔍 BM25 Search — Full-text search across project files
• 🌳 Merkle Tree — O(log n) change detection
• 🎯 Token Budget — Smart truncation within token limits
• 💾 LRU Cache — Semantic caching for repeated queries
• 🔒 Integrity — SHA-256 tamper detection
• 🖥️ Daemon Mode — Background process with HTTP transport
• 🔑 OAuth 2.1 — JWT/API key authentication for HTTP mode
• ⚡ Native Engine — Rust-powered via napi-rs (10-100x faster)

MCP Tools

| Tool | Description | | ------------------- | -------------------------------------- | | hsa_get_context | Retrieve optimized context for LLM | | hsa_detect_stack | Detect project tech stack | | hsa_check_changes | Check file changes via Merkle diff | | hsa_prefetch | Prefetch context for predicted queries | | hsa_status | Engine health and cache stats |

Engine Tiers

| Tier | Engine | Speed | Requirement | | ---- | --------------------- | -------- | --------------- | | ⚡ 1 | Native (Rust/napi-rs) | 10-100x | Platform binary | | 🔄 2 | WASM | 2-5x | WASM runtime | | 📋 3 | Pure TS (fallback) | Baseline | Always works |

Auto-selects the best available engine with graceful degradation.

Environment Variables

| Variable | Default | Description | | ------------------ | ------- | -------------------- | | HSA_PROJECT_PATH | . | Project root path | | HSA_MAX_TOKENS | 8000 | Maximum token budget | | HSA_LOG_LEVEL | info | Log level | | HSA_DAEMON_PORT | 3100 | HTTP port for daemon |

Requirements

• Node.js ≥ 18.0.0

License

MIT © NockDev