nc-tools — the Typed Machine API for coding agents

A terminal-free machine interface: every operation the terminal used to provide (files, search, patches, git, processes, tests, packages, network) is a typed tool with structured inputs, structured outputs, structured errors, and a full append-only event journal. One static Rust binary speaks MCP over stdio.

Thesis: the terminal is the machine's untyped API. Replace it with a typed one and agents become verifiable, replayable, measurable, and safer — without changing their model or harness.

Quick start

Requires Rust (stable) and Node ≥ 20 (for the test/dev harnesses only — the kernel itself has zero runtime dependencies).

git clone https://github.com/ncdevshiv/nc-tools.git
cd nc-tools
cargo build --release -p nct-mcp        # → target/release/nc-tools-mcp(.exe)
npm run conform                          # 27 protocol conformance cases, black-box

Mount it in any MCP client (ZCode, Claude Desktop, Cursor-style hosts, custom loops) — see docs/MCP-CONFIG.md. Point the command at target/release/nc-tools-mcp with your workspace root as the only argument, or run npm run install:bin to copy it to ~/.local/bin and use that stable path.

Related MCP server: core-agent-mcp

What's in the box

The tool surface (60 typed tools)

• fs.* — read/readMany/readRange, write/writeMany, append, copy, list, tree, stat, mkdir, delete, move

• patch.apply/applyMany — search/replace edits with exactness guards

• search.grep/files/replace/semantic, code.symbols, text.diff

• git.status/diff/add/blame/commit/log/branch/checkout/push/pull

• proc.spawn/start/status/readOutput/stop/list/kill/runScript/watch — argv-typed, no shell

• test.run (node, pytest), pkg.add/list/scripts/runScript

• net.http/probePort/fetch/robots/search — see docs/INTERNET-TOOLS.md

• env.get/set/list, sys.snapshot/rollback/listSnapshots/journal/workspace/doctor, batch.execute

The frozen machine-readable export is conformance/golden/tools.json (regenerate with npm run golden; changes must be deliberate). The full contract — error taxonomy, journal schema, transport bindings — is docs/PROTOCOL.md.

Principles

1. Typed in, typed out. Tools return structured results and structured errors with machine-readable remediation hints. No stdout scraping.

2. Everything is journaled. Every tool call and result is an event in <workspace>/.nc-tools/journal.jsonl. Sessions are replayable and auditable.

3. Mutations are deliberate. Writes go through validated patches (search/replace blocks with occurrence counts). No silent overwrites.

4. No shell. There is no exec/bash tool. proc.spawn is argv-typed. If a task requires a shell, that is a tool to design, not an escape hatch.

Verification gates

Every claim in this repo is machine-checked:

cargo test                       # Rust unit + integration suites
npm run test:node                # black-box protocol/behavior suite over MCP stdio
npm run conform                  # language-neutral conformance (27 cases)
npm run crossaudit               # audits THIS repo through its own MCP server
npm run audit                    # stub/TODO/mock/placeholder scan (exit 1 on findings)
npm run verify:verifiers         # bench verifiers: untouched→fail, solved→pass, wrong→rejected

License

MIT