NetArk (netark-mcp)
Zero-Dependency Deterministic AI Coding Harness & Portable Markdown Governance MCP.
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.
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 startermemory/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.
(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.
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.
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 |
Documentation & Links
- Quickstart & Multi-Host Setup —
uv/uvxsetup,--targetmodes, non-destructive merging, and uninstall. - Universal Hook CLI Contract — 5 lifecycle hooks, JSON stdin contract, and
agy/claude/pidialects. - Security Guardrails & Remediation Reference — Immutable core rules,
enterprise-policy.jsonschema, and guard code guide. - Contributing & Security Policy — Zero-dependency development guidelines (Apache-2.0, no CLA friction).
- Looking for the early TypeScript Pi Coding Agent prototype? See NetArk-preview.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.