# 🛡️ NTS MCP FileSystem Server
### Next Transactional Server for Model Context Protocol

[![Java](https://img.shields.io/badge/Java-25%2B-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white)](https://openjdk.org/)
[![Release](https://img.shields.io/badge/Release-v1.7.4-black?style=for-the-badge)](https://github.com/Nefrols/NTS_MCP_FS/releases/tag/v1.7.4)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](LICENSE)
[![Status](https://img.shields.io/badge/Status-Stable-green?style=for-the-badge)](#-key-differentiators)
[![Tools](https://img.shields.io/badge/MCP%20Tools-21-purple?style=for-the-badge)](#%EF%B8%8F-the-toolchain-a-discipline-system-not-just-utilities)
[![Languages](https://img.shields.io/badge/Languages-12-blue?style=for-the-badge)](#6--lsp-navigation-tree-sitter)

> **English** | **[Русский](README.ru.md)** | **[Releases](https://github.com/Nefrols/NTS_MCP_FS/releases)**

---

**NTS_MCP_FS** is an enterprise-grade File System server implementation for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

It transforms standard file operations into a **Transactional OS for AI Agents**. Unlike basic tools that allow "blind" overwrites, NTS enforces **Optimistic Locking**, provides a **Persistent HUD**, and enables **Atomic Scripting** via programmable batches.

### 🚀 Key Differentiators

| Feature | Standard MCP Server | NTS_MCP_FS |
| :--- | :--- | :--- |
| **Integrity** | Blind Overwrites (Last Write Wins) | **Line Access Tokens (LATs)** - Optimistic Locking |
| **Operations** | One file at a time | **Programmable Atomic Batches** (Multi-file Scripting) |
| **Context** | Stateless (Agent forgets plan) | **AI-HUD & Built-in TODOs** (Persistent Context) |
| **Safety** | Basic Ctrl+Z (if any) | **Deep Undo & Checkpoints** (Tracks file moves) |
| **Code Intelligence** | None | **LSP Navigation & Semantic Refactoring** (12 languages) |
| **Verification** | Manual testing | **Syntax Check (Tree-sitter)**, Compilation & Test validation |
| **Persistence** | Stateless (in-memory only) | **H2 Database** (Transaction journal survives restarts) |
| **Agent Memory** | None (context lost on compression) | **nts_context** (HUD notes + snapshot recovery) |
| **Profiling** | None | **JFR Profiler + Memory Analyzer** (CPU/contention/GC/IO profiling, heap snapshots, allocation analysis) |
| **Performance** | Blocking I/O | **Java Virtual Threads** & Memory-Mapped I/O |

---

### 📦 Installation & Usage

**Prerequisites:** Java 25+

> **Why Java 25+?** NTS uses `jdk.jfr.consumer` streaming API improvements (JDK 25), enhanced `jcmd` diagnostic commands, and `ScopedValue` for task-scoped context propagation. Virtual Threads (preview in 21, production in 25) are used throughout for non-blocking I/O. Docker is available for environments that can't upgrade.

#### 1. Quick Start (Auto-Integration)
Build and run the integrator to automatically configure supported clients (Gemini CLI, OpenCode, Codex, Claude Code, Qwen CLI, Cursor, LM Studio, Antigravity, Copilot VS Code).

```bash
./gradlew shadowJar
java -jar app/build/libs/app-all.jar --integrate
```

#### 2. Manual Configuration
Add to your `mcp-config.json`:
```json
{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/nts-mcp-fs/app/build/libs/app-all.jar"
      ]
    }
  }
}
```

#### 3. Docker (No Java Required)

Docker eliminates the need to install Java 25+ locally. The server runs in a container with project directories mounted as volumes.

> **Important: Docker Mode and Roots**
>
> In Docker, you must explicitly mount directories and specify them via `NTS_DOCKER_ROOTS`. These roots **override** any roots sent by the MCP client, because the client sends host paths that don't exist inside the container.

**Option A: Use pre-built image (recommended)**

```bash
docker pull ghcr.io/nefrols/nts-mcp-fs:latest
```

**Single project:**
```json
{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/myproject:/mnt/project",
        "-e", "NTS_DOCKER_ROOTS=/mnt/project",
        "ghcr.io/nefrols/nts-mcp-fs:latest"
      ]
    }
  }
}
```

**Multiple projects:**
```json
{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/project1:/mnt/p1",
        "-v", "/home/user/project2:/mnt/p2",
        "-e", "NTS_DOCKER_ROOTS=/mnt/p1:/mnt/p2",
        "ghcr.io/nefrols/nts-mcp-fs:latest"
      ]
    }
  }
}
```

**Option B: Build locally**
```bash
docker build -t nts-mcp-fs .
docker run -i --rm \
  -v /path/to/project:/mnt/project \
  -e NTS_DOCKER_ROOTS=/mnt/project \
  nts-mcp-fs
```

**Environment variables:**
| Variable | Description |
|----------|-------------|
| `NTS_DOCKER_ROOTS` | **Required.** Colon-separated list of root paths inside the container. Must match your `-v` mount points. Overrides client roots. |
| `JAVA_OPTS` | JVM options (default: `-XX:+UseZGC -Xmx512m`) |
| `MCP_DEBUG` | Set to `true` for debug logging |
| `MCP_LOG_FILE` | Path to log file (for clients that merge stderr/stdout) |

**Available image tags:**
| Tag | Description |
|-----|-------------|
| `latest` | Latest stable release |
| `1.2.3` | Specific version |
| `1.2` | Latest patch of minor version |
| `edge` | Latest development build (main branch) |

---

### 🎯 The Philosophy: Disciplined AI Through Intentional Friction

> **"The goal is not to make the agent's job easier — it's to make the agent's work reliable."**

Most MCP servers optimize for **convenience**: fewer calls, shorter responses, maximum automation. NTS takes the opposite approach. It introduces **intentional friction** that forces AI agents to work with surgical precision.

#### The Problem: Catastrophic Drift in Long Sessions

When an AI agent works on a complex task (1-2M+ tokens), context summarization inevitably loses details. The agent "forgets" what it read 50 messages ago. Then:

1. 🔴 Agent edits line 347 based on stale memory
2. 🔴 Edit breaks something — agent panics
3. 🔴 Agent enters an uncontrolled fix-loop
4. 🔴 **Hours of work destroyed in seconds**

This isn't a bug — it's an emergent property of how LLMs handle long contexts. **NTS is designed to prevent this failure mode.**

#### The Solution: Forced Concentration via LAT

**Line Access Tokens (LATs)** are not just a security feature — they're a **cognitive constraint**.

```
┌─────────────────────────────────────────────────────────────────┐
│  Without LAT:                                                   │
│  "I'll just read the whole file... it's only 400 lines"        │
│   → Context bloated with "just in case" data                    │
│   → Summarization drops critical details                        │
│   → Agent edits wrong line from fuzzy memory                    │
│   → Catastrophic error                                          │
├─────────────────────────────────────────────────────────────────┤
│  With LAT:                                                      │
│  "I need to edit line 47. Let me read lines 40-55."            │
│   → Agent explicitly decides what it needs                      │
│   → Token proves agent saw current state                        │
│   → Context stays clean and precise                             │
│   → Edits are surgical and verified                             │
└─────────────────────────────────────────────────────────────────┘
```

The agent **cannot** read an entire file in one lazy command. It must specify ranges. This forces the agent to **think before acting** — exactly the discipline that prevents drift.

#### Why Verbose Responses Matter

Every `nts_edit_file` response includes a full unified diff. This isn't optional verbosity — it's **mandatory validation**.

```diff
--- User.java (original)
+++ User.java (modified)
@@ -15,7 +15,7 @@
     }
 
-    public String getName() {
+    public String getFullName() {
         return name;
     }
```

The agent sees the result **immediately**, in the same response. No separate "verify" step needed. No chance to "forget" to check. The diff is the proof.

#### Real-World Impact

| Scenario | Standard Tools | NTS |
| :--- | :--- | :--- |
| 2-hour refactoring session | 40% chance of catastrophic error | Near-zero (checkpoint + undo) |
| Multi-file rename | Silent corruption possible | Atomic batch or full rollback |
| External file change mid-work | Agent overwrites user's edits | Token expires, agent warned |
| Agent "panics" after error | Uncontrolled fix spiral | Undo → stable state → retry |

#### The Counterintuitive Truth

> **Spending 10% more tokens on discipline saves 100% of wasted work.**

A 2-hour agent session costs ~$5-15 in API calls. A catastrophic error that destroys that work costs the same amount **again** to redo — plus human time to diagnose what went wrong.

NTS trades micro-efficiency for macro-reliability. The agent works slightly harder per-operation, but the **entire session succeeds** instead of collapsing at hour 1:45.



### 🧠 Advanced Features Deep Dive

#### 1. 📟 Agent HUD (Heads-Up Display)
The server injects a status header into *every* tool response. The Agent never loses context.
```text
[HUD tid:a1b2] Plan: Refactor Auth [✓2 ○1] → #3: Update Login | Task: 5 edits | Unlocked: 3 files
[MEMORY: Auth tokens must use RS256 | DB migration pending review]
```
*   **Task Context:** Reminds the agent of the active Task ID.
*   **Progress Tracking:** Shows current TODO status (Done/Pending) and the *next* active task.
*   **Safety Stats:** Shows how many files are currently unlocked for editing.
*   **Agent Memory:** Shows `[MEMORY: ...]` lines from `nts_context` HUD notes — critical reminders survive context compression.

#### 2. 📜 Programmable Atomic Batches (Scripting)
The `nts_batch_tools` is not just a list of commands; it's a scripting engine for the file system.
*   **Atomic Transactions:** 10 operations in one request. If the 10th fails, the previous 9 are rolled back instantly. The project is never left in a broken state.
*   **Variable Interpolation:** Pass data between steps. Create a file in Step 1, then reference its path in Step 2 using `{{step1.path}}`.
*   **Virtual Addressing:** Use variables like `$LAST` or `$PREV_END+1` to insert code relative to previous edits without calculating line numbers.
*   **Virtual FS Context:** When you edit a file in Step 1 and run `nts_code_refactor` in Step 2, the refactoring sees the **modified content** from Step 1, not the disk version. Enables complex chains like "edit class → rename symbol across project".

**Example Script:** "Create a service, rename it, and add a method"
```json
"actions": [
  { "id": "cre", "tool": "nts_file_manage", "params": { "action": "create", "path": "Temp.java", "content": "class Svc {}" } },
  { "tool": "nts_file_manage", "params": { "action": "rename", "path": "{{cre.path}}", "newName": "UserService.java" } },
  { "tool": "nts_edit_file", "params": { "path": "{{cre.path}}", "startLine": "$LAST", "operation": "insert_after", "content": "void login() {}", "accessToken": "{{cre.token}}" } }
]
```
*Note: `{{cre.path}}` automatically resolves to `UserService.java` after the rename step!*

#### 3. 🔒 Enterprise Security & Sandboxing
*   **Optimistic Locking (LATs):** Agents *must* read a file to get a token (`LAT:...`) before editing. If the file changes externally, the token expires and the external change is automatically recorded in file history. No more race conditions.
*   **Smart Token Invalidation:** Tokens track **Range CRC** instead of file CRC. Edits outside your token's range don't invalidate it — only changes to the specific lines you're working on trigger re-read. This dramatically reduces unnecessary token refreshes in large files.
*   **Path Aliasing:** Tokens remain valid after `move`/`rename` operations. The system tracks file identity through path aliases with transitive resolution — even chains like `A → B → C` preserve token validity.
*   **Strict Sandboxing:** All paths are normalized and pinned to the project root. Impossible to escape via `../../`.
*   **Infrastructure Protection:** Automatically blocks modification of `.git`, `.env`, and build configs unless explicitly allowed.
*   **OOM Protection:** Prevents reading massive files (>10MB) that would crash the context window.
*   **Structured Error Codes:** All errors include machine-readable codes (`FILE_NOT_FOUND`, `TOKEN_EXPIRED`, etc.) with human-readable solutions. No more cryptic exceptions — every error tells you exactly what went wrong and how to fix it.

#### 4. ⏪ State Management: Checkpoints & Deep Undo
*   **Task Journal (H2 Database):** Logs every logical step (not just file IO). Persisted in embedded H2 database — survives server restarts.
*   **In-Memory Snapshots:** Undo engine uses in-memory `byte[]` snapshots instead of file-based backups for faster recovery.
*   **Checkpoints:** Agent can run `nts_task checkpoint('pre-refactor')` and safely `rollback` if the approach fails.
*   **Deep Undo:** The system tracks **File Lineage**. If you move `FileA -> FileB` and then hit Undo, NTS knows to restore content to `FileA`.
*   **Git Integration:** Can create Git stashes as emergency fallbacks (`git_checkpoint`).

#### 5. 👁️ External Change Tracking
The server automatically detects when files are modified **outside of MCP** (by user, linter, IDE, or other tools).
*   **CRC-based Detection:** Each file read creates a snapshot. On next access, if the CRC differs, the change is detected.
*   **File History:** External changes are recorded in file history and can be reviewed via `nts_task journal`.
*   **Smart Prompts:** When an external change is detected, the agent receives a TIP recommending to review changes before proceeding, as they may be intentional user edits.
*   **Undo Support:** If needed, external changes can be undone through the standard undo mechanism.

#### 6. 💡 Smart Contextual TIPs
Every tool response includes intelligent contextual hints that guide the agent through optimal workflows.
*   **Workflow Guidance:** After each operation, TIPs suggest the logical next step (e.g., "Token ready for editing → nts_edit_file(...)").
*   **Performance Hints:** Large range reads trigger suggestions to use symbol-based navigation or grep for precision.
*   **Error Prevention:** Pattern analysis detects regex-like queries used without `isRegex=true` and warns proactively.
*   **Token Management:** When line counts change after edit, TIPs remind to use the NEW token for subsequent operations.
*   **Refactoring Awareness:** Signature changes trigger suggestions to check call sites via `nts_code_navigate(action='references')`.
*   **Import Updates:** After move/rename of Java/Kotlin files, TIPs suggest searching for import statements that need updating.

**Example TIPs in action:**
```
[WORKFLOW: Token ready for editing -> nts_edit_file(path, startLine, content, accessToken)]
[TIP: Large range read (150 lines). Consider using 'symbol' parameter for precise symbol boundaries.]
[TIP: Pattern contains regex-like characters (.*). If you intended regex search, add isRegex=true parameter.]
[TIP: Line count changed (+5). Use NEW TOKEN above for subsequent edits to this file.]
```

#### 7. ✅ Built-in TODO System
A specialized tool (`nts_todo`) allows the agent to maintain a Markdown-based plan.
*   The active plan state is fed into the **HUD**.
*   Keeps the agent focused on one task at a time.
*   Auto-updates status (`todo`, `done`, `failed`) in the file system.

#### 8. 🧭 LSP Navigation (Tree-sitter)
The `nts_code_navigate` tool provides IDE-like code intelligence powered by Tree-sitter.
*   **Go to Definition:** Jump to where a symbol is defined.
*   **Find References:** Locate all usages across the project.
*   **Hover:** Get type, signature, and documentation for any symbol.
*   **List Symbols:** File outline with all definitions.
*   **12 Languages:** Java, Kotlin, JS/TS/TSX, Python, Go, Rust, C/C++, C#, PHP, HTML.
*   **Extended Java Support:** Enum constants as `CONSTANT` symbols, class-vs-constructor auto-resolution, `kind` filter and `brief` mode for compact output on large files.
*   **Structured Resolution Contract:** Semantic actions now return `resolutionStatus`, `resolutionKind`, `usedFallback`, `safeForAutonomousEdit`, `candidateCount`, `target`, and `candidates`.
*   **Strict Mode:** `strict=true` rejects fallback and ambiguous cursor resolution instead of silently guessing a target.
*   **Ambiguity Signaling:** Overload or nearby-cursor ambiguity is returned explicitly so an agent can stop before making an unsafe edit.

#### 9. 🔄 Semantic Refactoring (10 Operations)
The `nts_code_refactor` tool performs intelligent code transformations.
*   **Rename:** Byte-span rewrite (UTF-8 safe) with overload-aware `SymbolHandle` matching. Updates ALL references across the entire project.
*   **Change Signature:** AST-rewrite of declarations and call sites. Action-based parameters (`add`, `remove`, `rename`, `retype`, `reorder`) with automatic overload disambiguation.
*   **Extract Method:** Pull code into a new method with safety validation (escaping variable detection) and smart return type inference.
*   **Extract Variable:** Span-precise extraction with occurrence normalization, balanced-expression validation, and `replaceAll` support.
*   **Inline:** AST-aware call-site rewriting with argument substitution, precedence-safe parenthesization, and multi-occurrence support.
*   **Move:** Relocate classes/methods with static method reference updates, import rewiring, and instance-method safety guards.
*   **Wrap:** Wrap code in try-catch, if-block, or loop with escaping-variable scope check.
*   **Delete:** Statement-level rewriting (`findStatementSegment`) instead of whole-line deletion. Overload-safe via signature/position.
*   **Generate:** Create getters, setters, constructors, builders, toString, equals/hashCode with final-field safety and duplicate detection.
*   **Batch:** Combine multiple refactoring operations atomically with parameter normalization and inheritance.
*   **Preview Mode:** Review diff before applying (`preview: true`).
*   **Parallel Reference Search:** Both `nts_code_navigate` and `nts_code_refactor` use parallel file scanning with pre-filtering, searching up to 15 levels deep for maximum coverage.
*   **Batch Integration:** Successful apply responses return an `affectedFiles` array with tokens for each modified file — enables chaining like `refactor → edit` in `nts_batch_tools`.
*   **Structured Validation:** Semantic previews/applies expose machine-readable `validation` metadata and `affectedFileCount`.
*   **Rollback on Invalid Output:** All mutating operations validate changed files through SyntaxChecker after apply and rollback atomically on syntax breakage.
*   **Risk Metadata:** Every response includes `confidence` (exact/mixed), `riskLevel` (low/medium), `rewriteStrategy` (semantic_span/hybrid_span/line_fallback), and detailed `validation` object.
*   **Hybrid Transparency:** Hybrid rename previews expose `hybridMode`, `semanticMatchCount`, `textOnlyMatchCount`, and provenance so text-only matches are never hidden.

```json
{
  "action": "rename",
  "path": "src/User.java",
  "symbol": "getName",
  "newName": "getFullName",
  "preview": true
}
```
**Preview response exposes structured validation and file counts:**
```json
{
  "status": "preview",
  "affectedFileCount": 2,
  "hybridMode": false,
  "semanticMatchCount": 2,
  "validation": {
    "targetCountExpected": 2,
    "targetCountMatched": 2,
    "declarationCountUpdated": 1,
    "callSiteCountUpdated": 1,
    "astParseAfterEdit": true
  }
}
```

**Apply response includes batch-ready tokens:**
```json
{
  "status": "success",
  "affectedFileCount": 1,
  "affectedFiles": [
    { "path": "src/User.java", "accessToken": "LAT:...", "crc32c": "A1B2C3D4", "lineCount": 50 }
  ],
  "token": "LAT:..."
}
```

#### 10. 🧠 Agent Context Memory (`nts_context`)
The `nts_context` tool gives the agent a **structured, task-scoped memory** — a native alternative to manually editing a MEMORY.MD file.

*   **HUD Notes (`kind='hud_note'`):** Critical reminders that appear in **every** tool response via the HUD line. Survive context compression and prompt summarization.
*   **Context Notes (`kind='note'`):** Broader findings, root causes, user constraints — stored for recovery but not shown on every response.
*   **Importance Levels:** `critical` > `high` > `normal` — controls display priority and sorting.
*   **Snapshot Recovery:** `action='snapshot'` returns a complete task picture: TODO progress, recently modified files, last 5 journal operations, active HUD notes, all context notes, and a suggested next action. Designed for re-orientation after context compression.
*   **CRUD API:** `add`, `read`, `update`, `delete`, `list` — full lifecycle management.
*   **Contextual Prompts:** Other tools (`nts_edit_file`, `nts_todo`, `nts_verify`) gently nudge the agent to save durable findings via TIP hints.

```
Agent discovers root cause → saves as hud_note
  → Every subsequent tool response shows: [MEMORY: Auth tokens must use RS256]
  → Context compressed after 500 messages
  → Agent calls snapshot → full picture restored in one call
```

#### 11. ☕ Java Development Suite

NTS provides **extended Java support** beyond the general 12-language tree-sitter capabilities. While AST navigation, refactoring, and syntax checking work across all supported languages, the Java ecosystem gets dedicated high-level tools designed for maximum agent productivity with minimum cognitive load.

**Design philosophy:** Every Java tool operates at the **highest abstraction level**. The agent doesn't manage JFR sessions, parse histograms, or construct Gradle commands from scratch — it states intent ("profile this", "build the project", "show me the heap") and receives actionable results. This reduces cognitive load, saves tokens, and lets the agent focus on the problem, not the tooling.

##### AST Intelligence (Extended for Java)

The tree-sitter-based `nts_code_navigate` and `nts_code_refactor` support 12 languages, but Java gets **enhanced capabilities**:
- **Enum constant extraction** — enum values appear as `CONSTANT` symbols in navigation
- **Constructor-aware rename** — class rename automatically renames all constructors (Java requires constructor name = class name)
- **Import-aware move** — moving classes triggers import update suggestions via Smart TIPs
- **Overload disambiguation** — method signature matching uses structured AST parameters, not string heuristics
- **Symbol filtering** — `symbols(kind='method', brief=true)` gives compact output for large classes (saves tokens on 2000+ line files)

##### Gradle Build Integration (`nts_gradle_task`)

High-level build automation — the agent says "build" or "test" without thinking about wrapper scripts or platform specifics.

- **Smart backend switching:** Uses `gradlew` if present, falls back to system `gradle`, or auto-generates wrapper
- **Project initialization:** `task='init', initType='java-application'` creates a complete project scaffold
- **Parsed output:** Compilation errors come back with `file:line` references. Test results include pass/fail/skip counts
- **Async support:** Long builds return a `processId` — the agent can continue other work and poll via `nts_process`

##### JFR Profiler (`nts_java_profiler`)

**One call profiling** — attach to any JVM, record, parse, and get an executive summary in a single tool call.

```
discover → profile(focus='cpu', 30s) → analyze(focus='contention') → compare(before, after)
```

- **6 focus areas:** `cpu`, `cpu-time` (JDK 25+), `memory`, `contention`, `gc`, `io`, or `all`
- **Re-analyze without re-recording:** Same recording, different focus — saves time and tokens
- **Delta comparison:** Before/after analysis with normalized per-second rates
- **Enhanced contention:** JavaMonitorEnter, Object.wait(), ThreadPark — with call sites and blocked thread ranking
- **Smart hints:** NIO servers with empty IO data get an NIO-specific suggestion. ZGC with minimal pauses gets a pauseless collector note

##### Memory Analyzer (`nts_java_memory`)

Answers "what's on the heap?" and "what's being allocated?" — separate from the profiler because these are fundamentally different questions.

```
snapshot(baseline) → exercise code → snapshot(after) → compare → find leak candidates
```

- **Instant histograms:** `jcmd GC.class_histogram` — results in milliseconds, no recording needed
- **Leak detection workflow:** Two snapshots → compare → classes with biggest growth = leak candidates
- **Allocation pressure:** JFR-based allocation recording shows top types by allocation rate with call sites
- **Auto-verdict:** Snapshot compare includes automated "leak signal" / "no leak signal" conclusion

##### Why Java Gets Special Treatment

| Aspect | General (12 languages) | Java (extended) |
|--------|----------------------|-----------------|
| **Navigation** | symbols, hover, definition, references | + enum constants, constructor-aware rename, overload disambiguation |
| **Build** | — | Gradle integration with init, build, test, async |
| **Profiling** | — | JFR profiler with 6 focus areas, re-analyze, compare |
| **Memory** | — | Heap snapshots, leak detection, allocation analysis |
| **Verification** | Tree-sitter syntax check | + Gradle compilation + test execution |

---

### 🛠️ The Toolchain: A Discipline System, Not Just Utilities

Each tool in NTS is designed as part of an **interconnected discipline system**. They don't just perform operations — they enforce a workflow that keeps the agent focused, verified, and recoverable.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        THE NTS DISCIPLINE LOOP                              │
│                                                                             │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐          │
│   │  INIT    │────▶│  READ    │────▶│  EDIT    │────▶│  VERIFY  │          │
│   │  Task    │     │ + Token  │     │ + Token  │     │(Diff/AST)│          │
│   └──────────┘     └──────────┘     └──────────┘     └────┬─────┘          │
│        │                                                   │                │
│        │              ┌──────────┐                         │                │
│        └─────────────▶│  UNDO    │◀────────────────────────┘                │
│         (if panic)    │ Recovery │    (if wrong)                            │
│                       └──────────┘                                          │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

#### 🔐 `nts_init` — The Accountability Boundary

**Why it exists:** Creates an isolated task with its own undo history, checkpoints, and token registry.

**Discipline role:** Everything the agent does is tracked. There's no "anonymous" editing. If something breaks, the task journal knows exactly what happened and when.

**Task Reactivation:** If the server restarts or connection drops, the task can be reactivated:
```json
{ "taskId": "your-previous-uuid" }
```
This restores the task directory with todos and file history. In-memory state (tokens, undo stack) starts fresh, but disk-persisted data (H2 journal) is preserved.

**Connection:** All other tools require `taskId`. This isn't bureaucracy — it's **traceability**.

**Sub-Tasks (parallel agents):**

When multiple agents work on the same codebase simultaneously (e.g., one refactors backend, another updates frontend), sub-tasks provide **isolated undo/redo stacks** while sharing the same project roots.

```
                    ┌─────────────┐
                    │  nts_init() │  ← Parent agent
                    │  taskId: A  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼                         ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ nts_init(        │     │ nts_init(        │
    │  parentTaskId=A) │     │  parentTaskId=A) │
    │ taskId: A:sub-x  │     │ taskId: A:sub-y  │
    │ [own undo stack] │     │ [own undo stack] │
    └────────┬────────┘     └────────┬────────┘
             │                       │
             ▼                       ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ merge → parent  │     │ rollback (fail)  │
    │ (one undo entry)│     │ (all reverted)   │
    └─────────────────┘     └─────────────────┘
```

**Lifecycle:**
```json
// 1. Sub-agent creates isolated sub-task
{"parentTaskId": "A"}
→ {"taskId": "A:sub-x1b2c3d4", "isSubTask": true}

// 2. Sub-agent works using sub-taskId in all calls
{"taskId": "A:sub-x1b2c3d4", "path": "Backend.java", ...}

// 3a. On SUCCESS — merge into parent (one grouped undo entry)
{"action": "merge", "childTaskId": "A:sub-x1b2c3d4", "taskId": "A"}

// 3b. On FAILURE — rollback all sub-task edits
{"action": "rollback", "childTaskId": "A:sub-x1b2c3d4", "taskId": "A"}
```

**Key rules:**
- Sub-tasks inherit workingDirectory and project roots from parent
- Sub-tasks have their **own** undo/redo stack, file tokens, TODO plans
- After merge, parent can undo ALL sub-agent edits with one `nts_task(action='undo')`
- **Different files only:** sub-tasks are designed for agents editing non-overlapping files. CRC tokens will block the second writer if two sub-tasks try to edit the same file region
- Don't use sub-tasks for simple sequential workflows — they add overhead

---

#### 📖 `nts_file_read` — The Attention Gate

**Why it exists:** Reads file content and issues a **Line Access Token (LAT)**.

**Discipline role:** The agent must **explicitly decide** which lines it needs. No "just read everything" shortcut.

```
❌ read({ path: "file.java" })                    // NOT ALLOWED
✅ read({ path: "file.java", startLine: 10, endLine: 30 })  // Forced precision
```

**Connection:** The token returned here is **required** for `nts_edit_file`. Read → Token → Edit. No shortcuts.

**Smart TIPs:** Responses include workflow hints (e.g., "Token ready for editing") and suggest symbol-based reading for large ranges.

**Bulk Read:** Read multiple related files in a single request:
```json
{
  "bulk": [
    { "path": "UserService.java", "symbol": "createUser" },
    { "path": "UserRepository.java", "symbol": "save" },
    { "path": "User.java", "startLine": 1, "endLine": 30 }
  ]
}
```
Each file is separated in output with its own TOKEN. Errors in one file don't affect others.

---

#### ✏️ `nts_edit_file` — The Verified Mutation

**Why it exists:** Applies line-based edits with mandatory token validation.

**Discipline role:**
1. **Token required** — proves agent read the current state
2. **Diff in response** — agent immediately sees what changed
3. **CRC check** — if file changed externally, edit fails safely
4. **Smart TIPs** — contextual hints for common issues:
   - Multi-line content replacing single line without `endLine` → suggests `insert_after` or range
   - Line count changed → reminds to use NEW token for subsequent edits
   - Signature change detected → suggests checking call sites with `nts_code_navigate`
   - Significant changes → reminds to run tests

**Connection:** Consumes token from `nts_file_read`, produces new token for subsequent edits. Chain of custody is unbroken.

---

#### 📁 `nts_file_manage` — Structure with Memory

**Why it exists:** Create, delete, move, rename files and directories.

**Discipline role:**
- `create` returns a token — new files are immediately editable
- `rename`/`move` **transfers tokens via path aliasing** — tokens remain valid even after the file is moved (transitive chains like `A → B → C` work)
- `delete` **invalidates tokens** — no editing ghosts

**Connection:** Works with `nts_batch_tools` for atomic multi-file restructuring. Path aliases persist across the task.

---

#### 🔍 `nts_file_search` — Discovery with Intent

**Why it exists:** Find files (`glob`), search content (`grep`), view structure.

**Discipline role:** `grep` returns **tokens for matched ranges**. The agent can search and immediately edit without a separate read step.

```
grep("TODO") → finds line 47 → returns TOKEN for lines 45-50
           → agent can edit lines 45-50 directly
```

**Smart TIPs:** After grep, workflow hints remind that tokens are ready for direct editing. If pattern looks like regex but `isRegex=false`, suggests enabling it.

**Connection:** Bridges discovery and action. Reduces round-trips while maintaining token discipline.

---

#### ⏪ `nts_task` — The Panic Button

**Why it exists:** Undo, redo, checkpoints, rollback, and task journal.

**Discipline role:** When the agent makes a mistake, it has **structured recovery** instead of uncontrolled fix-spiraling.

```
checkpoint("before-risky-refactor")
  → try dangerous changes
  → if wrong: rollback("before-risky-refactor")
  → project restored in one command
```

**Connection:** This is the safety net that makes aggressive refactoring possible. Agents can be bold because recovery is guaranteed.

---

#### 🔗 `nts_batch_tools` — Atomic Scripting

**Why it exists:** Execute multiple tools as a single atomic transaction.

**Discipline role:** Complex operations either **fully succeed or fully rollback**. No half-broken states.

```json
{
  "actions": [
    { "id": "svc", "tool": "nts_file_manage", "params": { "action": "create", "path": "Service.java" }},
    { "tool": "nts_edit_file", "params": { "path": "{{svc.path}}", "accessToken": "{{svc.token}}", ... }}
  ]
}
// If edit fails → create is rolled back → project untouched
```

**Connection:** Uses `{{step.token}}` interpolation. Tokens flow between steps automatically. This is the culmination of the discipline system.

---

#### 🔄 `nts_project_replace` — Controlled Mass Mutation

**Why it exists:** Global search and replace across the entire project.

**Discipline role:** 
- `dryRun: true` shows **all changes before applying**
- Atomic: all files changed or none
- Creates automatic checkpoint before execution

**Connection:** High-risk operation with maximum safeguards.

---

#### 🧭 `nts_code_navigate` — Semantic Understanding

**Why it exists:** Go to definition, find references, hover info, symbol listing.

**Discipline role:** Agent can understand code structure **before editing**. Reduces guesswork, increases precision.

**Structured response contract:**
- `resolutionStatus`: `exact`, `ambiguous`, `fallback`, or `not_found`
- `resolutionKind`: how the semantic target was resolved
- `usedFallback`: whether resolver had to weaken precision
- `safeForAutonomousEdit`: whether the result is safe to feed into autonomous edits
- `candidateCount`: number of semantic candidates considered
- `target`: the selected `SymbolHandle` when one exact target exists
- `candidates`: candidate summary when the target is ambiguous

**Extended Java Support:** Enum constants as `CONSTANT` symbols, class-vs-constructor auto-resolution, `kind` filter and `brief` mode for compact output on large files.

**Connection:** Returns tokens for found locations. Navigate → understand → edit with confidence.

---

#### 🔧 `nts_code_refactor` — Intelligent Transformation

**Why it exists:** Rename symbols, change signatures, generate code, extract methods — with automatic reference updates.

**Discipline role:**
- `preview: true` shows **all affected files** before applying
- Semantic rename updates ALL references, not just text matches
- Atomic: entire refactoring succeeds or fails together
- **Returns tokens** for all modified files — enables `refactor → edit` chains in batches
- Semantic refactors expose machine-readable `validation` and `affectedFileCount`
- Standard semantic `rename` no longer mixes in text-search fallback unless `hybridMode=true`
- Hybrid rename explicitly reports `semanticMatchCount`, `textOnlyMatchCount`, and provenance
- Apply path validates syntax and rolls back on invalid output instead of returning false success

**Connection:** Uses tree-sitter for precision. Integrates with `nts_batch_tools` via `{{step.affectedFiles[0].accessToken}}` interpolation. Safer than manual multi-file editing.

---

#### 📋 `nts_todo` — The Focus Anchor

**Why it exists:** Maintains a Markdown-based task list integrated with the HUD.

**Discipline role:** Keeps the agent focused on **one task at a time**. The HUD constantly reminds what's next.

```
[HUD] Plan: Auth Refactor [✓2 ○3] → #3: Update Login Controller
```

**Connection:** Prevents scope creep. Agent always knows the current objective even after context summarization.

---

#### 🔀 `nts_git` — Version Control Integration

**Why it exists:** Git status, diff, add, commit — without leaving NTS.

**Discipline role:** 
- `git_checkpoint` creates stash as emergency backup
- `commit_task` auto-generates commit message from TODO progress
- Safe operations only (no push/force)

**Connection:** Integrates with task journal. Commits can reference completed tasks.

---

#### 📊 `nts_compare_files` — Visual Verification

**Why it exists:** Shows unified diff between any two files.

**Discipline role:** Agent can verify changes by comparing before/after states explicitly.

**Connection:** Useful for reviewing results of batch operations or refactoring.

---

#### ⚙️ `nts_gradle_task` — Build Feedback Loop

**Why it exists:** Run Gradle tasks (build, test, check) with parsed output.

**Discipline role:** Agent gets immediate feedback on whether changes broke the build. Errors are parsed and actionable.

**Connection:** Closes the loop: Edit → Build → Fix → Repeat.

---

#### ✅ `nts_verify` — Multi-Level Validation

**Why it exists:** Verify code correctness at three levels: syntax, compilation, and tests.

**Discipline role:**
- `syntax` — Fast tree-sitter AST check (no build needed). Catches errors instantly after edits.
- `compile` — Runs `gradlew build -x test` for compilation verification.
- `test` — Runs `gradlew test` for full test validation.

**Connection:** Bridges editing and building. Agent verifies syntax without a full build cycle, escalating to compilation/tests only when needed.

---

#### 🔍 `nts_context` — Unified Task Context

**Why it exists:** Provides a single place for HUD reminders and full task-context recovery after compression.

**Discipline role:**
- `add/update/read/delete/list` manage task-scoped context entries
- `kind='hud_note'` creates always-visible HUD reminders
- `kind='note'` stores broader findings and recovery notes
- `snapshot` returns the current task picture when the agent needs to re-orient
- The tool behaves like a structured internal `MEMORY.MD`, but with explicit actions instead of manual file editing

When the agent loses context due to prompt summarization, `snapshot` returns:
- Current task ID and stats
- TODO progress (if active)
- Recently modified files
- Recent journal entries (last 5 operations)
- Active HUD notes
- All stored context notes
- Suggested next action

**Connection:** Combines always-on reminders and recovery context into one native tool. The agent can ask "what must I remember?" and "where am I?" from the same surface, while prompt hints gently push it to preserve only durable, high-value context.

---

#### 🖥️ `nts_process` — Background Process Management

**Why it exists:** Monitor and control long-running background processes (Gradle builds, Git operations).

**Discipline role:** Agent can retrieve logs or kill async processes without blocking the main workflow.

**Connection:** Works with `nts_gradle_task` and `nts_git` for async operations.

---

#### ☕ Java Development Suite (`nts_gradle_task` + `nts_java_profiler` + `nts_java_memory`)

**Why it exists:** Java gets dedicated high-level tools that operate at the intent level — "build", "profile CPU for 30s", "show me the heap" — with all complexity handled internally.

**Discipline role:** The agent never manages JFR sessions, parses raw histograms, or constructs Gradle command lines. Each tool returns actionable, agent-friendly output. Re-analyze without re-recording saves tokens. Snapshot compare auto-generates leak verdicts. Build errors come back with file:line references.

**Connection:** Integrates with `nts_context` for persisting findings, `nts_verify` for build feedback, and `nts_process` for async builds.

---

### The System as a Whole

These tools aren't independent utilities. They form a **closed discipline loop**:

1. **Task** establishes accountability
2. **Read** forces attention and issues tokens
3. **Edit** requires tokens and shows results
4. **Verify** validates changes (syntax → compile → test)
5. **Task** provides recovery when needed
6. **Batch** enables complex operations atomically
7. **HUD + TODO** maintains focus across long sessions
8. **Context** preserves durable reminders and recovers the task picture after compression
9. **Java Suite** provides build, profiling, and memory analysis for the full Java development lifecycle

**Every tool reinforces the others.** There's no escape hatch to "just edit blindly." The discipline is architectural.

---

> **See also:** [Русская версия](README.ru.md) | [Releases](https://github.com/Nefrols/NTS_MCP_FS/releases) | [License](LICENSE)