Metadata-Version: 2.4
Name: nagato-mcp-tools
Version: 0.2.2
Summary: Agent-First MCP Toolkit -- code search, editing, execution, and analysis tools for any MCP client.
Author-email: Chromoforge <mcp@chromoforge.de>
Maintainer-email: Chromoforge <mcp@chromoforge.de>
License: MIT
Project-URL: Homepage, https://chromoforge.de/mcp
Project-URL: Repository, https://github.com/Chromoforge/nagato-mcp-tools
Project-URL: Issues, https://github.com/Chromoforge/nagato-mcp-tools/issues
Project-URL: Security, https://github.com/Chromoforge/nagato-mcp-tools/security/advisories
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3.0.0,>=2.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: ddgs>=0.5.0
Requires-Dist: ruff>=0.3.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: semantic
Requires-Dist: fastembed>=0.4.0; extra == "semantic"
Requires-Dist: sqlite-vec>=0.1.6; extra == "semantic"
Requires-Dist: onnxruntime>=1.16.0; extra == "semantic"
Provides-Extra: ui
Requires-Dist: fastapi>=0.100.0; extra == "ui"
Requires-Dist: uvicorn[standard]>=0.22.0; extra == "ui"
Requires-Dist: websockets>=11.0; extra == "ui"
Requires-Dist: aiofiles>=23.0.0; extra == "ui"
Provides-Extra: monitor
Requires-Dist: psutil>=5.9.0; extra == "monitor"
Requires-Dist: nvidia-ml-py>=13.610.43; extra == "monitor"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Dynamic: license-file

# 🛠️ nagato-mcp-tools

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Standard](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Repo: Chromoforge/nagato-mcp-tools](https://img.shields.io/badge/repo-Chromoforge%2Fnagato--mcp--tools-blue.svg)](https://github.com/Chromoforge/nagato-mcp-tools)

> **Agent-First MCP Toolkit** — 31 code search, editing, execution, and analysis tools exposed directly over the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Fully standalone and compatible with any MCP client (VS Code, Claude Desktop, Cursor, etc.).
>
> Licensed under the **MIT License**. See [LICENSE](LICENSE) for full terms.

---

## ✨ Features

- 🔍 **Deep Code Navigation:** AST-level symbol extraction, call-graph analysis (callers/callees), function signatures, file discovery, and vector-based semantic code search.
- ✏️ **Precise Code Editing:** Exact substring replacements, line-range edits, safe renames/deletes.
- ⏪ **Granular Undo/Redo:** Multi-mode undo/redo (steps, time, command, step-target) — rollback edits, shell commands, or entire workflows with precision.
- ⚡ **Execution & Scripting:** Python code snippet execution with timeout limits and isolated subprocess execution (Note: NOT an OS sandbox; executes with local user permissions).
- 🧪 **Testing & Quality:** Targeted pytest execution (`nagato_run_test`), configured test suites, and integrated Ruff linting/syntax checks.
- 🧰 **Git & Shell:** Git log/diff/status/revert, shell execution, DuckDuckGo web search, and interactive prompts.
- 🧠 **Smart Pre-Parsing:** Automatic input validation and auto-correction before tool execution — catches malformed arguments early.

---

## ⚠️ Security & Trust Model

* **No Sandbox:** `nagato_execute_snippet` and `nagato_shell` execute with full user permissions on the host system. Do not expose them to untrusted external LLM prompts without human oversight.
* **WebUI Security:** The WebUI dashboard has no built-in authentication. Bind it only to `127.0.0.1` / `localhost` and do not expose the port to public networks.
* **Audit Logs:** Tool calls and returns are logged to `.nagato/standalone/audit.jsonl`. If inspecting files containing sensitive tokens/credentials, consider adding `.nagato/` to your `.gitignore`.

---

## 📦 Installation

### Standard Installation
```bash
pip install nagato-mcp-tools
```

### With Semantic Search (Vector Embeddings)
```bash
pip install "nagato-mcp-tools[semantic]"
```

### With WebUI Dashboard (Live Monitoring & Audit)
```bash
pip install "nagato-mcp-tools[ui]"
```

### All Extras (Semantic + WebUI)
```bash
pip install "nagato-mcp-tools[semantic,ui]"
```

### Editable Installation (Development)
```bash
git clone https://github.com/Chromoforge/nagato-mcp-tools.git
cd nagato-mcp-tools
pip install -e ".[dev,ui,semantic]"
```

---

## 🚀 Quick Start

### 1. Stdio MCP Server
Start the stdio MCP server directly from your terminal for any MCP client:

```bash
# Uses current directory as workspace root and default "standalone" session
nagato-mcp-tools

# Specify a custom workspace directory
nagato-mcp-tools --workspace /path/to/your/project

# Multi-project isolation via session ID
nagato-mcp-tools --workspace /path/to/your/project --session-id proj:my-app
# Or via environment variable:
export NAGATO_SESSION_ID="proj:my-app"
nagato-mcp-tools
```

### 2. Standalone WebUI Dashboard
Start the visual dashboard and telemetry server (`pip install "nagato-mcp-tools[ui]"`):

```bash
# Start dashboard on http://127.0.0.1:8080 and open browser
nagato-ui --open-browser

# Specify custom host, port, workspace, and project session
nagato-ui --workspace /path/to/your/project --session-id proj:my-app --port 8085
```

---

## 🗂️ Multi-Project & Session Isolation

When using Nagato tools across multiple repositories/projects, you can prevent cross-project pollution using **formatted `session_id` values**:

* **Project Session**: `proj:<project-name>` (e.g. `proj:backend-api`, `proj:mobile-app`) — isolates audit telemetry and undo snapshots per project.
* **Zero-Config Isolation**: If no `session_id` is provided, one is auto-generated from the workspace path hash (e.g., `ws_a1b2c3d4`), giving each workspace its own isolated undo/redo caches and telemetry.

* **Default Session**: `standalone` (fallback) — single-workspace zero-config default.
* **FSM Ephemeral Session**: Standard UUID4 (e.g. `550e8400-e29b-41d4...`) — managed turn-by-turn orchestration.

All colons, slashes, and illegal path characters in formatted session IDs are automatically sanitized for cross-platform filesystem safety. For example, `proj:my-app` becomes `proj_my-app` on disk. The rewrite is **silent by default**; if you need to see exactly which session IDs are being rewritten, set one of these environment variables before launching the server:

```bash
# Linux / macOS / WSL
export NAGATO_LOG_SESSION_SANITIZE=1
# Or, more broadly (toggles all nagato debug logging):
export NAGATO_DEBUG=1

# Windows PowerShell
$env:NAGATO_LOG_SESSION_SANITIZE = "1"
```

On startup with the toggle on, the standalone router logs a line like:

```
[nagato] standalone router ready: session_id='proj_my-app' (raw='proj:my-app') workspace=/path/to/project
[nagato] session-id sanitized: 'proj:my-app' -> 'proj_my-app'
```

---

## ⏪ Undo/Redo Session & Workspace Isolation

The standalone undo system (`nagato_undo_standalone`) maintains **isolated undo/redo caches per `(workspace, session_id)` pair**. This enables safe concurrent usage by multiple agents:

| Configuration | Session ID | Undo Cache Location | Redo Cache Location |
|---------------|------------|---------------------|---------------------|
| Default (no session_id) | Auto-generated from workspace hash (e.g., `ws_a1b2c3d4`) | `.nagato/sessions/ws_a1b2c3d4/undo_cache/` | `.nagato/sessions/ws_a1b2c3d4/redo_cache/` |
| `NAGATO_SESSION_ID=proj:my-app` | `proj_my-app` (sanitized) | `.nagato/sessions/proj_my-app/undo_cache/` | `.nagato/sessions/proj_my-app/redo_cache/` |
| Explicit `session_id="standalone"` | `standalone` | `.nagato/undo_cache/` | `.nagato/redo_cache/` |

### Concurrency Model

- **Different workspaces**: Naturally isolated by different workspace roots
- **Same workspace, different session_ids**: Isolated via `.nagato/sessions/<session_id>/` — each agent gets its own undo stream
- **Same workspace, same session_id**: Share undo cache (intentional for collaborative editing)

### MCP Client Configuration for Concurrent Agents

Each agent should configure its own `session_id` in `.vscode/mcp.json`:

```json
{
  "servers": {
    "nagato-tools": {
      "type": "stdio",
      "command": "nagato-mcp-tools",
      "args": [
        "--workspace", "${workspaceFolder}",
        "--session-id", "proj:agent-1"
      ]
    }
  }
}
```

Or via environment variable:
```json
{
  "servers": {
    "nagato-tools": {
      "type": "stdio",
      "command": "nagato-mcp-tools",
      "args": ["--workspace", "${workspaceFolder}"],
      "env": {
        "NAGATO_SESSION_ID": "proj:agent-1"
      }
    }
  }
}
```

### Zero-Config Isolation

If no `session_id` is provided, the system auto-generates one from the workspace path hash. This means **each workspace automatically gets isolated undo history** without any configuration.

---

## 🔌 Client Configuration

### 1. VS Code (`.vscode/mcp.json`)
```json
{
  "servers": {
    "nagato-tools": {
      "type": "stdio",
      "command": "nagato-mcp-tools",
      "args": [
        "--workspace", "${workspaceFolder}",
        "--session-id", "proj:my-app"
      ]
    }
  }
}
```

### 2. Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "nagato-tools": {
      "command": "nagato-mcp-tools",
      "args": [
        "--workspace", "/path/to/your/project",
        "--session-id", "proj:my-app"
      ],
      "env": {
        "NAGATO_SESSION_ID": "proj:my-app"
      }
    }
  }
}
```

### 3. Cursor / Windsurf
Add a new stdio MCP server:
- **Command:** `nagato-mcp-tools`
- **Args:** `["--workspace", ".", "--session-id", "proj:my-app"]`

---

## 🤖 Agent Instructions & Prompt Setup

To get the most out of `nagato-mcp-tools`, your AI assistant (Copilot, Cursor, Claude Code, etc.) needs instructions on **how** and **when** to leverage AST navigation, safe edit loops, and undo capabilities.

Copy the included **[`AGENT_INSTRUCTIONS.md`](AGENT_INSTRUCTIONS.md)** into your project configuration:

- **VS Code:** `.github/copilot-instructions.md`
- **Cursor:** `.cursorrules` or `.cursor/rules/nagato.mdc`
- **Claude Code / Claude Desktop:** `CLAUDE.md` or System Prompt
- **Windsurf:** `.windsurfrules`

The instructions guide the LLM to:
1. **Explore first:** Use `nagato_read_signatures` and `nagato_searchAST` instead of reading entire files into context.
2. **Safe edits:** Make surgical edits with `nagato_edit`, immediately run `nagato_lint`, and verify tests.
3. **Rollback easily:** Use `nagato_undo_standalone` if changes fail instead of doing messy manual reversions.

---

## 🛠️ Registered Tools (31 Tools)

| Category | Available Tools | Description |
|---|---|---|
| **Search** | `nagato_searchAST`<br>`nagato_searchInFile`<br>`nagato_searchInFiles`<br>`nagato_find_file`<br>`nagato_semantic_search`<br>`nagato_rebuild_symbol_db`<br>`nagato_set_semantic_search_root` | Search symbols via AST, plain substring search in single/multiple files, filename lookup, and vector semantic search. |
| **Inspection** | `nagato_read_file`<br>`nagato_read_lines`<br>`nagato_list_dir`<br>`nagato_read_signatures`<br>`nagato_extract_callees`<br>`nagato_extract_callers` | Inspect file content and line ranges, extract signatures, and inspect call graphs (callers & callees). |
| **Editing** | `nagato_edit`<br>`nagato_edit_lines`<br>`nagato_delete`<br>`nagato_rename`<br>`nagato_create_dir` | Target exact string replacement, line-range editing, rename/delete files, create directories. |
| **Undo/Redo** | `nagato_undo_standalone` | Granular undo/redo with multi-mode support (steps, time, command, step-target). **Session-scoped**: Each `(workspace, session_id)` pair maintains isolated undo/redo caches under `.nagato/sessions/<session_id>/undo_cache` and `.nagato/sessions/<session_id>/redo_cache`. Default `standalone` session uses `.nagato/undo_cache` and `.nagato/redo_cache`. |
| **Execution** | `nagato_execute_snippet` | Execute Python snippets with subprocess isolation and timeout limits. |
| **Lint & Quality** | `nagato_lint` | Syntax checking and automated Ruff linting. |
| **Testing** | `nagato_run_test`<br>`nagato_run_gold_full`<br>`nagato_run_configured_suite` | Run single pytest test nodes or configured test suites. |
| **Git** | `nagato_git`<br>`nagato_upload` | Git operations (diff, log, status, revert, checkout) and guarded uploads. |
| **Shell** | `nagato_shell`<br>`nagato_shell_str` | Shell command execution (string and structured output). |
| **Web** | `nagato_web_search` | DuckDuckGo web search. |
| **System** | `nagato_is_agent_running` | Agent monitoring. |
| **Creation** | `nagato_generate_uuid4` | UUID generation for session bootstrap. |

---

## 🌐 WebUI Dashboard

The package includes a built-in React/Vite dashboard SPA for visual debugging, real-time audit event streaming, token tracking, and interactive inspection of tool executions and undo/redo history.

### Quick Start
Install the `[ui]` extra and run `nagato-ui`:

```bash
pip install "nagato-mcp-tools[ui]"
nagato-ui --workspace /path/to/target-project --port 8080 --open-browser
```

> **Crucial — Matching `--workspace`**:
> The WebUI dashboard loads telemetry and audit logs from the project directory specified in `--workspace`.
> Ensure that the `--workspace` parameter given to `nagato-ui` matches the `--workspace` path configured in your MCP client (`mcp.json`). If they do not match, the WebUI will monitor a different directory.
>
> *(Note: If you run the full FSM runtime via `python -m fsm.api.server`, it also accepts `--workspace /path/to/target-project` or the `$env:NAGATO_WORKSPACE_ROOT` environment variable).*

### Features
- 📊 **Real-Time Audit Stream**: Live WebSocket event stream of tool dispatches, execution durations, and payloads.
- ⏪ **Undo/Redo Browser**: Visual timeline of file modifications, creations, and deletions with instant rollback status.
- 🪙 **Token Usage Tracking**: Aggregated prompt/completion tokens and interaction breakdown.
- 🔍 **Overview & Health**: Consolidated workspace telemetry metrics and health checks.
- 🔌 **Standalone REST API**: HTTP endpoints (`/api/v1/standalone/*`) for external scripts or custom frontends.

### Building the WebUI from Source
```bash
# From repository root
cd dashboard
npm install
npm run build
# Or sync directly:
python sync_tools.py --build-ui
```

---

## 🔧 Tool Filtering

Control which tools are available via:

### 1. Config File (`.nagato/functions_config.json`)
```json
{
  "tool_filtering": {
    "allowed_categories": ["READ", "SEARCH", "EXECUTE"],
    "denied_tools": ["nagato_shell", "nagato_git", "nagato_upload"]
    // "allowed_tools": ["nagato_read_file", "nagato_searchInFile"]  // Alternative: explicit allowlist
  }
}
```

**Category names** match `ToolCategory` enum: `EDIT`, `TESTING`, `GIT`, `SEARCH`, `WEB`, `READ`, `EXECUTE`, `DEBUGGING`, `SYSTEM`, `SHELL`, `CREATION`, `PLANNING`.

### 2. Explicit Parameters (Override Config)
```python
from nagato_tools.facade import create_standalone_facade
from nagato_tools.tool_categories import ToolCategory

# Explicit params override config file
facade = create_standalone_facade(
    allowed_tools={"nagato_read_file", "nagato_searchInFile"},
    denied_tools={"nagato_shell"},
    allowed_categories=[ToolCategory.READ, ToolCategory.SEARCH],
)
```

### 3. Runtime Control
```python
from nagato_tools.facade import create_standalone_facade

facade = create_standalone_facade()

# Disable/enable individual tools
facade.disable_tool("nagato_shell")
facade.enable_tool("nagato_shell")

# Disable/enable entire categories
facade.disable_category(ToolCategory.SHELL)
facade.enable_category(ToolCategory.READ)

# Custom filter predicate
facade.set_tool_filter(lambda name: not name.startswith("nagato_delete"))

# Inspect current filter status
print(facade.get_filter_status())
```

### Filter Precedence
1. **`denied_tools`** — Absolute block (wins over everything)
2. **`allowed_tools`** — Explicit allowlist (if set, only these tools)
3. **`allowed_categories`** — Category-level allowlist
4. **Default** — All discovered tools

---

## ⚙️ Configuration (`.nagato/functions_config.json`)

Standalone tool behaviors (Semantic Search, Ruff Linting, and Output Truncation) are configured per-workspace via `.nagato/functions_config.json`. Place this file inside the `.nagato/` folder of your project root:

```json
{
  "semantic_search": {
    "db_path": "nagato_codebase.db",
    "embedding_model": "jina",
    "dimension": 768,
    "auto_index": true
  },
  "lint": {
    "enabled": true,
    "soft_mode": true,
    "auto_fix": false,
    "ruff_path": "ruff"
  },
  "tool_token_limits": {
    "default": 20000,
    "read": 20000,
    "search": 20000,
    "web": 10000,
    "shell": 20000
  }
}
```

### 📏 Output Truncation & Token Limits (`tool_token_limits`)

To prevent huge files or unbounded searches from overwhelming LLM context windows, tool outputs (`nagato_read_file`, `nagato_read_lines`, `nagato_searchInFile`, `nagato_searchInFiles`, `nagato_web_search`, `nagato_shell`) are protected by configurable token limits.

- **Default Limits (Standalone)**: 20,000 tokens for inspection, search, editing, and execution (providing ample room for large files while safeguarding against runaway memory dumps).
- **Custom Limits**: Set category-specific limits (e.g. `"read": 40000`) or a blanket `"default": 50000` under `tool_token_limits` in `.nagato/functions_config.json`.
- **Disable Truncation Completely**: Set a category or `"default"` to `0`, `null`, or `"unlimited"` (e.g. `"tool_token_limits": {"default": 0}`).
- **Truncation Notice**: When truncated, outputs append `[TRUNCATED: X tokens omitted]`.

> **Important — Workspace Configuration Location**:
> The `.nagato/functions_config.json` file is loaded **relative to the target `--workspace` directory**, NOT from the directory where the MCP server / tool package is installed!
>
> For example, in your VS Code / Claude `mcp.json`:
> ```json
> "nagato-tools": {
>   "type": "stdio",
>   "command": "nagato-mcp-tools",
>   "args": ["--workspace", "/path/to/target-project"]
> }
> ```
> Nagato will look for `/path/to/target-project/.nagato/functions_config.json`.

---

### 📋 Complete Configuration Example

Here's a full `.nagato/functions_config.json` showing all available options:

```json
{
  "tool_filtering": {
    "denied_tools": ["nagato_shell", "nagato_upload"],
    "allowed_categories": ["READ", "SEARCH", "EXECUTE", "EDIT"],
    "allowed_tools": []
  },
  "insight": {
    "enabled": true,
    "embedding_provider": "fastembed",
    "embedding_model": "jinaai/jina-embeddings-v2-base-code",
    "embedding_dimension": 768
  },
  "semantic_search": {
    "db_path": "nagato_codebase.db",
    "embedding_model": "jina",
    "dimension": 768,
    "auto_index": true
  },
  "lint": {
    "enabled": true,
    "soft_mode": true,
    "auto_fix": false,
    "ruff_path": "ruff"
  },
  "tool_token_limits": {
    "default": 20000,
    "read": 50000,
    "search": "unlimited",
    "shell": 0
  }
}
```

**Key Points:**
- **`tool_filtering`** — Controls which tools are available (see [Tool Filtering](#-tool-filtering))
- **`insight`** — Enables the knowledge graph (requires `[semantic]` extra)
- **`semantic_search`** — Vector search configuration
- **`lint`** — Ruff linting behavior
- **`tool_token_limits`** — Output truncation per category (0 = unlimited)

All paths are relative to the `--workspace` directory.
---


---

## 🧠 Semantic Search (Optional)

Semantic search uses `fastembed` (embeddings) and `sqlite-vec` (vector database).

1. Install semantic extras:
   ```bash
   pip install "nagato-mcp-tools[semantic]"
   ```
2. Build the vector database by calling `nagato_rebuild_symbol_db` from your MCP client.
3. For model choices (Jina vs. BAAI) and database configuration, see [SEMANTIC_SEARCH_SETUP.md](SEMANTIC_SEARCH_SETUP.md).

---

## 🏗️ Architecture

```mermaid
graph TD
    Client["MCP Client (VS Code, Claude, Cursor)"] -->|stdio JSON-RPC| Server["NagatoMCPServer (nagato_mcp_tools)"]
    Server --> Facade["ToolFacade (nagato_tools.facade)"]
    Facade --> Context["MockFSMContext (Standalone)"]
    Facade --> Tools["Tool Modules (search, edit, read, test, etc.)"]
```

---

## 🧪 Development & Testing

```bash
# Run test suite
pytest

# Run tests with coverage
pytest --cov=nagato_tools --cov=nagato_mcp_tools
```

---

## 📄 License

Distributed under the [MIT License](LICENSE).
