<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:0F172A,50:059669,100:10B981&height=160&section=header&text=HSA%20MCP%20Server&fontSize=36&fontColor=FFFFFF&animation=fadeIn&fontAlignY=35&desc=Hierarchical%20Semantic%20Analysis%20for%20AI%20Code%20Agents&descAlignY=55&descSize=14" width="100%" />
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@nockdev/hsa"><img src="https://img.shields.io/npm/v/@nockdev/hsa?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837&color=000000" alt="npm" /></a>
  <img src="https://img.shields.io/badge/MCP%20tools-19-10B981?style=for-the-badge&logo=puzzle&logoColor=white" alt="MCP Tools" />
  <img src="https://img.shields.io/badge/engine-Rust%20Native-EF4444?style=for-the-badge&logo=rust&logoColor=white" alt="Rust" />
  <img src="https://img.shields.io/badge/node-%E2%89%A518-3B82F6?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js" />
  <img src="https://img.shields.io/badge/license-MIT-8B5CF6?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="License" />
</p>

<p align="center">
  Token-optimized context engine with <b>BM25 search</b>, <b>Merkle tree</b> change detection, <b>semantic caching</b>, and <b>web dashboard</b>.
</p>

---

## ⚡ Quick Start

```bash
# Via nock-cli (recommended)
nock awf hsa start

# Or run standalone via npx
npx -y @nockdev/hsa@latest

# Or install as plugin
nock plugins install @nockdev/hsa
```

---

## ✨ Features

| Feature              | Description                                                  |
| :------------------- | :----------------------------------------------------------- |
| 🔍 **BM25 Search**   | Full-text search across project files with ranked results    |
| 🌳 **Merkle Tree**   | O(log n) change detection — instant diff for large codebases |
| 🎯 **Token Budget**  | Smart truncation within configurable token limits            |
| 💾 **LRU Cache**     | Semantic caching for repeated queries with TTL               |
| 🔒 **Integrity**     | SHA-256 tamper detection across 266 files                    |
| 🖥️ **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)                    |
| 🧠 **Skill Search**  | BM25 index across 93 skill patterns                          |
| 📊 **Web Dashboard** | Real-time monitoring at `localhost:13100/dashboard`          |

---

## 🛠️ MCP Tools (19)

| Tool                     | Description                            |
| :----------------------- | :------------------------------------- |
| `hsa_get_context`        | Retrieve optimized context for LLM     |
| `hsa_detect_stack`       | Detect project tech stack              |
| `hsa_get_agent_config`   | Load commands, personas, rules, skills |
| `hsa_check_changes`      | Check file changes via Merkle diff     |
| `hsa_prefetch`           | Prefetch context for predicted queries |
| `hsa_status`             | Engine health and cache stats          |
| `hsa_search_skills`      | BM25 search across 93 skill patterns   |
| `hsa_get_snapshot`       | Project structure snapshot             |
| `hsa_get_repo_map`       | Repository structure map               |
| `hsa_export`             | Export context as portable format      |
| `hsa_detect_environment` | Detect runtime environment             |
| `hsa_prepare_handoff`    | Prepare context for agent handoff      |
| `hsa_filter_tools`       | Filter available tools by context      |
| `hsa_trace_flow`         | Trace code execution & call chains     |
| `hsa_feedback`           | Provide relevance feedback for ranking |
| `hsa_declare_intent`     | Declare session intent & goals         |
| `hsa_track_progress`     | Track work in 3-level hierarchy        |
| `hsa_save_anchor`        | Save immutable facts across sessions   |
| `hsa_check_drift`        | Detect scope drift from declared intent|

---

## ⚙️ Engine Tiers

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

Auto-selects the best available engine with graceful degradation.

---

## 🖥️ Web Dashboard

```bash
nock awf hsa start    # Dashboard at http://localhost:13100/dashboard
```

| Page         | Description                                            |
| :----------- | :----------------------------------------------------- |
| `/dashboard` | Real-time project stats, cache metrics, indexed skills |
| `/logs`      | Tool call history, search queries, performance traces  |

---

## 🔧 Environment Variables

| Variable                 | Default | Description                                  |
| :----------------------- | :------ | :------------------------------------------- |
| `HSA_PROJECT_PATH`       | `.`     | Project root path                            |
| `HSA_MAX_TOKENS`         | `8000`  | Maximum token budget                         |
| `HSA_LOG_LEVEL`          | `info`  | Log level (`debug`, `info`, `warn`, `error`) |
| `HSA_DAEMON_PORT`        | `13100` | HTTP port for daemon mode                    |
| `HSA_CACHE_TTL`          | `300`   | Cache TTL in seconds                         |
| `HSA_MAX_INDEXED_SKILLS` | `10`    | Maximum concurrent indexed skills            |

---

## 📋 Requirements

- **Node.js** ≥ 18.0.0

## 📄 License

MIT © [**NockDev**](https://github.com/nockasdd)

<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:10B981,50:059669,100:0F172A&height=100&section=footer" width="100%" />
</p>
