🛠️ nagato-mcp-tools

Agent-First MCP Toolkit — 31 code search, editing, execution, and analysis tools exposed directly over the Model Context Protocol (MCP). Fully standalone and compatible with any MCP client (VS Code, Claude Desktop, Cursor, etc.).

Licensed under the MIT License. See 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

pip install nagato-mcp-tools

With Semantic Search (Vector Embeddings)

pip install "nagato-mcp-tools[semantic]"

With WebUI Dashboard (Live Monitoring & Audit)

pip install "nagato-mcp-tools[ui]"

All Extras (Semantic + WebUI)

pip install "nagato-mcp-tools[semantic,ui]"

Editable Installation (Development)

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:

# 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]"):

# 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:

# 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:

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

Or via environment variable:

{
  "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)

{
  "servers": {
    "nagato-tools": {
      "type": "stdio",
      "command": "nagato-mcp-tools",
      "args": [
        "--workspace", "${workspaceFolder}",
        "--session-id", "proj:my-app"
      ]
    }
  }
}

2. Claude Desktop (claude_desktop_config.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 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 nagato_searchInFile nagato_searchInFiles nagato_find_file nagato_semantic_search nagato_rebuild_symbol_db 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 nagato_read_lines nagato_list_dir nagato_read_signatures nagato_extract_callees nagato_extract_callers	Inspect file content and line ranges, extract signatures, and inspect call graphs (callers & callees).
Editing	nagato_edit nagato_edit_lines nagato_delete nagato_rename 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 nagato_run_gold_full nagato_run_configured_suite	Run single pytest test nodes or configured test suites.
Git	nagato_git nagato_upload	Git operations (diff, log, status, revert, checkout) and guarded uploads.
Shell	nagato_shell 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:

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

# 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)

{
  "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)

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

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:

{
  "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:

"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:

{
  "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)
• 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:

   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.

---

🏗️ Architecture

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

# Run test suite
pytest

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

---

📄 License

Distributed under the MIT License.