NTS_MCP_FS

NTS_MCP_FS is an enterprise-grade MCP File System server that turns standard file operations into a transactional, optimistic-locked environment for AI agents. It provides line-accurate access control via Line Access Tokens (LATs), a persistent Heads-Up Display (HUD) in tool responses, programmable atomic batches for multi-file scripting, and a built-in persistence layer (H2 database) to survive restarts. Tools exposed by the server include a suite of nts_* utilities such as nts_file_manage for file operations, nts_edit_file for diff-driven edits, nts_batch_tools for atomic scripting, and nts_code_refactor for semantic changes across projects. The server supports safe multi-step edits with diffs returned in responses, making it ideal for long-running AI agent sessions that require precise state management and rollback capabilities. To interact with the server, you issue MCP commands that the server translates into transactional file-system actions, observe the HUD in each response, and leverage programmable batches to chain operations atomically.

Prerequisites:

• Docker installed and running, or a Java-enabled environment if you opt for non-Docker deployment.
• Optional: git, curl, and a Java install if building from source.

Recommended deployment method (Docker):

1. Ensure Docker is installed and running.
2. Pull and run the MCP server container (as shown in the README): docker pull nefrols/nts_mcp_fs:latest docker run -i nefrols/nts_mcp_fs:latest

Alternative (Java-based build from source):

1. Prerequisites: JDK 17+ and Maven or Gradle.
2. Clone the repository: git clone https://github.com/yourorg/nts_mcp_fs.git cd nts_mcp_fs
3. Build the project (example with Maven): mvn -q -DskipTests package
4. Run the built JAR (example): java -jar target/nts-mcp-fs-jar-with-dependencies.jar

Prerequisites recap:

• Docker or Java runtime (JDK 17+)
• Git for cloning repositories
• Maven/Gradle for building from source (if not using Docker)

Note: The README indicates Docker readiness. If you use Docker, the recommended command is to pull and run nefrols/nts_mcp_fs:latest as described above.

Tips and common issues:

• If LATs fail to appear or tokens expire, ensure the file being edited has not been altered outside of the expected workflow, as LATs enforce optimistic locking.
• Use nts_batch_tools to perform multi-step operations atomically; if any step fails, the entire batch rolls back.
• The HUD in responses provides task context, progress, and safety stats to help you manage long AI agent sessions.
• When running in Docker, consider mounting a persistent volume for the H2 database to survive container restarts, e.g., -v /path/to/data:/data.
• Settings like JAVA_OPTS and NTS_MCP_FS_LOG_LEVEL can help tune performance and observability in production.
• For debugging, enable DEBUG level logging and review container logs to diagnose issues with file operations or token validation.