Skip to main content

NetArk (netark-mcp)

Zero-Dependency Deterministic AI Coding Harness & Portable Markdown Governance MCP.

CI Python 3.10+ Dependencies: 0 MCP Tools: 3 License: Apache-2.0

English | 繁體中文

NetArk gives AI coding agents (Claude Code, Google Antigravity, Pi Agent, and custom MCP hosts) deterministic pre-write AST/secret guardrails and a Git-portable Markdown memory graph — packaged as a single pure-stdlib Python CLI (netark-mcp) with 0 runtime files dropped into your repository.

NetArk Dual-Plane Architecture: Hook-First Deterministic Guardrails and 3-Tool Lean MCP


Key Engineering Benchmarks

Metric Value Why It Matters
MCP Context Footprint 3 Tools (< 220 Tokens) Keeps tool-schema overhead near zero (netark_query, netark_record, netark_guard).
Runtime Dependencies 0 External Packages Pure Python 3.10+ standard library; no vector DB, Docker, or Node.js runtime required.
Pre-Write Hook Latency ~62ms (PreToolUse) Deterministic AST nesting, silent-except, secret DLP, and shell inspection before disk writes.
Turn-1 Context Compression 95.7% Token Saved Compresses multi-node specs & AST edges into a frozen @D/@M/@C/@G map (5.2 KB).

30-Second Quickstart (uv / uvx)

Install netark-mcp directly from GitHub for full Hooks + MCP, or run uvx for MCP-only (once v3.2.0 is published on PyPI, uv tool install netark-mcp also works directly):

# 1. Install globally from GitHub (recommended for native-speed PreToolUse hooks)
uv tool install git+https://github.com/joinblue/NetArk
# Or once published on PyPI:
# uv tool install netark-mcp

# 2. Initialize your project (creates 0 .py files inside your repo)
cd /path/to/your-project
netark-mcp init --lang en --cwd .
Choose Your Host Setup (Default Memory / Claude Code / AGY / Pi Agent & Custom Hosts)
  • Default — Zero Host Intrusion (--target memory):

    netark-mcp init --cwd .
    

    Creates/merges only .mcp.json, policy config, and starter memory/ nodes without touching host rules or hook files.

  • Claude Code (--target claude):

    netark-mcp init --target claude --lang en --cwd .
    

    Non-destructively merges .mcp.json, .claude/settings.json (SessionStart, PreToolUse, PostToolUse, Stop), and .claude/commands/.

  • Google Antigravity / AGY (--target agy):

    netark-mcp init --target agy --lang en --cwd .
    

    Wires .agents/hooks.json, .agents/plugins/netark/mcp_config.json, .agents/enterprise-policy.json, .agents/skills/, and .agents/workflows/.

  • Pi Agent / Custom MCP Hosts (uvx + Universal Hook Contract):

    {
      "mcpServers": {
        "netark": {
          "command": "uvx",
          "args": ["--from", "git+https://github.com/joinblue/NetArk", "netark-mcp", "serve", "--cwd", "."]
        }
      }
    }
    

    Then instruct your agent to call netark_guard(action="setup") (or inspect docs/HOOK_CONTRACT.md) to wire the stdin/stdout hook bridge.


How It Works (Hooks + 3-Tool Closed Loop)

flowchart LR
    S["SessionStart Hook<br/>Inject Frozen @D/@M/@C/@G Map"] --> Q["1. Query Before Edit<br/>netark_query(query)"]
    Q --> P["2. PreToolUse Hook (~62ms)<br/>Secret DLP + AST P1-P4 + RIBC Gate"]
    P -->|"DENY + [RuleDoc] Fix"| Q
    P -->|"ALLOW"| W["3. Governed Write & Verify<br/>netark_record / PostToolUse / netark_guard(oracle)"]
    W --> S

1. Deterministic Pre-Write Guardrails (~62ms)

Stops hardcoded credentials (SEC-PREWRITE-SECRET), .env / vault reads (SEC-CRED), silent except: pass (CODE-SILENT-EXCEPT), deep arrow nesting (CODE-ARROW-NESTING), destructive shell subshells, and unguarded subagent dispatches — returning structured [RuleDoc] and [SuggestedAlternative] remediation so the agent fixes itself in one turn.

NetArk Pre-Write Guard Terminal Demo: Intercepting Hardcoded Secrets & AST Anti-Patterns

(Also available as an animated terminal sequence, or regenerate locally with scripts/render_assets/ / demo-prewrite-guard.tape.)

2. Turn-1 @D/@M/@C/@G Context Compression (95.7% Saved)

Instead of flooding every prompt with raw Markdown specs and source files, SessionStart injects a frozen compact directory/node/script/dependency codebook (5.2 KB). Prefix caches remain intact while netark_query resolves exact 1-hop node summaries and AST neighbors on demand.

NetArk Turn-1 Token Compression Comparison (-95.7%)

3. Stub-First Governance Lifecycle & Spec ↔ Code Alignment

Tracks every change from draft ➔ reviewing ➔ stub_ready ➔ verified ➔ archived. STUB-FIRST-GATE and SPEC-AST-SYNC-GATE prevent agents from inventing modules without an approved spec or drifting from declared AST symbols.

NetArk Causal Topology & Governance State Dashboard


3 High-Cohesion MCP Tools

Tool Purpose Key Inputs
netark_query O(1) codebook lookup & 1-hop AST/DAG neighbor resolution query, project_id (optional)
netark_record Schema-validated memory authoring (preflight dry-run or atomic write) intent, title, body, mode (preflight | write), affected_paths, parent_blueprint
netark_guard Policy health check, full-repo DAG oracle, handover audit, or Hook contract action (status | oracle | handover | setup)

How NetArk Compares to the Ecosystem

Approach External DB / Runtime Pre-Write AST & Secret Hooks Spec ↔ Code Drift & Stub Gate Prefix-Cache Safe Turn-1 Map
NetArk (netark-mcp) None (Python 3.10+ Stdlib) Yes (~62ms deterministic) Yes (STUB-FIRST + oracle) Yes (@D/@M/@C/@G, 95.7% saved)
Raw CLAUDE.md / AGENTS.md None No (advisory prompt only) No Degrades as docs grow
Vector / Graph Memory MCP (Mem0, Zep) Vector DB / Graph DB / LLM API No No Dynamic retrieval can churn context
LSP Symbol MCP (Serena) Language Servers No Symbol lookup only No governance lifecycle


Licensed under the Apache License 2.0.

Metadata

Release files for netark-mcp 3.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for netark-mcp 3.2.0
File Size Uploaded Provenance Actions
netark_mcp-3.2.0.tar.gz 2.2 MB With provenance Details for netark_mcp-3.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for netark-mcp 3.2.0
File Interpreter ABI Platform Actions
netark_mcp-3.2.0-py3-none-any.whl Python 3 none any Details for netark_mcp-3.2.0-py3-none-any.whl

Total release size: 2.5 MB

Release files / netark_mcp-3.2.0.tar.gz

Download URL netark_mcp-3.2.0.tar.gz
Size 2.2 MB
Tags Source
SHA-256 checksum
How to use checksums
3baca3c3ab1c6c866d85d956e3dbf2474f5ef11d208d48c56d956c18feb2c70e
BLAKE2b-256 checksum
How to use checksums
14f5af86a4ddaeaa744bbbe68265c7c1bf8ae24c33420175d117af5403905658
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / netark_mcp-3.2.0-py3-none-any.whl

Download URL netark_mcp-3.2.0-py3-none-any.whl
Size 262.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
50636122ef07e01ff420a0d04ba75a967aa01bace7c570531234d9f0277ed57e
BLAKE2b-256 checksum
How to use checksums
e89849be16249dd27c8f7eb06854bce7c783c764aa7ae1864483506df429ef3c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for netark-mcp 3.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for netark_mcp-3.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page